4.9.1 Configuration Header Templates

Your distribution should contain a template file that looks as you want the final header file to look, including comments, with #undef statements which are used as hooks. For example, suppose your configure.ac makes these calls:

     AC_CONFIG_HEADERS([conf.h])
     AC_CHECK_HEADERS([unistd.h])

Then you could have code like the following in conf.h.in. The conf.h created by configure defines `HAVE_UNISTD_H' to 1, if and only if the system has unistd.h.

     /* Define as 1 if you have unistd.h.  */
     #undef HAVE_UNISTD_H

The format of the template file is stricter than what the C preprocessor is required to accept. A directive line should contain only whitespace, `#undef', and `HAVE_UNISTD_H'. The use of `#define' instead of `#undef', or of comments on the same line as `#undef', is strongly discouraged. Each hook should only be listed once. Other preprocessor lines, such as `#ifdef' or `#include', are copied verbatim from the template into the generated header.

Since it is a tedious task to keep a template header up to date, you may use autoheader to generate it, see autoheader Invocation.

During the instantiation of the header, each `#undef' line in the template file for each symbol defined by `AC_DEFINE' is changed to an appropriate `#define'. If the corresponding `AC_DEFINE' has not been executed during the configure run, the `#undef' line is commented out. (This is important, e.g., for `_POSIX_SOURCE': on many systems, it can be implicitly defined by the compiler, and undefining it in the header would then break compilation of subsequent headers.)

Currently, all remaining `#undef' lines in the header template are commented out, whether or not there was a corresponding `AC_DEFINE' for the macro name; but this behavior is not guaranteed for future releases of Autoconf.

Generally speaking, since you should not use `#define', and you cannot guarantee whether a `#undef' directive in the header template will be converted to a `#define' or commented out in the generated header file, the template file cannot be used for conditional definition effects. Consequently, if you need to use the construct

     #ifdef THIS
     # define THAT
     #endif

you must place it outside of the template. If you absolutely need to hook it to the config header itself, please put the directives to a separate file, and `#include' that file from the config header template. If you are using autoheader, you would probably use `AH_BOTTOM' to append the `#include' directive.