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.
configure.
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).
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.
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'.
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).
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.
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@
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.
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. See section `Variables for Installation Directories' in The GNU Coding Standards, for more information about the variables with names that end in `dir'.
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.
srcdir.
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 runs, the default value is
empty. configure uses this variable when compiling or
preprocessing programs to test for C features.
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.
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.
configure runs,
the default value is empty. configure uses this variable when
linking programs to test for C features.
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
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.
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.
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.
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
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 file
arguments 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
--localdir=dir
-l dir
--macrodir=dir
-m dir
AC_MACRODIR environment variable
to a directory; this option overrides the environment variable.
--version
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.
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.
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.
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.
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'.
configure
The following macros manage version numbers for configure
scripts. Using them is optional.
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.
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