Autoconf

Node:Top, Next:, Up:(dir)

Autoconf

Node:Introduction, Next:, Previous:Top, Up:Top

Introduction

A physicist, an engineer, and a computer scientist were discussing the

nature of God. "Surely a Physicist," said the physicist, "because

early in the Creation, God made Light; and you know, Maxwell's

equations, the dual nature of electromagnetic waves, the relativistic

consequences..." "An Engineer!," said the engineer, "because

before making Light, God split the Chaos into Land and Water; it takes a

hell of an engineer to handle that big amount of mud, and orderly

separation of solids from liquids..." The computer scientist

shouted: "And the Chaos, where do you think it was coming from, hmm?"

--Anonymous

Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of UNIX-like systems. The configuration scripts produced by Autoconf are independent of Autoconf when they are run, so their users do not need to have Autoconf.

The configuration scripts produced by Autoconf require no manual user intervention when run; they do not normally even need an argument specifying the system type. Instead, they individually test for the presence of each feature that the software package they are for might need. (Before each check, they print a one-line message stating what they are checking for, so the user doesn't get too bored while waiting for the script to finish.) As a result, they deal well with systems that are hybrids or customized from the more common UNIX variants. There is no need to maintain files that list the features supported by each release of each variant of UNIX.

For each software package that Autoconf is used with, it creates a configuration script from a template file that lists the system features that the package needs or can use. After the shell code to recognize and respond to a system feature has been written, Autoconf allows it to be shared by many software packages that can use (or need) that feature. If it later turns out that the shell code needs adjustment for some reason, it needs to be changed in only one place; all of the configuration scripts can be regenerated automatically to take advantage of the updated code.

The Metaconfig package is similar in purpose to Autoconf, but the scripts it produces require manual user intervention, which is quite inconvenient when configuring large source trees. Unlike Metaconfig scripts, Autoconf scripts can support cross-compiling, if some care is taken in writing them.

Autoconf does not solve all problems related to making portable software packages--for a more complete solution, it should be used in concert with other GNU build tools like Automake and Libtool. These other tools take on jobs like the creation of a portable, recursive Makefile with all of the standard targets, linking of shared libraries, and so on. See The GNU build system, for more information.

Autoconf imposes some restrictions on the names of macros used with #if in C programs (see Preprocessor Symbol Index).

Autoconf requires GNU M4 in order to generate the scripts. It uses features that some UNIX versions of M4, including GNU M4 1.3, do not have. You must use version 1.4 or later of GNU M4.

See Autoconf 1, for information about upgrading from version 1. See History, for the story of Autoconf's development. See Questions, for answers to some common questions about Autoconf.

See the Autoconf web page for up-to-date information, details on the mailing lists, pointers to a list of known bugs, etc.

Mail suggestions to the Autoconf mailing list.

Bug reports should be preferably submitted to the Autoconf Gnats database, or sent to the Autoconf Bugs mailing list. If possible, first check that your bug is not already solved in current development versions, and that it has not been reported yet. Be sure to include all the needed information and a short configure.ac that demonstrates the problem.

Autoconf's development tree is accessible via CVS; see the Autoconf web page for details. There is also a CVSweb interface to the Autoconf development tree. Patches relative to the current CVS version can be sent for review to the Autoconf Patches mailing list.

Because of its mission, Autoconf includes only a set of often-used macros that have already demonstrated their usefulness. Nevertheless, if you wish to share your macros, or find existing ones, see the Autoconf Macro Archive, which is kindly run by Peter Simons.

Node:The GNU build system, Next:, Previous:Introduction, Up:Top

The GNU build system

Autoconf solves an important problem--reliable discovery of system-specific build and runtime information--but this is only one piece of the puzzle for the development of portable software. To this end, the GNU project has developed a suite of integrated utilities to finish the job Autoconf started: the GNU build system, whose most important components are Autoconf, Automake, and Libtool. In this chapter, we introduce you to those tools, point you to sources of more information, and try to convince you to use the entire GNU build system for your software.

Node:Automake, Next:, Up:The GNU build system

Automake

The ubiquity of make means that a Makefile is almost the only viable way to distribute automatic build rules for software, but one quickly runs into make's numerous limitations. Its lack of support for automatic dependency tracking, recursive builds in subdirectories, reliable timestamps (e.g. for network filesystems), and so on, mean that developers must painfully (and often incorrectly) reinvent the wheel for each project. Portability is non-trivial, thanks to the quirks of make on many systems. On top of all this is the manual labor required to implement the many standard targets that users have come to expect (make install, make distclean, make uninstall, etc.). Since you are, of course, using Autoconf, you also have to insert repetitive code in your Makefile.in to recognize @CC@, @CFLAGS@, and other substitutions provided by configure. Into this mess steps Automake.

Automake allows you to specify your build needs in a Makefile.am file with a vastly simpler and more powerful syntax than that of a plain Makefile, and then generates a portable Makefile.in for use with Autoconf. For example, the Makefile.am to build and install a simple "Hello world" program might look like: 

bin_PROGRAMS = hello
hello_SOURCES = hello.c

The resulting Makefile.in (~400 lines) automatically supports all the standard targets, the substitutions provided by Autoconf, automatic dependency tracking, VPATH building, and so on. make will build the hello program, and make install will install it in /usr/local/bin (or whatever prefix was given to configure, if not /usr/local).

Automake may require that additional tools be present on the developer's machine. For example, the Makefile.in that the developer works with may not be portable (e.g. it might use special features of your compiler to automatically generate dependency information). Running make dist, however, produces a hello-1.0.tar.gz package (or whatever the program/version is) with a Makefile.in that will work on any system.

The benefits of Automake increase for larger packages (especially ones with subdirectories), but even for small programs the added convenience and portability can be substantial. And that's not all...

Node:Libtool, Next:, Previous:Automake, Up:The GNU build system

Libtool

Very often, one wants to build not only programs, but libraries, so that other programs can benefit from the fruits of your labor. Ideally, one would like to produce shared (dynamically-linked) libraries, which can be used by multiple programs without duplication on disk or in memory and can be updated independently of the linked programs. Producing shared libraries portably, however, is the stuff of nightmares--each system has its own incompatible tools, compiler flags, and magic incantations. Fortunately, GNU provides a solution: Libtool.

Libtool handles all the requirements of building shared libraries for you, and at this time seems to be the only way to do so with any portability. It also handles many other headaches, such as: the interaction of Makefile rules with the variable suffixes of shared libraries, linking reliably to shared libraries before they are installed by the superuser, and supplying a consistent versioning system (so that different versions of a library can be installed or upgraded without breaking binary compatibility). Although Libtool, like Autoconf, can be used on its own, it is most simply utilized in conjunction with Automake--there, Libtool is used automatically whenever shared libraries are needed, and you need not know its syntax.

Node:Pointers, Previous:Libtool, Up:The GNU build system

Pointers

Developers who are used to the simplicity of make for small projects on a single system might be daunted at the prospect of learning to use Automake and Autoconf. As your software is distributed to more and more users, however, you will otherwise quickly find yourself putting lots of effort into reinventing the services that the GNU build tools provide, and making the same mistakes that they once made and overcame. (Besides, since you're already learning Autoconf, Automake will be a piece of cake.)

There are a number of places that you can go to for more information on the GNU build tools.

Node:Making configure Scripts, Next:, Previous:The GNU build system, Up:Top

Making configure Scripts

The configuration scripts that Autoconf produces are by convention called configure. When run, configure creates several files, replacing configuration parameters in them with appropriate values. The files that configure creates are:

To create a configure script with Autoconf, you need to write an Autoconf input file configure.ac (or configure.in) and run autoconf on it. If you write your own feature tests to supplement those that come with Autoconf, you might also write files called aclocal.m4 and acsite.m4. If you use a C header file to contain #define directives, you might also run autoheader, and you will distribute the generated file config.h.in with the package.

Here is a diagram showing how the files that can be used in configuration are produced. Programs that are executed are suffixed by *. Optional files are enclosed in square brackets ([]). autoconf and autoheader also read the installed Autoconf macro files (by reading autoconf.m4).

Files used in preparing a software package for distribution: 

your source files --> [autoscan*] --> [configure.scan] --> configure.ac

configure.ac --.
               |   .------> autoconf* -----> configure
[aclocal.m4] --+---+
               |   `-----> [autoheader*] --> [config.h.in]
[acsite.m4] ---'

Makefile.in -------------------------------> Makefile.in

Files used in configuring a software package: 

                       .-------------> [config.cache]
configure* ------------+-------------> config.log
                       |
[config.h.in] -.       v            .-> [config.h] -.
               +--> config.status* -+               +--> make*
Makefile.in ---'                    `-> Makefile ---'

Node:Writing configure.ac, Next:, Up:Making configure Scripts

Writing configure.ac

To produce a configure script for a software package, create a file called configure.ac that contains invocations of the Autoconf macros that test the system features your package needs or can use. Autoconf macros already exist to check for many features; see Existing Tests, for their descriptions. For most other features, you can use Autoconf template macros to produce custom checks; see Writing Tests, for information about them. For especially tricky or specialized features, configure.ac might need to contain some hand-crafted shell commands; see Portable Shell. The autoscan program can give you a good start in writing configure.ac (see autoscan Invocation, for more information).

Previous versions of Autoconf promoted the name configure.in, which is somewhat ambiguous (the tool needed to produce this file is not described by its extension), and introduces a slight confusion with config.h.in and so on (for which .in means "to be processed by configure"). Using configure.ac is now preferred.

Node:Shell Script Compiler, Next:, Up:Writing configure.ac

A Shell Script Compiler

Just as for any other computer language, in order to properly program configure.ac in Autoconf you must understand what problem the language tries to address and how it does so.

The problem Autoconf addresses is that the world is a mess. After all, you are using Autoconf in order to have your package compile easily on all sorts of different systems, some of them being extremely hostile. Autoconf itself bears the price for these differences: configure must run on all those systems, and thus configure must limit itself to their lowest common denominator of features.

Naturally, you might then think of shell scripts; who needs autoconf? A set of properly written shell functions is enough to make it easy to write configure scripts by hand. Sigh! Unfortunately, shell functions do not belong to the least common denominator; therefore, where you would like to define a function and use it ten times, you would instead need to copy its body ten times.

So, what is really needed is some kind of compiler, autoconf, that takes an Autoconf program, configure.ac, and transforms it into a portable shell script, configure.

How does autoconf perform this task?

There are two obvious possibilities: creating a brand new language or extending an existing one. The former option is very attractive: all sorts of optimizations could easily be implemented in the compiler and many rigorous checks could be performed on the Autoconf program (e.g. rejecting any non-portable construct). Alternatively, you can extend an existing language, such as the sh (Bourne shell) language.

Autoconf does the latter: it is a layer on top of sh. It was therefore most convenient to implement autoconf as a macro expander: a program that repeatedly performs macro expansions on text input, replacing macro calls with macro bodies and producing a pure sh script in the end. Instead of implementing a dedicated Autoconf macro expander, it is natural to use an existing general-purpose macro language, such as M4, and implement the extensions as a set of M4 macros.

Node:Autoconf Language, Next:, Previous:Shell Script Compiler, Up:Writing configure.ac

The Autoconf Language

The Autoconf language is very different from many other computer languages because it treats actual code the same as plain text. Whereas in C, for instance, data and instructions have very different syntactic status, in Autoconf their status is rigorously the same. Therefore, we need a means to distinguish literal strings from text to be expanded: quotation.

When calling macros that take arguments, there must not be any blank space between the macro name and the open parenthesis. Arguments should be enclosed within the M4 quote characters [ and ], and be separated by commas. Any leading spaces in arguments are ignored, unless they are quoted. You may safely leave out the quotes when the argument is simple text, but always quote complex arguments such as other macro calls. This rule applies recursively for every macro call, including macros called from other macros.

For instance: 

AC_CHECK_HEADER([stdio.h],
                [AC_DEFINE([HAVE_STDIO_H])],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])

is quoted properly. You may safely simplify its quotation to: 

AC_CHECK_HEADER(stdio.h,
                [AC_DEFINE(HAVE_STDIO_H)],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])

Notice that the argument of AC_MSG_ERROR is still quoted; otherwise, its comma would have been interpreted as an argument separator.

The following example is wrong and dangerous, as it is underquoted: 

AC_CHECK_HEADER(stdio.h,
                AC_DEFINE(HAVE_STDIO_H),
                AC_MSG_ERROR([Sorry, can't do anything for you]))

In other cases, you may have to use text that also resembles a macro call. You must quote that text even when it is not passed as a macro argument: 

echo "Hard rock was here!  --[AC_DC]"

which will result in 

echo "Hard rock was here!  --AC_DC"

When you use the same text in a macro argument, you must therefore have an extra quotation level (since one is stripped away by the macro substitution). In general, then, it is a good idea to use double quoting for all literal string arguments: 

AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])

You are now able to understand one of the constructs of Autoconf that has been continually misunderstood... The rule of thumb is that whenever you expect macro expansion, expect quote expansion; i.e., expect one level of quotes to be lost. For instance: 

AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])

is incorrect: here, the first argument of AC_COMPILE_IFELSE is char b[10]; and will be expanded once, which results in char b10;. (There was an idiom common in Autoconf's past to address this issue via the M4 changequote primitive, but do not use it!) Let's take a closer look: the author meant the first argument to be understood as a literal, and therefore it must be quoted twice: 

AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])

Voilà, you actually produce char b[10]; this time!

The careful reader will notice that, according to these guidelines, the "properly" quoted AC_CHECK_HEADER example above is actually lacking three pairs of quotes! Nevertheless, for the sake of readability, double quotation of literals is used only where needed in this manual.

Some macros take optional arguments, which this documentation represents as [arg] (not to be confused with the quote characters). You may just leave them empty, or use [] to make the emptiness of the argument explicit, or you may simply omit the trailing commas. The three lines below are equivalent: 

AC_CHECK_HEADERS(stdio.h, [], [], [])
AC_CHECK_HEADERS(stdio.h,,,)
AC_CHECK_HEADERS(stdio.h)

It is best to put each macro call on its own line in configure.ac. Most of the macros don't add extra newlines; they rely on the newline after the macro call to terminate the commands. This approach makes the generated configure script a little easier to read by not inserting lots of blank lines. It is generally safe to set shell variables on the same line as a macro call, because the shell allows assignments without intervening newlines.

You can include comments in configure.ac files by starting them with the #. For example, it is helpful to begin configure.ac files with a line like this: 

# Process this file with autoconf to produce a configure script.

Node:configure.ac Layout, Previous:Autoconf Language, Up:Writing configure.ac

Standard configure.ac Layout

The order in which configure.ac calls the Autoconf macros is not important, with a few exceptions. Every configure.ac must contain a call to AC_INIT before the checks, and a call to AC_OUTPUT at the end (see Output). Additionally, some macros rely on other macros having been called first, because they check previously set values of some variables to decide what to do. These macros are noted in the individual descriptions (see Existing Tests), and they also warn you when configure is created if they are called out of order.

To encourage consistency, here is a suggested order for calling the Autoconf macros. Generally speaking, the things near the end of this list are those that could depend on things earlier in it. For example, library functions could be affected by types and libraries. 

Autoconf requirements
AC_INIT(package, version, bug-report-address)
information on the package
checks for programs
checks for libraries
checks for header files
checks for types
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
AC_CONFIG_FILES([file...])
AC_OUTPUT

Node:autoscan Invocation, Next:, Previous:Writing configure.ac, Up:Making configure Scripts

Using autoscan to Create configure.ac

The autoscan program can help you create and/or maintain a configure.ac file for a software package. autoscan examines source files in the directory tree rooted at a directory given as a command line argument, or the current directory if none is given. It searches the source files for common portability problems and creates a file configure.scan which is a preliminary configure.ac for that package, and checks a possibly existing configure.ac for completeness.

When using autoscan to create a configure.ac, you should manually examine configure.scan before renaming it to configure.ac; it will probably need some adjustments. Occasionally, autoscan outputs a macro in the wrong order relative to another macro, so that autoconf produces a warning; you need to move such macros manually. Also, if you want the package to use a configuration header file, you must add a call to AC_CONFIG_HEADERS (see Configuration Headers). You might also have to change or add some #if directives to your program in order to make it work with Autoconf (see ifnames Invocation, for information about a program that can help with that job).

When using autoscan to maintain a configure.ac, simply consider adding its suggestions. The file autoscan.log will contain detailed information on why a macro is requested.

autoscan uses several data files (installed along with Autoconf) to determine which macros to output when it finds particular symbols in a package's source files. These data files all have the same format: each line consists of a symbol, whitespace, and the Autoconf macro to output if that symbol is encountered. Lines starting with # are comments.

autoscan 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
Print the names of the files it examines and the potentially interesting symbols it finds in them. This output can be voluminous.
--include=dir
-I dir
Also look for input files in dir. Multiple invocations accumulate. Directories are browsed from last to first.

Node:ifnames Invocation, Next:, Previous:autoscan Invocation, Up:Making configure Scripts

Using ifnames to List Conditionals

ifnames can help you write configure.ac for a software package. It prints the identifiers that the package already uses in C preprocessor conditionals. If a package has already been set up to have some portability, ifnames can thus help you figure out what its configure needs to check for. It may help fill in some gaps in a configure.ac generated by autoscan (see autoscan Invocation).

ifnames scans all of the C source files named on the command line (or the standard input, if none are given) and writes to the standard output a sorted list of all the identifiers that appear in those files in #if, #elif, #ifdef, or #ifndef directives. It prints each identifier on a line, followed by a space-separated list of the files in which that identifier occurs.

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

Node:autoconf Invocation, Next:, Previous:ifnames Invocation, Up:Making configure Scripts

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 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.
--force
-f
Remake configure 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.
--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 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([exit (0)])])

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

Node:autoreconf Invocation, Previous:autoconf Invocation, Up:Making configure Scripts

Using autoreconf to Update configure Scripts

Installing the various components of the GNU Build System can be tedious: running gettextize, automake etc. in each directory. It may be needed either because some tools such as automake have been updated on your system, or because some of the sources such as configure.ac have been updated, or finally, simply in order to install the GNU Build System in a fresh tree.

It runs autoconf, autoheader, aclocal, automake, libtoolize, and gettextize (when appropriate) repeatedly to update the GNU Build System in specified directories, and their subdirectories (see Subdirectories). By default, it only remakes those files that are older than their sources.

If you install a new version of some tools, you can make autoreconf remake all of the files by giving it the --force option.

See Automatic Remaking, for Makefile rules to automatically remake configure scripts when their source files change. That method handles the timestamps of configuration header templates properly, but does not pass --autoconf-dir=dir or --localdir=dir.

autoreconf 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
Print the name of each directory where autoreconf runs autoconf (and autoheader, if appropriate).
--debug
-d
Don't remove the temporary files.
--force
-f
Remake even configure scripts and configuration headers that are newer than their input files (configure.ac and, if present, aclocal.m4).
--install
-i
Copy missing auxiliary files. This option is similar to the option --add-missing in automake.
--symlink
-s
Instead of copying missing auxiliary files, install symbolic links.
--include=dir
-I dir
Also look for input files in dir. Multiple invocations accumulate. Directories are browsed from last to first.

Node:Setup, Next:, Previous:Making configure Scripts, Up:Top

Initialization and Output Files

Autoconf-generated configure scripts need some information about how to initialize, such as how to find the package's source files; and about the output files to produce. The following sections describe initialization and the creation of output files.

Node:Initializing configure, Next:, Up:Setup

Initializing configure

Every configure script must call AC_INIT before doing anything else. The only other required macro is AC_OUTPUT (see Output).

AC_INIT (package, version, [bug-report], [tarname]) Macro
Process any command-line arguments and perform various initializations and verifications.

Set the name of the package and its version. These are typically used in --version support, including that of configure. The optional argument bug-report should be the email to which users should send bug reports. The package tarname differs from package: the latter designates the full package name (e.g., GNU Autoconf), while the latter is meant for distribution tar ball names (e.g., autoconf). It defaults to package once GNU strip, lower cased, and all non alphanumeric character mapped onto -.

It is preferable that these arguments be static, i.e., there should not be any shell computation, but they can be computed by M4. The following M4 macros (e.g., AC_PACKAGE_NAME), output variables (e.g., PACKAGE_NAME), and preprocessor symbols (e.g., PACKAGE_NAME) are then defined:

AC_PACKAGE_NAME, PACKAGE_NAME
Exactly package.
AC_PACKAGE_TARNAME, PACKAGE_TARNAME
Exactly tarname.
AC_PACKAGE_VERSION, PACKAGE_VERSION
Exactly version.
AC_PACKAGE_STRING, PACKAGE_STRING
Exactly package version.
AC_PACKAGE_BUGREPORT, PACKAGE_BUGREPORT
Exactly bug-report.

Node:Notices, Next:, Previous:Initializing configure, Up:Setup

Notices in configure

The following macros manage version numbers for configure scripts. Using them is optional.

AC_PREREQ (version) Macro
Ensure that a recent enough version of Autoconf is being used. If the version of Autoconf being used to create configure is earlier than version, print an error message to the standard error output and do not create configure. For example: 
AC_PREREQ(2.53)

This macro is the only macro that may be used before AC_INIT, but for consistency, you are invited not to do so.

AC_COPYRIGHT (copyright-notice) Macro
State that, in addition to the Free Software Foundation's copyright on the Autoconf macros, parts of your configure are covered by the copyright-notice.

The copyright-notice will show up in both the head of configure and in configure --version.

AC_REVISION (revision-info) Macro
Copy revision stamp revision-info into the configure script, with any dollar signs or double-quotes removed. This macro lets you put a revision stamp from configure.ac into configure without RCS or cvs changing it when you check in configure. That way, you can determine easily which revision of configure.ac a particular configure corresponds to.

For example, this line in configure.ac: 

AC_REVISION($Revision: 1.30 $)

produces this in configure: 

#! /bin/sh
# From configure.ac Revision: 1.30

Node:Input, Next:, Previous:Notices, Up:Setup

Finding configure Input

AC_CONFIG_SRCDIR (unique-file-in-source-dir) Macro
unique-file-in-source-dir is some file that is in the package's source directory; configure checks for this file's existence to make sure that the directory that it is told contains the source code in fact does. Occasionally people accidentally specify the wrong directory with --srcdir; this is a safety check. See configure Invocation, for more information.

Packages that do manual configuration or use the install program might need to tell configure where to find some other shell scripts by calling AC_CONFIG_AUX_DIR, though the default places it looks are correct for most cases.

AC_CONFIG_AUX_DIR (dir) Macro
Use the auxiliary build tools (e.g., install-sh, config.sub, config.guess, Cygnus configure, Automake and Libtool scripts etc.) that are in directory dir. These are auxiliary files used in configuration. dir can be either absolute or relative to srcdir. The default is srcdir or srcdir/.. or srcdir/../.., whichever is the first that contains install-sh. The other files are not checked for, so that using AC_PROG_INSTALL does not automatically require distributing the other auxiliary files. It checks for install.sh also, but that name is obsolete because some make have a rule that creates install from it if there is no Makefile.

Node:Output, Next:, Previous:Input, Up:Setup

Outputting Files

Every Autoconf script, e.g., configure.ac, should finish by calling AC_OUTPUT. It is the macro that generates config.status, which will create the Makefiles and any other files resulting from configuration. The only required macro is AC_INIT (see Input).

AC_OUTPUT Macro
Generate config.status and launch it. Call this macro once, at the end of configure.ac.

config.status will take all the configuration actions: all the output files (see Configuration Files, macro AC_CONFIG_FILES), header files (see Configuration Headers, macro AC_CONFIG_HEADERS), commands (see Configuration Commands, macro AC_CONFIG_COMMANDS), links (see Configuration Links, macro AC_CONFIG_LINKS), subdirectories to configure (see Subdirectories, macro AC_CONFIG_SUBDIRS) are honored.

Historically, the usage of AC_OUTPUT was somewhat different. See Obsolete Macros, for a description of the arguments that AC_OUTPUT used to support.

If you run make on subdirectories, you should run it using the make variable MAKE. Most versions of make set MAKE to the name of the make program plus any options it was given. (But many do not include in it the values of any variables set on the command line, so those are not passed on automatically.) Some old versions of make do not set this variable. The following macro allows you to use it even with those versions.

AC_PROG_MAKE_SET Macro
If make predefines the variable MAKE, define output variable SET_MAKE to be empty. Otherwise, define SET_MAKE to contain MAKE=make. Calls AC_SUBST for SET_MAKE.

To use this macro, place a line like this in each Makefile.in that runs MAKE on other directories: 

@SET_MAKE@

Node:Configuration Actions, Next:, Previous:Output, Up:Setup

Taking Configuration Actions

configure is designed so that it appears to do everything itself, but there is actually a hidden slave: config.status. configure is in charge of examining your system, but it is config.status that actually takes the proper actions based on the results of configure. The most typical task of config.status is to instantiate files.

This section describes the common behavior of the four standard instantiating macros: AC_CONFIG_FILES, AC_CONFIG_HEADERS, AC_CONFIG_COMMANDS and AC_CONFIG_LINKS. They all have this prototype: 

AC_CONFIG_FOOS(tag..., [commands], [init-cmds])

where the arguments are:

tag...
A whitespace-separated list of tags, which are typically the names of the files to instantiate.

You are encouraged to use literals as tags. In particular, you should avoid 

... && my_foos="$my_foos fooo"
... && my_foos="$my_foos foooo"
AC_CONFIG_FOOS($my_foos)

and use this instead: 

... && AC_CONFIG_FOOS(fooo)
... && AC_CONFIG_FOOS(foooo)

The macros AC_CONFIG_FILES and AC_CONFIG_HEADERS use special tags: they may have the form output or output:inputs. The file output is instantiated from its templates, inputs (defaulting to output.in).

For instance AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk) asks for the creation of Makefile that will be the expansion of the output variables in the concatenation of boiler/top.mk and boiler/bot.mk.

The special value - might be used to denote the standard output when used in output, or the standard input when used in the inputs. You most probably don't need to use this in configure.ac, but it is convenient when using the command line interface of ./config.status, see config.status Invocation, for more details.

The inputs may be absolute or relative filenames. In the latter case they are first looked for in the build tree, and then in the source tree.

commands
Shell commands output literally into config.status, and associated with a tag that the user can use to tell config.status which the commands to run. The commands are run each time a tag request is given to config.status; typically, each time the file tag is created.

The variable set during the execution of configure are not available here: you first need to set them via the init-cmds. Nonetheless the following variables are precomputed:

srcdir
The path from the top build directory to the top source directory. This is what configure's option --srcdir sets.
ac_top_srcdir
The path from the current build directory to the top source directory.
ac_top_builddir
The path from the current build directory to the top build directory. It can be empty, or else ends with a slash, so that you may concatenate it.
ac_srcdir
The path from the current build directory to the corresponding source directory.

The current directory refers to the directory (or pseudo-directory) containing the input part of tags. For instance, running 

AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [...], [...])

with --srcdir=../package produces the following values: 

# Argument of --srcdir
srcdir='../package'
# Reversing deep/dir
ac_top_builddir='../../'
# Concatenation of $ac_top_builddir and srcdir
ac_top_srcdir='../../../package'
# Concatenation of $ac_top_srcdir and deep/dir
ac_srcdir='../../../package/deep/dir'

independently of in/in.in.

init-cmds
Shell commands output unquoted near the beginning of config.status, and executed each time config.status runs (regardless of the tag). Because they are unquoted, for example, $var will be output as the value of var. init-cmds is typically used by configure to give config.status some variables it needs to run the commands.

You should be extremely cautious in your variable names: all the init-cmds share the same name space and may overwrite each other in unpredictable ways. Sorry...

All these macros can be called multiple times, with different tags, of course!

Node:Configuration Files, Next:, Previous:Configuration Actions, Up:Setup

Creating Configuration Files

Be sure to read the previous section, Configuration Actions.

AC_CONFIG_FILES (file..., [cmds], [init-cmds]) Macro
Make AC_OUTPUT create each file by copying an input file (by default file.in), substituting the output variable values. This macro is one of the instantiating macros, see Configuration Actions. See Makefile Substitutions, for more information on using output variables. See Setting Output Variables, for more information on creating them. This macro creates the directory that the file is in if it doesn't exist. Usually, Makefiles are created this way, but other files, such as .gdbinit, can be specified as well.

Typical calls to AC_CONFIG_FILES look like this: 

AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
AC_CONFIG_FILES([autoconf], [chmod +x autoconf])

You can override an input file name by appending to file a colon-separated list of input files. Examples: 

AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
                [lib/Makefile:boiler/lib.mk])

Doing this allows you to keep your file names acceptable to MS-DOS, or to prepend and/or append boilerplate to the file.

Node:Makefile Substitutions, Next:, Previous:Configuration Files, Up:Setup

Substitutions in Makefiles

Each subdirectory in a distribution that contains something to be compiled or installed should come with a file Makefile.in, from which configure will create a Makefile in that directory. To create a Makefile, configure performs a simple variable substitution, replacing occurrences of @variable@ in Makefile.in with the value that configure has determined for that variable. Variables that are substituted into output files in this way are called output variables. They are ordinary shell variables that are set in configure. To make configure substitute a particular variable into the output files, the macro AC_SUBST must be called with that variable name as an argument. Any occurrences of @variable@ for other variables are left unchanged. See Setting Output Variables, for more information on creating output variables with AC_SUBST.

A software package that uses a configure script should be distributed with a file Makefile.in, but no Makefile; that way, the user has to properly configure the package for the local system before compiling it.

See Makefile Conventions, for more information on what to put in Makefiles.

Node:Preset Output Variables, Next:, Up:Makefile Substitutions

Preset Output Variables

Some output variables are preset by the Autoconf macros. Some of the Autoconf macros set additional output variables, which are mentioned in the descriptions for those macros. See Output Variable Index, for a complete list of output variables. See Installation Directory Variables, for the list of the preset ones related to installation directories. Below are listed the other preset ones. They all are precious variables (see Setting Output Variables, AC_ARG_VAR).

CFLAGS Variable
Debugging and optimization options for the C compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_CC (or empty if you don't). configure uses this variable when compiling programs to test for C features.

configure_input Variable
A comment saying that the file was generated automatically by configure and giving the name of the input file. AC_OUTPUT adds a comment line containing this variable to the top of every Makefile it creates. For other files, you should reference this variable in a comment at the top of each input file. For example, an input shell script should begin like this: 
#! /bin/sh
# @configure_input@

The presence of that line also reminds people editing the file that it needs to be processed by configure in order to be used.

CPPFLAGS Variable
Header file search directory (-Idir) and any other miscellaneous options for the C and C++ preprocessors and compilers. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when compiling or preprocessing programs to test for C and C++ features.

CXXFLAGS Variable
Debugging and optimization options for the C++ compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_CXX (or empty if you don't). configure uses this variable when compiling programs to test for C++ features.

DEFS Variable
-D options to pass to the C compiler. If AC_CONFIG_HEADERS is called, configure replaces @DEFS@ with -DHAVE_CONFIG_H instead (see Configuration Headers). This variable is not defined while configure is performing its tests, only when creating the output files. See Setting Output Variables, for how to check the results of previous tests.

ECHO_C Variable
ECHO_N Variable
ECHO_T Variable
How does one suppress the trailing newline from echo for question-answer message pairs? These variables provide a way: 
echo $ECHO_N "And the winner is... $ECHO_C"
sleep 100000000000
echo "${ECHO_T}dead."

Some old and uncommon echo implementations offer no means to achieve this, in which case ECHO_T is set to tab. You might not want to use it.

FFLAGS Variable
Debugging and optimization options for the Fortran 77 compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_F77 (or empty if you don't). configure uses this variable when compiling programs to test for Fortran 77 features.

LDFLAGS Variable
Stripping (-s), path (-L), and any other miscellaneous options for the linker. Don't use this variable to pass library names (-l) to the linker, use LIBS instead. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when linking programs to test for C, C++ and Fortran 77 features.

LIBS Variable
-l options to pass to the linker. The default value is empty, but some Autoconf macros may prepend extra libraries to this variable if those libraries are found and provide necessary functions, see Libraries. configure uses this variable when linking programs to test for C, C++ and Fortran 77 features.

builddir Variable
Rigorously equal to .. Added for symmetry only.

abs_builddir Variable
Absolute path of builddir.

top_builddir Variable
The relative path to the top-level of the current build tree. In the top-level directory, this is the same as srcbuild.

abs_top_builddir Variable
Absolute path of top_builddir.

srcdir Variable
The relative path to the directory that contains the source code for that Makefile.

abs_srcdir Variable
Absolute path of srcdir.

top_srcdir Variable
The relative path to the top-level source code directory for the package. In the top-level directory, this is the same as srcdir.

abs_top_srcdir Variable
Absolute path of top_srcdir.

Node:Installation Directory Variables, Next:, Previous:Preset Output Variables, Up:Makefile Substitutions

Installation Directory Variables

The following variables specify the directories where the package will be installed, see Variables for Installation Directories, for more information. See the end of this section for details on when and how to use these variables.

bindir Variable
The directory for installing executables that users run.

datadir Variable
The directory for installing read-only architecture-independent data.

exec_prefix Variable
The installation prefix for architecture-dependent files. By default it's the same as prefix. You should avoid installing anything directly to exec_prefix. However, the default value for directories containing architecture-dependent files should be relative to exec_prefix.

includedir Variable
The directory for installing C header files.

infodir Variable
The directory for installing documentation in Info format.

libdir Variable
The directory for installing object code libraries.

libexecdir Variable
The directory for installing executables that other programs run.

localstatedir Variable
The directory for installing modifiable single-machine data.

mandir Variable
The top-level directory for installing documentation in man format.

oldincludedir Variable
The directory for installing C header files for non-gcc compilers.

prefix Variable
The common installation prefix for all files. If exec_prefix is defined to a different value, prefix is used only for architecture-independent files.

sbindir Variable
The directory for installing executables that system administrators run.

sharedstatedir Variable
The directory for installing modifiable architecture-independent data.

sysconfdir Variable
The directory for installing read-only single-machine data.

Most of these variables have values that rely on prefix or exec_prefix. It is deliberate that the directory output variables keep them unexpanded: typically @datadir@ will be replaced by ${prefix}/share, not /usr/local/share.

This behavior is mandated by the GNU coding standards, so that when the user runs:

make
she can still specify a different prefix from the one specified to configure, in which case, if needed, the package shall hard code dependencies corresponding to the make-specified prefix.
make install
she can specify a different installation location, in which case the package must still depend on the location which was compiled in (i.e., never recompile when make install is run). This is an extremely important feature, as many people may decide to install all the files of a package grouped together, and then install links from the final locations to there.

In order to support these features, it is essential that datadir remains being defined as ${prefix}/share to depend upon the current value of prefix.

A corollary is that you should not use these variables except in Makefiles. For instance, instead of trying to evaluate datadir in configure and hardcoding it in Makefiles using e.g. AC_DEFINE_UNQUOTED(DATADIR, "$datadir"), you should add -DDATADIR="$(datadir)" to your CPPFLAGS.

Similarly you should not rely on AC_OUTPUT_FILES to replace datadir and friends in your shell scripts and other files, rather let make manage their replacement. For instance Autoconf ships templates of its shell scripts ending with .sh, and uses this Makefile snippet: 

.sh:
        rm -f $@ $@.tmp
        sed 's,@datadir\@,$(pkgdatadir),g' $< >$@.tmp
        chmod +x $@.tmp
        mv $@.tmp $@

Three things are noteworthy:

@datadir\@
The backslash prevents configure from replacing @datadir@ in the sed expression itself.
$(pkgdatadir)
Don't use @pkgdatadir@! Use the matching makefile variable instead.
,
Don't use / in the sed expression(s) since most probably the variables you use, such as $(pkgdatadir), will contain some.

Node:Build Directories, Next:, Previous:Installation Directory Variables, Up:Makefile Substitutions

Build Directories

You can support compiling a software package for several architectures simultaneously from the same copy of the source code. The object files for each architecture are kept in their own directory.

To support doing this, make uses the VPATH variable to find the files that are in the source directory. GNU make and most other recent make programs can do this. Older make programs do not support VPATH; when using them, the source code must be in the same directory as the object files.

To support VPATH, each Makefile.in should contain two lines that look like: 

srcdir = @srcdir@
VPATH = @srcdir@

Do not set VPATH to the value of another variable, for example VPATH = $(srcdir), because some versions of make do not do variable substitutions on the value of VPATH.

configure substitutes in the correct value for srcdir when it produces Makefile.

Do not use the make variable $<, which expands to the file name of the file in the source directory (found with VPATH), except in implicit rules. (An implicit rule is one such as .c.o, which tells how to create a .o file from a .c file.) Some versions of make do not set $< in explicit rules; they expand it to an empty value.

Instead, Makefile command lines should always refer to source files by prefixing them with $(srcdir)/. For example: 

time.info: time.texinfo
        $(MAKEINFO) $(srcdir)/time.texinfo

Node:Automatic Remaking, Previous:Build Directories, Up:Makefile Substitutions

Automatic Remaking

You can put rules like the following in the top-level Makefile.in for a package to automatically update the configuration information when you change the configuration files. This example includes all of the optional files, such as aclocal.m4 and those related to configuration header files. Omit from the Makefile.in rules for any of these files that your package does not use.

The $(srcdir)/ prefix is included because of limitations in the VPATH mechanism.

The stamp- files are necessary because the timestamps of config.h.in and config.h will not be changed if remaking them does not change their contents. This feature avoids unnecessary recompilation. You should include the file stamp-h.in your package's distribution, so make will consider config.h.in up to date. Don't use touch (see Limitations of Usual Tools), rather use echo (using date would cause needless differences, hence CVS conflicts etc.). 

$(srcdir)/configure: configure.ac aclocal.m4
        cd $(srcdir) && autoconf

# autoheader might not change config.h.in, so touch a stamp file.
$(srcdir)/config.h.in: stamp-h.in
$(srcdir)/stamp-h.in: configure.ac aclocal.m4
        cd $(srcdir) && autoheader
        echo timestamp > $(srcdir)/stamp-h.in

config.h: stamp-h
stamp-h: config.h.in config.status
        ./config.status

Makefile: Makefile.in config.status
        ./config.status

config.status: configure
        ./config.status --recheck

(Be careful if you copy these lines directly into your Makefile, as you will need to convert the indented lines to start with the tab character.)

In addition, you should use AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h]) so config.status will ensure that config.h is considered up to date. See Output, for more information about AC_OUTPUT.

See config.status Invocation, for more examples of handling configuration-related dependencies.

Node:Configuration Headers, Next:, Previous:Makefile Substitutions, Up:Setup

Configuration Header Files

When a package tests more than a few C preprocessor symbols, the command lines to pass -D options to the compiler can get quite long. This causes two problems. One is that the make output is hard to visually scan for errors. More seriously, the command lines can exceed the length limits of some operating systems. As an alternative to passing -D options to the compiler, configure scripts can create a C header file containing #define directives. The AC_CONFIG_HEADERS macro selects this kind of output. It should be called right after AC_INIT.

The package should #include the configuration header file before any other header files, to prevent inconsistencies in declarations (for example, if it redefines const). Use #include <config.h> instead of #include "config.h", and pass the C compiler a -I. option (or -I..; whichever directory contains config.h). That way, even if the source directory is configured itself (perhaps to make a distribution), other build directories can also be configured without finding the config.h from the source directory.

AC_CONFIG_HEADERS (header ..., [cmds], [init-cmds]) Macro
This macro is one of the instantiating macros, see Configuration Actions. Make AC_OUTPUT create the file(s) in the whitespace-separated list header containing C preprocessor #define statements, and replace @DEFS@ in generated files with -DHAVE_CONFIG_H instead of the value of DEFS. The usual name for header is config.h.

If header already exists and its contents are identical to what AC_OUTPUT would put in it, it is left alone. Doing this allows some changes in configuration without needlessly causing object files that depend on the header file to be recompiled.

Usually the input file is named header.in; however, you can override the input file name by appending to header, a colon-separated list of input files. Examples: 

AC_CONFIG_HEADERS([config.h:config.hin])
AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])

Doing this allows you to keep your file names acceptable to MS-DOS, or to prepend and/or append boilerplate to the file.

See Configuration Actions, for more details on header.

Node:Header Templates, Next:, Up:Configuration Headers

Configuration Header Templates

Your distribution should contain a template file that looks as you want the final header file to look, including comments, with #undef statements which are used as hooks. For example, suppose your configure.ac makes these calls: 

AC_CONFIG_HEADERS([conf.h])
AC_CHECK_HEADERS([unistd.h])

Then you could have code like the following in conf.h.in. On systems that have unistd.h, configure will #define HAVE_UNISTD_H to 1. On other systems, the whole line will be commented out (in case the system predefines that symbol). 

/* Define as 1 if you have unistd.h.  */
#undef HAVE_UNISTD_H

You can then decode the configuration header using the preprocessor directives: 

#include <conf.h>

#if HAVE_UNISTD_H
# include <unistd.h>
#else
/* We are in trouble. */
#endif

The use of old form templates, with #define instead of #undef is strongly discouraged.

Since it is a tedious task to keep a template header up to date, you may use autoheader to generate it, see autoheader Invocation.

Node:autoheader Invocation, Next:, Previous:Header Templates, Up:Configuration Headers

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 (see 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

Node:Autoheader Macros, Previous:autoheader Invocation, Up:Configuration Headers

Autoheader Macros

autoheader scans configure.ac and figures out which C preprocessor symbols it might define. It knows how to generate templates for symbols defined by AC_CHECK_HEADERS, AC_CHECK_FUNCS etc., but if you AC_DEFINE any additional symbol, you must define a template for it. If there are missing templates, autoheader fails with an error message.

The simplest way to create a template for a symbol is to supply the description argument to an AC_DEFINE(symbol); see Defining Symbols. You may also use one of the following macros.

AH_VERBATIM (key, template) Macro
Tell autoheader to include the template as-is in the header template file. This template is associated with the key, which is used to sort all the different templates and guarantee their uniqueness. It should be the symbol that can be AC_DEFINE'd.

For example: 

AH_VERBATIM([_GNU_SOURCE],
[/* Enable GNU extensions on systems that have them.  */
#ifndef _GNU_SOURCE
# define _GNU_SOURCE
#endif])

AH_TEMPLATE (key, description) Macro
Tell autoheader to generate a template for key. This macro generates standard templates just like AC_DEFINE when a description is given.

For example: 

AH_TEMPLATE([CRAY_STACKSEG_END],
            [Define to one of _getb67, GETB67, getb67
             for Cray-2 and Cray-YMP systems.  This
             function is required for alloca.c support
             on those systems.])

will generate the following template, with the description properly justified. 

/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
   Cray-YMP systems. This function is required for alloca.c
   support on those systems. */
#undef CRAY_STACKSEG_END

AH_TOP (text) Macro
Include text at the top of the header template file.

AH_BOTTOM (text) Macro
Include text at the bottom of the header template file.

Node:Configuration Commands, Next:, Previous:Configuration Headers, Up:Setup

Running Arbitrary Configuration Commands

You execute arbitrary commands either before, during and after config.status is run. The three following macros accumulate the commands to run when they are called multiple times. AC_CONFIG_COMMANDS replaces the obsolete macro AC_OUTPUT_COMMANDS, see Obsolete Macros, for details.

AC_CONFIG_COMMANDS (tag..., [cmds], [init-cmds]) Macro
Specify additional shell commands to run at the end of config.status, and shell commands to initialize any variables from configure. Associate the commands to the tag. Since typically the cmds create a file, tag should naturally be the name of that file. This macro is one of the instantiating macros, see Configuration Actions.

Here is an unrealistic example: 

fubar=42
AC_CONFIG_COMMANDS([fubar],
                   [echo this is extra $fubar, and so on.],
                   [fubar=$fubar])

Here is a better one: 

AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])

AC_CONFIG_COMMANDS_PRE (cmds) Macro
Execute the cmds right before creating config.status. A typical use is computing values derived from variables built during the execution of configure: 
AC_CONFIG_COMMANDS_PRE(
[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
AC_SUBST(LTLIBOBJS)])

AC_CONFIG_COMMANDS_POST (cmds) Macro
Execute the cmds right after creating config.status.

Node:Configuration Links, Next:, Previous:Configuration Commands, Up:Setup

Creating Configuration Links

You may find it convenient to create links whose destinations depend upon results of tests. One can use AC_CONFIG_COMMANDS but the creation of relative symbolic links can be delicate when the package is built in another directory than its sources.

AC_CONFIG_LINKS (dest:source..., [cmds], [init-cmds]) Macro
Make AC_OUTPUT link each of the existing files source to the corresponding link name dest. Makes a symbolic link if possible, otherwise a hard link. The dest and source names should be relative to the top level source or build directory. This macro is one of the instantiating macros, see Configuration Actions.

For example, this call: 

AC_CONFIG_LINKS(host.h:config/$machine.h
                object.h:config/$obj_format.h)

creates in the current directory host.h as a link to srcdir/config/$machine.h, and object.h as a link to srcdir/config/$obj_format.h.

The tempting value . for dest is invalid: it makes it impossible for config.status to guess the links to establish.

One can then run: 

./config.status host.h object.h

to create the links.

Node:Subdirectories, Next:, Previous:Configuration Links, Up:Setup

Configuring Other Packages in Subdirectories

In most situations, calling AC_OUTPUT is sufficient to produce Makefiles in subdirectories. However, configure scripts that control more than one independent package can use AC_CONFIG_SUBDIRS to run configure scripts for other packages in subdirectories.

AC_CONFIG_SUBDIRS (dir ...) Macro
Make AC_OUTPUT run configure in each subdirectory dir in the given whitespace-separated list. Each dir should be a literal, i.e., please do not use: 
if test "$package_foo_enabled" = yes; then
  $my_subdirs="$my_subdirs foo"
fi
AC_CONFIG_SUBDIRS($my_subdirs)

because this prevents ./configure --help=recursive from displaying the options of the package foo. Rather, you should write: 

if test "$package_foo_enabled" = yes; then
  AC_CONFIG_SUBDIRS(foo)
fi

If a given dir is not found, an error is reported: if the subdirectory is optional, write: 

if test -d $srcdir/foo; then
  AC_CONFIG_SUBDIRS(foo)
fi

If a given dir contains configure.gnu, it is run instead of configure. This is for packages that might use a non-autoconf script Configure, which can't be called through a wrapper configure since it would be the same file on case-insensitive filesystems. Likewise, if a dir contains configure.ac but no configure, the Cygnus configure script found by AC_CONFIG_AUX_DIR is used.

The subdirectory configure scripts are given the same command line options that were given to this configure script, with minor changes if needed, which include:

  • adjusting a relative path for the cache file;
  • adjusting a relative path for the source directory;
  • propagating the current value of $prefix, including if it was defaulted, and if default values of the top level and of sub directory configure differ.

This macro also sets the output variable subdirs to the list of directories dir .... Makefile rules can use this variable to determine which subdirectories to recurse into. This macro may be called multiple times.

Node:Default Prefix, Previous:Subdirectories, Up:Setup

Default Prefix

By default, configure sets the prefix for files it installs to /usr/local. The user of configure can select a different prefix using the --prefix and --exec-prefix options. There are two ways to change the default: when creating configure, and when running it.

Some software packages might want to install in a directory besides /usr/local by default. To accomplish that, use the AC_PREFIX_DEFAULT macro.

AC_PREFIX_DEFAULT (prefix) Macro
Set the default installation prefix to prefix instead of /usr/local.

It may be convenient for users to have configure guess the installation prefix from the location of a related program that they have already installed. If you wish to do that, you can call AC_PREFIX_PROGRAM.

AC_PREFIX_PROGRAM (program) Macro
If the user did not specify an installation prefix (using the --prefix option), guess a value for it by looking for program in PATH, the way the shell does. If program is found, set the prefix to the parent of the directory containing program; otherwise leave the prefix specified in Makefile.in unchanged. For example, if program is gcc and the PATH contains /usr/local/gnu/bin/gcc, set the prefix to /usr/local/gnu.

Node:Existing Tests, Next:, Previous:Setup, Up:Top

Existing Tests

These macros test for particular system features that packages might need or want to use. If you need to test for a kind of feature that none of these macros check for, you can probably do it by calling primitive test macros with appropriate arguments (see Writing Tests).

These tests print messages telling the user which feature they're checking for, and what they find. They cache their results for future configure runs (see Caching Results).

Some of these macros set output variables. See