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