autoconf: autoheader Invocation
1
1 4.9.2 Using `autoheader' to Create `config.h.in'
1 ------------------------------------------------
1
1 The `autoheader' program can create a template file of C `#define'
1 statements for `configure' to use. It searches for the first
1 invocation of `AC_CONFIG_HEADERS' in `configure' sources to determine
1 the name of the template. (If the first call of `AC_CONFIG_HEADERS'
1 specifies more than one input file name, `autoheader' uses the first
1 one.)
1
1 It is recommended that only one input file is used. If you want to
1 append a boilerplate code, it is preferable to use `AH_BOTTOM([#include
1 <conf_post.h>])'. File `conf_post.h' is not processed during the
1 configuration then, which make things clearer. Analogically, `AH_TOP'
1 can be used to prepend a boilerplate code.
1
1 In order to do its job, `autoheader' needs you to document all of
1 the symbols that you might use. Typically this is done via an
1 `AC_DEFINE' or `AC_DEFINE_UNQUOTED' call whose first argument is a
DONTPRINTYET 11 literal symbol and whose third argument describes the symbol (⇒
Defining Symbols). Alternatively, you can use `AH_TEMPLATE' (*note1DONTPRINTYET 11 literal symbol and whose third argument describes the symbol (⇒
Defining Symbols). Alternatively, you can use `AH_TEMPLATE' (⇒
Autoheader Macros), or you can supply a suitable input file for a
1 subsequent configuration header file. Symbols defined by Autoconf's
1 builtin tests are already documented properly; you need to document
1 only those that you define yourself.
1
1 You might wonder why `autoheader' is needed: after all, why would
1 `configure' need to "patch" a `config.h.in' to produce a `config.h'
1 instead of just creating `config.h' from scratch? Well, when
1 everything rocks, the answer is just that we are wasting our time
1 maintaining `autoheader': generating `config.h' directly is all that is
1 needed. When things go wrong, however, you'll be thankful for the
1 existence of `autoheader'.
1
1 The fact that the symbols are documented is important in order to
1 _check_ that `config.h' makes sense. The fact that there is a
1 well-defined list of symbols that should be defined (or not) is also
1 important for people who are porting packages to environments where
1 `configure' cannot be run: they just have to _fill in the blanks_.
1
1 But let's come back to the point: the invocation of `autoheader'...
1
1 If you give `autoheader' an argument, it uses that file instead of
1 `configure.ac' and writes the header file to the standard output
1 instead of to `config.h.in'. If you give `autoheader' an argument of
1 `-', it reads the standard input instead of `configure.ac' and writes
1 the header file to the standard output.
1
1 `autoheader' accepts the following options:
1
1 `--help'
1 `-h'
1 Print a summary of the command line options and exit.
1
1 `--version'
1 `-V'
1 Print the version number of Autoconf and exit.
1
1 `--verbose'
1 `-v'
1 Report processing steps.
1
1 `--debug'
1 `-d'
1 Don't remove the temporary files.
1
1 `--force'
1 `-f'
1 Remake the template file even if newer than its input files.
1
1 `--include=DIR'
1 `-I DIR'
1 Append DIR to the include path. Multiple invocations accumulate.
1
1 `--prepend-include=DIR'
1 `-B DIR'
1 Prepend DIR to the include path. Multiple invocations accumulate.
1
1 `--warnings=CATEGORY'
1 `-W CATEGORY'
1 Report the warnings related to CATEGORY (which can actually be a
1 comma separated list). Current categories include:
1
1 `obsolete'
1 report the uses of obsolete constructs
1
1 `all'
1 report all the warnings
1
1 `none'
1 report none
1
1 `error'
1 treats warnings as errors
1
1 `no-CATEGORY'
1 disable warnings falling into CATEGORY
1
1