File: autoconf.info,  Node: Configuration Headers,  Next: Configuration Commands,  Prev: Makefile Substitutions,  Up: Setup

4.9 Configuration Header Files
==============================

When a package contains more than a few tests that define C preprocessor
symbols, the command lines to pass ‘-D’ options to the compiler can get
quite long.  This causes two problems.  One is that the ‘make’ output is
hard to visually scan for errors.  More seriously, the command lines can
exceed the length limits of some operating systems.  As an alternative
to passing ‘-D’ options to the compiler, ‘configure’ scripts can create
a C header file containing ‘#define’ directives.  The
‘AC_CONFIG_HEADERS’ macro selects this kind of output.  Though it can be
called anywhere between ‘AC_INIT’ and ‘AC_OUTPUT’, it is customary to
call it right after ‘AC_INIT’.

   The package should ‘#include’ the configuration header file before
any other header files, to prevent inconsistencies in declarations (for
example, if it redefines ‘const’, or if it defines a macro like
‘_FILE_OFFSET_BITS’ that affects the behavior of system headers).  Note
that it is okay to only include ‘config.h’ from ‘.c’ files; the
project's ‘.h’ files can rely on ‘config.h’ already being included first
by the corresponding ‘.c’ file.

   To provide for VPATH builds, remember to pass the C compiler a ‘-I.’
option (or ‘-I..’; whichever directory contains ‘config.h’).  Even if
you use ‘#include "config.h"’, the preprocessor searches only the
directory of the currently read file, i.e., the source directory, not
the build directory.

   With the appropriate ‘-I’ option, you can use ‘#include ’.
Actually, it's a good habit to use it, because in the rare case when the
source directory contains another ‘config.h’, the build directory should
be searched first.

 -- Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS])
     This macro is one of the instantiating macros; see *note
     Configuration Actions::.  Make ‘AC_OUTPUT’ create the file(s) in
     the blank-or-newline-separated list HEADER containing C
     preprocessor ‘#define’ statements, and replace ‘@DEFS@’ in
     generated files with ‘-DHAVE_CONFIG_H’ instead of the value of
     ‘DEFS’.  The usual name for HEADER is ‘config.h’; HEADER should not
     contain shell metacharacters.  *Note Special Chars in Variables::.

     If HEADER already exists and its contents are identical to what
     ‘AC_OUTPUT’ would put in it, it is left alone.  Doing this allows
     making some changes in the configuration without needlessly causing
     object files that depend on the header file to be recompiled.

     Usually the input file is named ‘HEADER.in’; however, you can
     override the input file name by appending to HEADER a
     colon-separated list of input files.  For example, you might need
     to make the input file name acceptable to DOS variants:

          AC_CONFIG_HEADERS([config.h:config.hin])

 -- Macro: AH_HEADER
     This macro is defined as the name of the first declared config
     header and undefined if no config headers have been declared up to
     this point.  A third-party macro may, for example, require use of a
     config header without invoking AC_CONFIG_HEADERS twice, like this:

          AC_CONFIG_COMMANDS_PRE(
                  [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])

   *Note Configuration Actions::, for more details on HEADER.

* Menu:

* Header Templates::            Input for the configuration headers
* autoheader Invocation::       How to create configuration templates
* Autoheader Macros::           How to specify CPP templates