autoconf: Header Templates

1 
1 4.9.1 Configuration Header Templates
1 ------------------------------------
1 
1 Your distribution should contain a template file that looks as you want
1 the final header file to look, including comments, with `#undef'
1 statements which are used as hooks.  For example, suppose your
1 `configure.ac' makes these calls:
1 
1      AC_CONFIG_HEADERS([conf.h])
1      AC_CHECK_HEADERS([unistd.h])
1 
1 Then you could have code like the following in `conf.h.in'.  The
1 `conf.h' created by `configure' defines `HAVE_UNISTD_H' to 1, if and
1 only if the system has `unistd.h'.
1 
1      /* Define as 1 if you have unistd.h.  */
1      #undef HAVE_UNISTD_H
1 
1    The format of the template file is stricter than what the C
1 preprocessor is required to accept.  A directive line should contain
1 only whitespace, `#undef', and `HAVE_UNISTD_H'.  The use of `#define'
1 instead of `#undef', or of comments on the same line as `#undef', is
1 strongly discouraged.  Each hook should only be listed once.  Other
1 preprocessor lines, such as `#ifdef' or `#include', are copied verbatim
1 from the template into the generated header.
1 
1    Since it is a tedious task to keep a template header up to date, you
1 may use `autoheader' to generate it, see ⇒autoheader Invocation.
1 
1    During the instantiation of the header, each `#undef' line in the
1 template file for each symbol defined by `AC_DEFINE' is changed to an
1 appropriate `#define'. If the corresponding `AC_DEFINE' has not been
1 executed during the `configure' run, the `#undef' line is commented
1 out.  (This is important, e.g., for `_POSIX_SOURCE': on many systems,
1 it can be implicitly defined by the compiler, and undefining it in the
1 header would then break compilation of subsequent headers.)
1 
1    Currently, _all_ remaining `#undef' lines in the header template are
1 commented out, whether or not there was a corresponding `AC_DEFINE' for
1 the macro name; but this behavior is not guaranteed for future releases
1 of Autoconf.
1 
1    Generally speaking, since you should not use `#define', and you
1 cannot guarantee whether a `#undef' directive in the header template
1 will be converted to a `#define' or commented out in the generated
1 header file, the template file cannot be used for conditional
1 definition effects.  Consequently, if you need to use the construct
1 
1      #ifdef THIS
1      # define THAT
1      #endif
1 
1 you must place it outside of the template.  If you absolutely need to
1 hook it to the config header itself, please put the directives to a
1 separate file, and `#include' that file from the config header
1 template.  If you are using `autoheader', you would probably use
1 `AH_BOTTOM' to append the `#include' directive.
1