6.8.4 Conditional Changes

Source files can often contain code that is conditional to build-time or static conditions. For example, C programs can contain compile-time #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 init_display, whose definition as a whole is unconditional, but the changes themselves are contained in a ‘#ifdef HAVE_LIBNCURSES’ conditional:

* 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.