standards: Conditional Changes

1 
1 6.8.4 Conditional Changes
1 -------------------------
1 
1 Source files can often contain code that is conditional to build-time or
1 static conditions.  For example, C programs can contain compile-time
1 '#if' conditionals; programs implemented in interpreted languages can
1 contain module imports of function definitions that are only performed
1 for certain versions of the interpreter; and Automake 'Makefile.am'
1 files can contain variable definitions or target declarations that are
1 only to be considered if a configure-time Automake conditional is true.
1 
1    Many changes are conditional as well: sometimes you add a new
1 variable, or function, or even a new program or library, which is
1 entirely dependent on a build-time condition.  It is useful to indicate
1 in the change log the conditions for which a change applies.
1 
1    Our convention for indicating conditional changes is to use _square
1 brackets around the name of the condition_.
1 
1    Conditional changes can happen in numerous scenarios and with many
1 variations, so here are some examples to help clarify.  This first
1 example describes changes in C, Perl, and Python files which are
1 conditional but do not have an associated function or entity name:
1 
1      * xterm.c [SOLARIS2]: Include <string.h>.
1      * FilePath.pm [$^O eq 'VMS']: Import the VMS::Feature module.
1      * framework.py [sys.version_info < (2, 6)]: Make "with" statement
1        available by importing it from __future__,
1        to support also python 2.5.
1 
1    Our other examples will for simplicity be limited to C, as the minor
1 changes necessary to adapt them to other languages should be
1 self-evident.
1 
1    Next, here is an entry describing a new definition which is entirely
1 conditional: the C macro 'FRAME_WINDOW_P' is defined (and used) only
1 when the macro 'HAVE_X_WINDOWS' is defined:
1 
1      * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
1 
1    Next, an entry for a change within the function 'init_display', whose
1 definition as a whole is unconditional, but the changes themselves are
1 contained in a '#ifdef HAVE_LIBNCURSES' conditional:
1 
1      * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
1 
1    Finally, here is an entry for a change that takes effect only when a
1 certain macro is _not_ defined:
1 
1      * host.c (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
1