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 (Note:Defining 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:
`--help'
`-h'
Print a summary of the command line options and exit.
`--version'
`-V'
Print the version number of Autoconf and exit.
`--verbose'
`-v'
Report processing steps.
`--debug'
`-d'
Don't remove the temporary files.
`--force'
`-f'
Remake the template file even if newer than its input files.
`--include=DIR'
`-I DIR'
Also look for input files in DIR. Multiple invocations accumulate.
Directories are browsed from last to first.
`--warnings=CATEGORY'
`-W CATEGORY'
Report the warnings related to CATEGORY (which can actually be a
comma separated list). Current categories include:
`obsolete'
report the uses of obsolete constructs
`all'
report all the warnings
`none'
report none
`error'
treats warnings as errors
`no-CATEGORY'
disable warnings falling into CATEGORY