Go to the previous, next section.

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 creating output files.

Finding configure Input

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

Macro: AC_INIT (unique-file-in-source-dir)

@maindex INIT Process any command-line arguments and find the source code directory. 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 section Running configure Scripts, 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.

Macro: AC_CONFIG_AUX_DIR(dir)

@maindex CONFIG_AUX_DIR Use the `install-sh', `config.sub', `config.guess', and Cygnus configure scripts 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 programs have a rule that creates `install' from it if there is no `Makefile'.

Creating Output Files

Every Autoconf-generated configure script must finish by calling AC_OUTPUT. It is the macro that creates the `Makefile's and optional other files resulting from configuration. The only other required macro is AC_INIT (see section Finding configure Input).

Macro: AC_OUTPUT ([file...] [,extra-cmds] [,init-cmds])

@maindex OUTPUT Create output files. The file... argument is a whitespace-separated list of output files; it may be empty. This macro creates each file `file' by copying an input file (by default named `file.in'), substituting the output variable values. See section Substitutions in Makefiles, for more information on using output variables. See section Setting Output Variables, for more information on creating them. This macro creates the directory that the file is in if it doesn't exist (but not the parents of that directory). Usually, `Makefile's are created this way, but other files, such as `.gdbinit', can be specified as well.

If AC_CONFIG_HEADER, AC_LINK_FILES, or AC_CONFIG_SUBDIRS has been called, this macro also creates the files named as their arguments.

A typical call to AC_OUTPUT looks like this:

AC_OUTPUT(Makefile src/Makefile man/Makefile X/Imakefile)

You can override an input file name by appending it to file, separated by a colon. For example,

AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk)

If you pass extra-cmds, those commands will be inserted into `config.status' to be run after all its other processing. If init-cmds are given, they are inserted just before extra-cmds, with shell variable, command, and backslash substitutions performed on them in configure. You can use init-cmds to pass variables from configure to the extra-cmds.

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.

Macro: AC_PROG_MAKE_SET

@maindex PROG_MAKE_SET @ovindex SET_MAKE 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@

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 section 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 section `Makefile Conventions' in The GNU Coding Standards, for more information on what to put in `Makefile's.

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 section Output Variable Index, for a complete list of output variables. Here is what each of the preset ones contains.

Variable: configure_input

@ovindex configure_input 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.

Variable: exec_prefix

@ovindex exec_prefix The installation prefix for architecture-dependent files.

Variable: prefix

@ovindex prefix The installation prefix for architecture-independent files.

Variable: srcdir

@ovindex srcdir The directory that contains the source code for that `Makefile'.

Variable: top_srcdir

@ovindex top_srcdir The top-level source code directory for the package. In the top-level directory, this is the same as srcdir.

Variable: CFLAGS

@ovindex CFLAGS 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.

Variable: CPPFLAGS

@ovindex CPPFLAGS Header file search directory (`-Idir') and any other miscellaneous options for the C preprocessor and compiler. 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 features.

Variable: CXXFLAGS

@ovindex CXXFLAGS 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.

Variable: DEFS

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

Variable: LDFLAGS

@ovindex LDFLAGS Stripping (`-s') and any other miscellaneous options for the linker. 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 features.

Variable: LIBS

@ovindex LIBS `-l' and `-L' options to pass to the linker.

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

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 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. On some old BSD systems, touch or any command that results in an empty file does not update the timestamps, so use a command like echo as a workaround.

${srcdir}/configure: configure.in 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.in aclocal.m4 acconfig.h \
    config.h.top config.h.bot
        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

In addition, you should pass `echo timestamp > stamp-h' in the extra-cmds argument to AC_OUTPUT, so `config.status' will ensure that `config.h' is considered up to date. See section Creating Output Files, for more information about AC_OUTPUT.

See section Recreating a Configuration, for more examples of handling configuration-related dependencies.

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

Macro: AC_CONFIG_HEADER (header-to-create ...)

@maindex CONFIG_HEADER @cvindex HAVE_CONFIG_H Make AC_OUTPUT create the file(s) in the whitespace-separated list header-to-create 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-to-create is `config.h'.

If header-to-create 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-to-create.in'; however, you can override the input file name by appending it to header-to-create, separated by a colon. For example,

AC_CONFIG_HEADER(defines.h:defines.hin)
Doing this allows you to keep your filenames acceptable to MS-DOS.

Configuration Header Templates

Your distribution should contain a template file that looks as you want the final header file to look, including comments, with default values in the #define statements. For example, suppose your `configure.in' makes these calls:

AC_CONFIG_HEADER(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 change the 0 to a 1. On other systems, it will leave the line unchanged.

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

Alternately, if your code tests for configuration options using #ifdef instead of #if, a default value can be to #undef the variable instead of to define it to a value. On systems that have `unistd.h', configure will change the second line to read `#define HAVE_UNISTD_H 1'. On other systems, it will comment that line out (in case the system predefines that symbol).

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

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.in' invokes AC_CONFIG_HEADER(file), autoheader creates `file.in' (if multiple header files are given, the first one is used). Otherwise, autoheader creates `config.h.in'.

If you give autoheader an argument, it uses that file instead of `configure.in' 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.in' and writes the header file to the standard output.

autoheader scans `configure.in' and figures out which C preprocessor symbols it might define. It copies comments and #define and #undef statements from a file called `acconfig.h', which comes with and is installed with Autoconf. It also uses a file called `acconfig.h' in the current directory, if present. If you AC_DEFINE any additional symbols, you must create that file with entries for them. For symbols defined by AC_CHECK_HEADERS, AC_CHECK_FUNCS, AC_CHECK_SIZEOF, or AC_CHECK_LIB, autoheader generates comments and #undef statements itself rather than copying them from a file, since the possible symbols are effectively limitless.

The file that autoheader creates contains mainly #define and #undef statements and their accompanying comments. If `./acconfig.h' contains the string `@TOP@', autoheader copies the lines before the line containing `@TOP@' into the top of the file that it generates. Similarly, if `./acconfig.h' contains the string `@BOTTOM@', autoheader copies the lines after that line to the end of the file it generates. Either or both of those strings may be omitted.

An alternate way to produce the same effect is to create the files `file.top' (typically `config.h.top') and/or `file.bot' in the current directory. If they exist, autoheader copies them to the beginning and end, respectively, of its output. Their use is discouraged because they have file names that contain two periods, and so can not be stored on MS-DOS; also, they are two more files to clutter up the directory. But if you use the `--localdir=dir' option to use an `acconfig.h' in another directory, they give you a way to put custom boilerplate in each individual `config.h.in'.

autoheader accepts the following options:

--help
-h
Print a summary of the command line options and exit.

--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 current directory.

--macrodir=dir
-m dir
@evindex AC_MACRODIR Look for the installed macro files and `acconfig.h' 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.

Configuring Other Packages in Subdirectories

In most situations, calling AC_OUTPUT is sufficient to produce `Makefile's 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.

Macro: AC_CONFIG_SUBDIRS (dir ...)

@maindex CONFIG_SUBDIRS @ovindex subdirs Make AC_OUTPUT run configure in each subdirectory dir in the given whitespace-separated list. If a given dir is not found, no error is reported, so a configure script can configure whichever parts of a large source tree are present. If a given dir contains `configure.in' but no configure, the Cygnus configure script found by AC_CONFIG_AUXDIR 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 (e.g., to adjust a relative path for the cache file or source directory). 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.

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.

Macro: AC_PREFIX_DEFAULT (prefix)

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.

Macro: AC_PREFIX_PROGRAM (program)

@maindex PREFIX_PROGRAM 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'.

Version Numbers in configure

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

Macro: AC_PREREQ (version)

@maindex PREREQ 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 on the standard error output and do not create configure. For example:

AC_PREREQ(1.8)

This macro is useful if your `configure.in' relies on non-obvious behavior that changed between Autoconf releases. If it merely needs recently added macros, then AC_PREREQ is less useful, because the autoconf program already tells the user which macros are not found. The same thing happens if `configure.in' is processed by a version of Autoconf older than when AC_PREREQ was added.

Macro: AC_REVISION (revision-info)

@maindex REVISION 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.in' into configure without RCS or CVS changing it when you check in configure. That way, you can determine easily which revision of `configure.in' a particular configure corresponds to.

It is a good idea to call this macro before AC_INIT so that the revision number is near the top of both `configure.in' and configure. To support doing that, the AC_REVISION output begins with `#! /bin/sh', like the normal start of a configure script does.

For example, this line in `configure.in':

AC_REVISION($Revision: 1.30 $)dnl

produces this in configure:

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

Go to the previous, next section.