Go to the first, previous, next, last section, table of contents.
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.
configure
The following macros manage version numbers for configure
scripts. Using them is optional.
configure is earlier
than version, print an error message to the standard error output
and do not create configure. For example:
AC_PREREQ(2.52)
This macro is the only macro that may be used before AC_INIT, but
for consistency, you are invited not to do so.
configure are covered by the
copyright-notice.
The copyright-notice will show up in both the head of
configure and in `configure --version'.
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
configure Input
Every configure script must call AC_INIT before doing
anything else. The only other required macro is AC_OUTPUT
(see section Outputting 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 @option{--srcdir}; this is a safety check. See section @code{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.
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 @command{make} 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 generates `config.status',
which will create the `Makefile's and any other files resulting
from configuration. The only other required macro is AC_INIT
(see section Finding configure Input).
`config.status' will take all the configuration actions: all the
output files (see section Creating Configuration Files, macro
AC_CONFIG_FILES), header files (see section Configuration Header Files,
macro AC_CONFIG_HEADERS), commands (see section Running Arbitrary Configuration Commands, macro AC_CONFIG_COMMANDS), links (see
section Creating Configuration Links, macro AC_CONFIG_LINKS), subdirectories
to configure (see section 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 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@
`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:
var. init-cmds
is typically used by `configure' to give `config.status' some
variables it needs to run the commands.
All these macros can be called multiple times, with different tags, of course!
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 macro AC_CONFIG_FILES and AC_CONFIG_HEADERS use
specials tags: they may have the form `output' or
`output:inputs'. The file output is instantiated
from its templates, inputs if specified, 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 section 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.
Be sure to read the previous section, section Taking Configuration Actions.
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 section Taking 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.
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. 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).
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 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.
configure runs, the default
value is empty. configure uses this variable when compiling or
preprocessing programs to test for C and 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_HEADERS
is called, configure replaces `@DEFS@' with
@option{-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.
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.
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.
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.
configure uses this variable when linking
programs to test for C, C++ and Fortran 77 features.
srcdir.
The following variables specify the directories where the package will be installed, see 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.
Most of these variables have values that rely on prefix or
exec_prefix. It is on purpose 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:
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 but 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 @command{make} manage their replacement. For instance Autoconf
ships templates of its shell scripts ending with `.sh', and uses
this Makefile snippet:
.sh:
rm -f $@ [email protected]
sed 's,@datadir\@,$(pkgdatadir),g' $< >[email protected]
chmod +x [email protected]
mv [email protected] $@
Three things are noteworthy:
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
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 @command{make} will consider `config.h.in' up to date. Don't use @command{touch} (see section Limitations of Usual Tools), rather use @command{echo} (using @command{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.
When a package tests more than a few C preprocessor symbols, the command
lines to pass @option{-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 @option{-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
@option{-I.} option (or @option{-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 containing C preprocessor
#define statements, and replace `@DEFS@' in generated
files with @option{-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 section Taking Configuration Actions, for more details on header.
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 section Using autoheader to Create `config.h.in'.
autoheader to Create `config.h.in'
The @command{autoheader} program can create a template file of C
`#define' statements for configure to use. If
`configure.ac' invokes AC_CONFIG_HEADERS(file),
@command{autoheader} creates `file.in'; if multiple file
arguments are given, the first one is used. Otherwise,
@command{autoheader} creates `config.h.in'.
In order to do its job, @command{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 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 built-in tests are
already documented properly; you only need to document those that you
define yourself.
You might wonder why @command{autoheader} is needed: after all, why would @command{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 @command{autoheader}: generating `config.h' directly is all that is needed. When things go wrong, however, you'll be thankful for the existence of @command{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
@command{configure} cannot be run: they just have to @emph{fill in the
blanks}.
But let's come back to the point: @command{autoheader}'s invocation...
If you give @command{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 @command{autoheader} an argument of @option{-}, it reads the standard input instead of `configure.ac' and writes the header file to the standard output.
autoheader accepts the following options:
AC_MACRODIR environment variable to a
directory; this option overrides the environment variable.
This option is rarely needed and dangerous; it is only used when one
plays with different versions of Autoconf simultaneously.
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 section Defining C Preprocessor Symbols. You may also use one of the following macros.
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])
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
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 section Obsolete Macros, for details.
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 section Taking 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])
configure:
AC_CONFIG_COMMANDS_PRE( [LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'` AC_SUBST(LTLIBOBJS)])
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_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 section Taking 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.
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. 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, 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.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 (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. This macro may be called multiple
times.
By default, configure sets the prefix for files it installs to
`/usr/local'. The user of configure can select a different
prefix using the @option{--prefix} and @option{--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'.
Go to the first, previous, next, last section, table of contents.