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