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:

• one or more `Makefile' files, one in each subdirectory of the package (see section Substitutions in Makefiles);
• optionally, a C header file, the name of which is configurable, containing #define directives (see section Configuration Header Files);
• a shell script called `config.status' that, when run, will recreate the files listed above (see section Recreating a Configuration);
• a shell script called `config.cache' that saves the results of running many of the tests (see section Cache Files);
• a file called `config.log' containing any messages produced by compilers, to help debugging if configure makes a mistake.

To create a configure script with Autoconf, you need to write an Autoconf input file `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 write `acconfig.h', and you will distribute the Autoconf-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.in

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

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 ---'

• Writing configure.in: What to put in an Autoconf input file.
• Invoking autoscan: Semi-automatic `configure.in' writing.
• Invoking ifnames: Listing the conditionals in source code.
• Invoking autoconf: How to create configuration scripts.
• Invoking autoreconf: Remaking multiple configure scripts.

Writing `configure.in'

To produce a configure script for a software package, create a file called `configure.in' 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 section Existing Tests, for their descriptions. For most other features, you can use Autoconf template macros to produce custom checks; see section Writing Tests, for information about them. For especially tricky or specialized features, `configure.in' might need to contain some hand-crafted shell commands. The autoscan program can give you a good start in writing `configure.in' (see section Using autoscan to Create `configure.in', for more information).

The order in which `configure.in' calls the Autoconf macros is not important, with a few exceptions. Every `configure.in' must contain a call to AC_INIT before the checks, and a call to AC_OUTPUT at the end (see section Creating Output Files). 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 section Existing Tests), and they also warn you when creating configure 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 could depend on things earlier in it. For example, library functions could be affected by typedefs and libraries.

AC_INIT(file)
checks for programs
checks for libraries
checks for header files
checks for typedefs
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
AC_OUTPUT([file...])

It is best to put each macro call on its own line in `configure.in'. 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.

When calling macros that take arguments, there must not be any blank space between the macro name and the open parenthesis. Arguments can be more than one line long if they are enclosed within the m4 quote characters `[' and `]'. If you have a long line such as a list of file names, you can generally use a backslash at the end of a line to continue it logically on the next line (this is implemented by the shell, not by anything special that Autoconf does).

Some macros handle two cases: what to do if the given condition is met, and what to do if the condition is not met. In some places you might want to do something if a condition is true but do nothing if it's false, or vice versa. To omit the true case, pass an empty value for the action-if-found argument to the macro. To omit the false case, omit the action-if-not-found argument to the macro, including the comma before it.

You can include comments in `configure.in' files by starting them with the m4 builtin macro dnl, which discards text up through the next newline. These comments do not appear in the generated configure scripts. For example, it is helpful to begin `configure.in' files with a line like this:

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

Using autoscan to Create `configure.in'

The autoscan program can help you create a `configure.in' 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.in' for that package.

You should manually examine `configure.scan' before renaming it to `configure.in'; 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_HEADER (see section Configuration Header Files). You might also have to change or add some #if directives to your program in order to make it work with Autoconf (see section Using ifnames to List Conditionals, for information about a program that can help with that job).

autoscan uses several data files, which are installed along with the distributed Autoconf macro files, to determine which macros to output when it finds particular symbols in a package's source files. These 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 is only installed if you already have Perl installed. autoscan accepts the following options:

--help

Print a summary of the command line options and exit.

--macrodir=dir

Look for the data files in directory dir instead of the default installation directory. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

--verbose

Print the names of the files it examines and the potentially interesting symbols it finds in them. This output can be voluminous.

--version

Print the version number of Autoconf and exit.

Using ifnames to List Conditionals

ifnames can help when writing a `configure.in' 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, this program can help you figure out what its configure needs to check for. It may help fill in some gaps in a `configure.in' generated by autoscan (see section Using autoscan to Create `configure.in').

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.

--macrodir=dir

-m dir

Look for the Autoconf macro files in directory dir instead of the default installation directory. Only used to get the version number. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

--version

Print the version number of Autoconf and exit.

Using autoconf to Create configure

To create configure from `configure.in', run the autoconf program with no arguments. autoconf processes `configure.in' with the m4 macro processor, using the Autoconf macros. If you give autoconf an argument, it reads that file instead of `configure.in' and writes the configuration script to the standard output instead of to configure. If you give autoconf the argument `-', it reads the standard input instead of `configure.in' and writes the configuration script on 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 Writing 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.

--localdir=dir

-l dir

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

--macrodir=dir

-m dir

Look for the installed macro files in directory dir. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

--version

Print the version number of Autoconf and exit.

Using autoreconf to Update configure Scripts

If you have a lot of Autoconf-generated configure scripts, the autoreconf program can save you some work. It runs autoconf (and autoheader, where appropriate) repeatedly to remake the Autoconf configure scripts and configuration header templates in the directory tree rooted at the current directory. By default, it only remakes those files that are older than their `configure.in' or (if present) `aclocal.m4'. Since autoheader does not change the timestamp of its output file if the file wouldn't be changing, this is not necessarily the minimum amount of work. If you install a new version of Autoconf, you can make autoreconf remake all of the files by giving it the `--force' option.

If you give autoreconf the `--macrodir=dir' or `--localdir=dir' options, it passes them down to autoconf and autoheader (with relative paths adjusted properly).

See section 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 `--macrodir=dir' or `--localdir=dir'.

autoreconf accepts the following options:

--help

-h

Print a summary of the command line options and exit.

--force

-f

Remake even `configure' scripts and configuration headers that are newer than their input files (`configure.in' and, if present, `aclocal.m4').

--localdir=dir

-l dir

Look for the package files `aclocal.m4' and `acconfig.h' (but not `file.top' and `file.bot') in directory dir instead of in the directory containing each `configure.in'.

--macrodir=dir

-m dir

Look for the Autoconf macro files in directory dir instead of the default installation directory. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

--verbose

Print the name of each directory where autoreconf runs autoconf (and autoheader, if appropriate).

--version

Print the version number of Autoconf and exit.