3.4 Using autoconf to Create configure

To create configure from `configure.ac', run the autoconf program with no arguments. autoconf processes `configure.ac' with the m4 macro processor, using the Autoconf macros. If you give autoconf an argument, it reads that file instead of `configure.ac' and writes the configuration script to the standard output instead of to configure. If you give autoconf the argument `-', it reads from the standard input instead of `configure.ac' and writes the configuration script to the standard output.

The Autoconf macros are defined in several files. Some of the files are distributed with Autoconf; autoconf reads them first. Then it looks for the optional file `acsite.m4' in the directory that contains the distributed Autoconf macro files, and for the optional file `aclocal.m4' in the current directory. Those files can contain your site's or the package's own Autoconf macro definitions (see section 9. Writing Autoconf Macros, for more information). If a macro is defined in more than one of the files that autoconf reads, the last definition it reads overrides the earlier ones.

autoconf 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.

`--autoconf-dir=dir'

`-A dir'

Override the location where the installed Autoconf data files are looked for. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

This option is rarely needed and dangerous; it is only used when one plays with different versions of Autoconf simultaneously.

`--localdir=dir'

`-l dir'

Look for the package file `aclocal.m4' in directory dir instead of in the current directory.

`--output=file'

`-o file'

Save output (script or trace) to file. The file `-' stands for the standard output.

`--warnings=category'

`-W category'

Report the warnings related to category (which can actually be a comma separated list). See section 9.3 Reporting Messages, macro AC_DIAGNOSE, for a comprehensive list of categories. Special values include:

`all'

report all the warnings

`none'

report none

`error'

treats warnings as errors

`no-category'

disable warnings falling into category

Warnings about `syntax' are enabled by default, and the environment variable WARNINGS, a comma separated list of categories, is honored. autoconf -W category will actually behave as if you had run:

autoconf --warnings=syntax,$WARNINGS,category

If you want to disable autoconf's defaults and WARNINGS, but (for example) enable the warnings about obsolete constructs, you would use `-W none,obsolete'.

autoconf displays a back trace for errors, but not for warnings; if you want them, just pass `-W error'. For instance, on this `configure.ac':

AC_DEFUN([INNER], [AC_TRY_RUN([true])]) AC_DEFUN([OUTER], [INNER]) AC_INIT OUTER

you get:

$ autoconf -Wcross configure.ac:8: warning: AC_TRY_RUN called without default \ to allow cross compiling $ autoconf -Wcross,error configure.ac:8: error: AC_TRY_RUN called without default \ to allow cross compiling acgeneral.m4:3044: AC_TRY_RUN is expanded from... configure.ac:2: INNER is expanded from... configure.ac:5: OUTER is expanded from... configure.ac:8: the top level

`--trace=macro[:format]'

`-t macro[:format]'

Do not create the configure script, but list the calls to macro according to the format. Multiple `--trace' arguments can be used to list several macros. Multiple `--trace' arguments for a single macro are not cumulative; instead, you should just make format as long as needed.

The format is a regular string, with newlines if desired, and several special escape codes. It defaults to `$f:$l:$n:$%'; see below for details on the format.

`--initialization'

`-i'

By default, `--trace' does not trace the initialization of the Autoconf macros (typically the AC_DEFUN definitions). This results in a noticeable speedup, but can be disabled by this option.

It is often necessary to check the content of a `configure.ac' file, but parsing it yourself is extremely fragile and error-prone. It is suggested that you rely upon `--trace' to scan `configure.ac'.

The format of `--trace' can use the following special escapes:

`$$'

The character `$'.

`$f'

The filename from which macro is called.

`$l'

The line number from which macro is called.

`$d'

The depth of the macro call. This is an M4 technical detail that you probably don't want to know about.

`$n'

The name of the macro.

`$num'

The numth argument of the call to macro.

`$@'

`$sep@'

`${separator}@'

All the arguments passed to macro, separated by the character sep or the string separator (`,' by default). Each argument is quoted, i.e. enclosed in a pair of square brackets.

`$*'

`$sep*'

`${separator}*'

As above, but the arguments are not quoted.

`$%'

`$sep%'

`${separator}%'

As above, but the arguments are not quoted, all new line characters in the arguments are smashed, and the default separator is `:'.

The escape `$%' produces single-line trace outputs (unless you put newlines in the `separator'), while `$@' and `$*' do not.

For instance, to find the list of variables that are substituted, use:

$ autoconf -t AC_SUBST configure.ac:2:AC_SUBST:ECHO_C configure.ac:2:AC_SUBST:ECHO_N configure.ac:2:AC_SUBST:ECHO_T More traces deleted

The example below highlights the difference between `$@', `$*', and $%.

$ cat configure.ac AC_DEFINE(This, is, [an [example]]) $ autoconf -t 'AC_DEFINE:@: $@ *: $* $: $%' @: [This],[is],[an [example]] *: This,is,an [example] $: This:is:an [example]

The format gives you a lot of freedom:

$ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";' $ac_subst{"ECHO_C"} = "configure.ac:2"; $ac_subst{"ECHO_N"} = "configure.ac:2"; $ac_subst{"ECHO_T"} = "configure.ac:2"; More traces deleted

A long separator can be used to improve the readability of complex structures, and to ease its parsing (for instance when no single character is suitable as a separator)):

$ autoconf -t 'AM_MISSING_PROG:${|:::::|}*' ACLOCAL|:::::|aclocal|:::::|$missing_dir AUTOCONF|:::::|autoconf|:::::|$missing_dir AUTOMAKE|:::::|automake|:::::|$missing_dir More traces deleted