autoconf: autoconf Invocation

1 
1 3.4 Using `autoconf' to Create `configure'
1 ==========================================
1 
1 To create `configure' from `configure.ac', run the `autoconf' program
1 with no arguments.  `autoconf' processes `configure.ac' with the M4
1 macro processor, using the Autoconf macros.  If you give `autoconf' an
1 argument, it reads that file instead of `configure.ac' and writes the
1 configuration script to the standard output instead of to `configure'.
1 If you give `autoconf' the argument `-', it reads from the standard
1 input instead of `configure.ac' and writes the configuration script to
1 the standard output.
1 
1    The Autoconf macros are defined in several files.  Some of the files
1 are distributed with Autoconf; `autoconf' reads them first.  Then it
1 looks for the optional file `acsite.m4' in the directory that contains
1 the distributed Autoconf macro files, and for the optional file
1 `aclocal.m4' in the current directory.  Those files can contain your
11 site's or the package's own Autoconf macro definitions (⇒Writing
 Autoconf Macros, for more information).  If a macro is defined in
1 more than one of the files that `autoconf' reads, the last definition
1 it reads overrides the earlier ones.
1 
1    `autoconf' 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 `configure' 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 `--output=FILE'
1 `-o FILE'
1      Save output (script or trace) to FILE.  The file `-' stands for
1      the standard output.
1 
1 `--warnings=CATEGORY'
1 `-W CATEGORY'
1      Report the warnings related to CATEGORY (which can actually be a
1      comma separated list).  ⇒Reporting Messages, macro
1      `AC_DIAGNOSE', for a comprehensive list of categories.  Special
1      values include:
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      Warnings about `syntax' are enabled by default, and the environment
1      variable `WARNINGS', a comma separated list of categories, is
1      honored as well.  Passing `-W CATEGORY' actually behaves as if you
1      had passed `--warnings syntax,$WARNINGS,CATEGORY'.  To disable the
1      defaults and `WARNINGS', and then enable warnings about obsolete
1      constructs, use `-W none,obsolete'.
1 
1      Because `autoconf' uses `autom4te' behind the scenes, it displays
1      a back trace for errors, but not for warnings; if you want them,
1      just pass `-W error'.  ⇒autom4te Invocation, for some
1      examples.
1 
1 `--trace=MACRO[:FORMAT]'
1 `-t MACRO[:FORMAT]'
1      Do not create the `configure' script, but list the calls to MACRO
1      according to the FORMAT.  Multiple `--trace' arguments can be used
1      to list several macros.  Multiple `--trace' arguments for a single
1      macro are not cumulative; instead, you should just make FORMAT as
1      long as needed.
1 
1      The FORMAT is a regular string, with newlines if desired, and
1      several special escape codes.  It defaults to `$f:$l:$n:$%'; see
1      ⇒autom4te Invocation, for details on the FORMAT.
1 
1 `--initialization'
1 `-i'
1      By default, `--trace' does not trace the initialization of the
1      Autoconf macros (typically the `AC_DEFUN' definitions).  This
1      results in a noticeable speedup, but can be disabled by this
1      option.
1 
1    It is often necessary to check the content of a `configure.ac' file,
1 but parsing it yourself is extremely fragile and error-prone.  It is
1 suggested that you rely upon `--trace' to scan `configure.ac'.  For
1 instance, to find the list of variables that are substituted, use:
1 
1      $ autoconf -t AC_SUBST
1      configure.ac:2:AC_SUBST:ECHO_C
1      configure.ac:2:AC_SUBST:ECHO_N
1      configure.ac:2:AC_SUBST:ECHO_T
1      More traces deleted
1 
1 The example below highlights the difference between `$@', `$*', and
1 `$%'.
1 
1      $ cat configure.ac
1      AC_DEFINE(This, is, [an
1      [example]])
1      $ autoconf -t 'AC_DEFINE:@: $@
1      *: $*
1      %: $%'
1      @: [This],[is],[an
1      [example]]
1      *: This,is,an
1      [example]
1      %: This:is:an [example]
1 
1 The FORMAT gives you a lot of freedom:
1 
1      $ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";'
1      $ac_subst{"ECHO_C"} = "configure.ac:2";
1      $ac_subst{"ECHO_N"} = "configure.ac:2";
1      $ac_subst{"ECHO_T"} = "configure.ac:2";
1      More traces deleted
1 
1 A long SEPARATOR can be used to improve the readability of complex
1 structures, and to ease their parsing (for instance when no single
1 character is suitable as a separator):
1 
1      $ autoconf -t 'AM_MISSING_PROG:${|:::::|}*'
1      ACLOCAL|:::::|aclocal|:::::|$missing_dir
1      AUTOCONF|:::::|autoconf|:::::|$missing_dir
1      AUTOMAKE|:::::|automake|:::::|$missing_dir
1      More traces deleted
1