(autoconf.info)autoheader Invocation

Next: Autoheader Macros Prev: Header Templates Up: Configuration Headers

4.9.2 Using `autoheader' to Create `config.h.in'

The `autoheader' program can create a template file of C `#define'
statements for `configure' to use.  It searches for the first
invocation of `AC_CONFIG_HEADERS' in `configure' sources to determine
the name of the template.  (If the first call of `AC_CONFIG_HEADERS'
specifies more than one input file name, `autoheader' uses the first

   It is recommended that only one input file is used.  If you want to
append a boilerplate code, it is preferable to use `AH_BOTTOM([#include
<conf_post.h>])'.  File `conf_post.h' is not processed during the
configuration then, which make things clearer.  Analogically, `AH_TOP'
can be used to prepend a boilerplate code.

   In order to do its job, `autoheader' needs you to document all of
the symbols that you might use.  Typically this is done via an
`AC_DEFINE' or `AC_DEFINE_UNQUOTED' call whose first argument is a
literal symbol and whose third argument describes the symbol (*note
Defining Symbols::).  Alternatively, you can use `AH_TEMPLATE' (*note
Autoheader Macros::), or you can supply a suitable input file for a
subsequent configuration header file.  Symbols defined by Autoconf's
builtin tests are already documented properly; you need to document
only 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 defined (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: the invocation of `autoheader'...

   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.

`-I DIR'
     Append DIR to the include path.  Multiple invocations accumulate.


`-B DIR'
     Prepend DIR to the include path.  Multiple invocations accumulate.

     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

automatically generated by info2www