cpp: Ifdef
1
1 4.2.1 Ifdef
1 -----------
1
1 The simplest sort of conditional is
1
1 #ifdef MACRO
1
1 CONTROLLED TEXT
1
1 #endif /* MACRO */
1
1 This block is called a "conditional group". CONTROLLED TEXT will be
1 included in the output of the preprocessor if and only if MACRO is
1 defined. We say that the conditional "succeeds" if MACRO is defined,
1 "fails" if it is not.
1
1 The CONTROLLED TEXT inside of a conditional can include preprocessing
1 directives. They are executed only if the conditional succeeds. You
1 can nest conditional groups inside other conditional groups, but they
1 must be completely nested. In other words, '#endif' always matches the
1 nearest '#ifdef' (or '#ifndef', or '#if'). Also, you cannot start a
1 conditional group in one file and end it in another.
1
1 Even if a conditional fails, the CONTROLLED TEXT inside it is still
1 run through initial transformations and tokenization. Therefore, it
1 must all be lexically valid C. Normally the only way this matters is
1 that all comments and string literals inside a failing conditional group
1 must still be properly ended.
1
1 The comment following the '#endif' is not required, but it is a good
1 practice if there is a lot of CONTROLLED TEXT, because it helps people
1 match the '#endif' to the corresponding '#ifdef'. Older programs
1 sometimes put MACRO directly after the '#endif' without enclosing it in
1 a comment. This is invalid code according to the C standard. CPP
1 accepts it with a warning. It never affects which '#ifndef' the
1 '#endif' matches.
1
1 Sometimes you wish to use some code if a macro is _not_ defined. You
1 can do this by writing '#ifndef' instead of '#ifdef'. One common use of
1 '#ifndef' is to include code only the first time a header file is
1 included. ⇒Once-Only Headers.
1
1 Macro definitions can vary between compilations for several reasons.
1 Here are some samples.
1
11 * Some macros are predefined on each kind of machine (⇒
System-specific Predefined Macros). This allows you to provide
1 code specially tuned for a particular machine.
1
1 * System header files define more macros, associated with the
1 features they implement. You can test these macros with
1 conditionals to avoid using a system feature on a machine where it
1 is not implemented.
1
1 * Macros can be defined or undefined with the '-D' and '-U'
1 command-line options when you compile the program. You can arrange
1 to compile the same source file into two different programs by
1 choosing a macro name to specify which program you want, writing
1 conditionals to test whether or how this macro is defined, and then
1 controlling the state of the macro with command-line options,
1 perhaps set in the Makefile. ⇒Invocation.
1
1 * Your program might have a special header file (often called
1 'config.h') that is adjusted when the program is compiled. It can
1 define or not define macros depending on the features of the system
1 and the desired capabilities of the program. The adjustment can be
1 automated by a tool such as 'autoconf', or done by hand.
1