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