When a package tests more than a few 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. It should be called 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). Use #include config.h instead of #include "config.h", and pass the C compiler a -I. option (or -I..; whichever directory contains config.h). That way, even if the source directory is configured itself (perhaps to make a distribution), other build directories can also be configured without finding the config.h from the source directory.
function>AC_CONFIG_HEADERS/function> (header …, [cmds], [init-cmds]) This macro is one of the instantiating macros, see the section called “Taking Configuration Actions”. Make AC_OUTPUT create the file(s) in the whitespace-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.
If header already exists and its contents are identical to what AC_OUTPUT would put in it, it is left alone. Doing this allows some changes in 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. Examples:
AC_CONFIG_HEADERS([config.h:config.hin]) AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
Doing this allows you to keep your file names acceptable to MS-DOS, or to prepend and/or append boilerplate to the file.
the section called “Taking Configuration Actions”, for more details on header.
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. On systems that have unistd.h, configure will #defineHAVE_UNISTD_H to 1. On other systems, the whole line will be commented out (in case the system predefines that symbol).
/* Define as 1 if you have unistd.h. */ #undef HAVE_UNISTD_H
You can then decode the configuration header using the preprocessor directives:
#include conf.h #if HAVE_UNISTD_H # include unistd.h #else /* We are in trouble. */ #endif
The use of old form templates, with #define instead of #undef is strongly discouraged.
Since it is a tedious task to keep a template header up to date, you may use autoheader to generate it, see the section called “Using autoheader to Create config.h.in”.
The autoheader program can create a template file of C #define statements for configure to use. If configure.ac invokes AC_CONFIG_HEADERS(file), autoheader creates file.in; if multiple file arguments are given, the first one is used. Otherwise, autoheader creates config.h.in.
In order to do its job, autoheader needs you to document all of the symbols that you might use; i.e., there must be at least one AC_DEFINE or one AC_DEFINE_UNQUOTED using its third argument for each symbol (the section called “Defining C Preprocessor Symbols”). An additional constraint is that the first argument of AC_DEFINE must be a literal. Note that all symbols defined by Autoconf's built-in tests are already documented properly; you only need to document those that you define yourself.
You might wonder why autoheader is needed: after all, why would configure need to "patch" a config.h.in to produce a config.h instead of just creating config.h from scratch? Well, when everything rocks, the answer is just that we are wasting our time maintaining autoheader: generating config.h directly is all that is needed. When things go wrong, however, you'll be thankful for the existence of autoheader.
The fact that the symbols are documented is important in order to check that config.h makes sense. The fact that there is a well defined list of symbols that should be #define'd (or not) is also important for people who are porting packages to environments where configure cannot be run: they just have to fill in the blanks.
But let's come back to the point: autoheader's invocation…
If you give autoheader an argument, it uses that file instead of configure.ac and writes the header file to the standard output instead of to config.h.in. If you give autoheader an argument of -, it reads the standard input instead of configure.ac and writes the header file to the standard output.
autoheader accepts the following options:
Print a summary of the command line options and exit.
Print the version number of Autoconf and exit.
Report processing steps.
Don't remove the temporary files.
Remake the template file even if newer than its input files.
Also look for input files in dir. Multiple invocations accumulate. Directories are browsed from last to first.
Report the warnings related to category (which can actually be a comma separated list). Current categories include:
report the uses of obsolete constructs
report all the warnings
report none
treats warnings as errors
disable warnings falling into category
autoheader scans configure.ac and figures out which C preprocessor symbols it might define. It knows how to generate templates for symbols defined by AC_CHECK_HEADERS, AC_CHECK_FUNCS etc., but if you AC_DEFINE any additional symbol, you must define a template for it. If there are missing templates, autoheader fails with an error message.
The simplest way to create a template for a symbol is to supply the description argument to an AC_DEFINE(symbol); see the section called “Defining C Preprocessor Symbols”. You may also use one of the following macros.
function>AH_VERBATIM/function> (key, template) Tell autoheader to include the template as-is in the header template file. This template is associated with the key, which is used to sort all the different templates and guarantee their uniqueness. It should be the symbol that can be AC_DEFINE'd.
For example:
AH_VERBATIM([_GNU_SOURCE], [/* Enable GNU extensions on systems that have them. */ #ifndef _GNU_SOURCE # define _GNU_SOURCE #endif])
function>AH_TEMPLATE/function> (key, description) Tell autoheader to generate a template for key. This macro generates standard templates just like AC_DEFINE when a description is given.
For example:
AH_TEMPLATE([CRAY_STACKSEG_END], [Define to one of _getb67, GETB67, getb67 for Cray-2 and Cray-YMP systems. This function is required for alloca.c support on those systems.])
will generate the following template, with the description properly justified.
/* Define to one of _getb67, GETB67, getb67 for Cray-2 and Cray-YMP systems. This function is required for alloca.c support on those systems. */ #undef CRAY_STACKSEG_END
function>AH_TOP/function> (text) Include text at the top of the header template file.
function>AH_BOTTOM/function> (text) Include text at the bottom of the header template file.