4. 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 the initialization and the creation of output files.

4.1 Initializing configure

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

Macro: AC_INIT (package, version, [bug-report], [tarname])

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 former is meant for distribution tar ball names (e.g., `autoconf'). It defaults to package with `GNU ' stripped, lower-cased, and all characters other than alphanumerics and underscores are changed to `-'.

It is preferable that the arguments of AC_INIT 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 defined by AC_INIT:

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.

4.2 Notices in configure

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

Macro: AC_PREREQ (version)

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.57)

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

Macro: AC_COPYRIGHT (copyright-notice)

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

Macro: AC_REVISION (revision-info)

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.1 $)

produces this in configure:

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

4.3 Finding configure Input

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

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

Macro: AC_CONFIG_AUX_DIR (dir)

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

4.4 Outputting Files

Every Autoconf script, e.g., `configure.ac', should finish by calling AC_OUTPUT. That is the macro that generates `config.status', which will create the `Makefile's and any other files resulting from configuration. This is the only required macro besides AC_INIT (see section Finding configure Input).

Macro: AC_OUTPUT

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

`config.status' will perform all the configuration actions: all the output files (see Creating Configuration Files, macro AC_CONFIG_FILES), header files (see Configuration Header Files, macro AC_CONFIG_HEADERS), commands (see Running Arbitrary Configuration Commands, macro AC_CONFIG_COMMANDS), links (see Creating Configuration Links, macro AC_CONFIG_LINKS), subdirectories to configure (see Configuring Other Packages in Subdirectories, macro AC_CONFIG_SUBDIRS) are honored.

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

If you run make in 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

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

If you use this macro, place a line like this in each `Makefile.in' that runs MAKE on other directories:

@SET_MAKE@

4.5 Performing 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 Recreating a Configuration, 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 variables 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!

4.6 Creating Configuration Files

Be sure to read the previous section, Performing Configuration Actions.

Macro: AC_CONFIG_FILES (file…, [cmds], [init-cmds])

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 Performing Configuration Actions. 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. Usually, `Makefile's 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.

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

4.7.1 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. See section 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 section Setting Output Variables, AC_ARG_VAR).

Variable: 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: 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: CPPFLAGS

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.

Variable: 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

`-D' options to pass to the C compiler. If AC_CONFIG_HEADERS 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: ECHO_C

Variable: ECHO_N

Variable: ECHO_T

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.

Variable: FFLAGS

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.

Variable: LDFLAGS

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.

Variable: LIBS

`-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 Library Files. configure uses this variable when linking programs to test for C, C++ and Fortran 77 features.

Variable: builddir

Rigorously equal to `.'. Added for symmetry only.

Variable: abs_builddir

Absolute path of builddir.

Variable: top_builddir

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

Variable: abs_top_builddir

Absolute path of top_builddir.

Variable: srcdir

The relative path to the directory that contains the source code for that `Makefile'.

Variable: abs_srcdir

Absolute path of srcdir.

Variable: top_srcdir

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

Variable: abs_top_srcdir

Absolute path of top_srcdir.

4.7.2 Installation Directory Variables

The following variables specify the directories where the package will be installed, see (standards)Directory Variables section `Variables for Installation Directories' in The GNU Coding Standards, for more information. See the end of this section for details on when and how to use these variables.

Variable: bindir

The directory for installing executables that users run.

Variable: datadir

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

Variable: exec_prefix

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.

Variable: includedir

The directory for installing C header files.

Variable: infodir

The directory for installing documentation in Info format.

Variable: libdir

The directory for installing object code libraries.

Variable: libexecdir

The directory for installing executables that other programs run.

Variable: localstatedir

The directory for installing modifiable single-machine data.

Variable: mandir

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

Variable: oldincludedir

The directory for installing C header files for non-GCC compilers.

Variable: prefix

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

Variable: sbindir

The directory for installing executables that system administrators run.

Variable: sharedstatedir

The directory for installing modifiable architecture-independent data.

Variable: sysconfdir

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 hard-coding 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 `.in', and uses a Makefile snippet similar to:

edit = sed \
        -e 's,@datadir\@,$(pkgdatadir),g' \
        -e 's,@prefix\@,$(prefix),g'

autoconf: Makefile $(srcdir)/autoconf.in
        rm -f autoconf autoconf.tmp
        $(edit) $(srcdir)/autoconf.in >autoconf.tmp
        chmod +x autoconf.tmp
        mv autoconf.tmp autoconf

autoheader: Makefile $(srcdir)/autoheader.in
        rm -f autoheader autoheader.tmp
        $(edit) $(srcdir)/autoconf.in >autoheader.tmp
        chmod +x autoheader.tmp
        mv autoheader.tmp autoheader

Some details 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 likely the variables you use, such as `$(pkgdatadir)', will contain some.

` Dependency on `Makefile' '

Since edit uses values that depend on the configuration specific values (prefix etc.) and not only on VERSION and so forth, the output depends on `Makefile', not `configure.ac'.

` Separated dependencies and Single Suffix Rules '

You can't use them! The above snippet cannot be (portably) rewritten as:

autoconf autoheader: Makefile .in: rm -f $@ $@.tmp $(edit) $< >$@.tmp chmod +x $@.tmp mv $@.tmp $@

See section Limitations of Make, for details.

` `$(srcdir)' '

Be sure to specify the path to the sources, otherwise the package won't support separated builds.

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

4.7.4 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 section 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 section Outputting Files, for more information about AC_OUTPUT.

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

4.8 Configuration Header Files

When a package contains more than a few tests that define 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.

Macro: AC_CONFIG_HEADERS (header …, [cmds], [init-cmds])

This macro is one of the instantiating macros; see Performing 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 making some changes in the 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 section Performing Configuration Actions, for more details on header.

4.8.1 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

Pay attention that `#undef' is in the first column, and there is nothing behind `HAVE_UNISTD_H', not even white spaces. 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. Similarly with old templates with comments on the same line as the `#undef'. Anyway, putting comments in preprocessor macros has never been a good idea.

Since it is a tedious task to keep a template header up to date, you may use autoheader to generate it, see Using autoheader to Create `config.h.in'.

4.8.2 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 call with a third argument for each symbol (see section Defining C Preprocessor Symbols). An additional constraint is that the first argument of AC_DEFINE must be a literal. Note that all symbols defined by Autoconf's builtin 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 '

Append dir to include path. Multiple invocations accumulate.

` --prepend-include=dir '

` -B dir '

Prepend dir to include path. Multiple invocations accumulate.

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

4.8.3 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 C Preprocessor Symbols. You may also use one of the following macros.

Macro: AH_VERBATIM (key, template)

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 a 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])

Macro: AH_TEMPLATE (key, description)

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

Macro: AH_TOP (text)

Include text at the top of the header template file.

Macro: AH_BOTTOM (text)

Include text at the bottom of the header template file.

4.9 Running Arbitrary Configuration Commands

You can execute arbitrary commands 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.

Macro: AC_CONFIG_COMMANDS (tag…, [cmds], [init-cmds])

Specify additional shell commands to run at the end of `config.status', and shell commands to initialize any variables from configure. Associate the commands with 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 Performing 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])

Macro: AC_CONFIG_COMMANDS_PRE (cmds)

Execute the cmds right before creating `config.status'.

Macro: AC_CONFIG_COMMANDS_POST (cmds)

Execute the cmds right after creating `config.status'.

4.10 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 a directory different from the source directory.

Macro: AC_CONFIG_LINKS (dest:source…, [cmds], [init-cmds])

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 if possible, otherwise a copy. 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 Performing 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.

4.11 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 …)

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.in' 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 the default values of the top level and of the subdirectory `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.

4.12 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 other than `/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)

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, else default the prefix as described above (`/usr/local' or AC_PREFIX_DEFAULT). For example, if program is gcc and the PATH contains `/usr/local/gnu/bin/gcc', set the prefix to `/usr/local/gnu'.

This document was generated by John Paul Wallington on October, 29 2003 using texi2html 1.67.