Go to the previous, next section.
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
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 (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.
@maindex CONFIG_AUX_DIR
Use the `install-sh', `config.sub', `config.guess', and
Cygnus
Every Autoconf-generated
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
A typical call to
You can override an input file name by appending it to file,
separated by a colon. For example,
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
If you run
@maindex PROG_MAKE_SET
@ovindex SET_MAKE
If
To use this macro, place a line like this in each `Makefile.in'
that runs
Each subdirectory in a distribution that contains something to be
compiled or installed should come with a file `Makefile.in', from
which
A software package that uses a
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.
@ovindex configure_input
A comment saying that the file was generated automatically by
The presence of that line also reminds people editing the file that it
needs to be processed by
@ovindex exec_prefix
The installation prefix for architecture-dependent files.
@ovindex prefix
The installation prefix for architecture-independent files.
@ovindex srcdir
The directory that contains the source code for that `Makefile'.
@ovindex top_srcdir
The top-level source code directory for the package. In the top-level
directory, this is the same as
@ovindex CFLAGS
Debugging and optimization options for the C compiler. If it is not set
in the environment when
@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
@ovindex CXXFLAGS
Debugging and optimization options for the C++ compiler. If it is not
set in the environment when
@ovindex DEFS
`-D' options to pass to the C compiler. If
@ovindex LDFLAGS
Stripping (`-s') and any other miscellaneous options for the
linker. If it is not set in the environment when
@ovindex LIBS
`-l' and `-L' options to pass to the linker.
You might want to compile a software package in a different directory
from the one that contains the source code. Doing this allows you to
compile the package for several architectures simultaneously from the
same copy of the source code and keep multiple sets of object files on
disk.
To support doing this,
To support
Do not set
Do not use the
Instead, `Makefile' command lines should always refer to source
files by prefixing them with `$(srcdir)/'. For example:
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
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
In addition, you should pass `date > stamp-h' in the extra-cmds
argument to
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
The package should `#include' the configuration header file before
any other header files, to prevent inconsistencies in declarations (for
example, if it redefines
Macro: AC_CONFIG_HEADER (header-to-create ...)
@maindex CONFIG_HEADER
@cvindex HAVE_CONFIG_H
Make
If header-to-create already exists and its contents are identical
to what
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,
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
Then you could have code like the following in `conf.h.in'.
On systems that have `unistd.h',
Alternately, if your code tests for configuration options using
The
If you give
The file that
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,
In most situations, calling
Macro: AC_CONFIG_SUBDIRS (dir ...)
@maindex CONFIG_SUBDIRS
@ovindex subdirs
Make
By default,
Some software packages might want to install in a directory besides
`/usr/local' by default. To accomplish that, use the
Macro: AC_PREFIX_DEFAULT (prefix)
Set the default installation prefix to prefix instead of `/usr/local'.
It may be convenient for users to have
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
The following macros manage version numbers for
@maindex PREREQ
Ensure that a recent enough version of Autoconf is being used. If the
version of Autoconf being used to create
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
Macro: AC_REVISION (revision-info)
@maindex REVISION
Copy revision stamp revision-info into the
It is a good idea to call this macro before
For example, this line in `configure.in':
produces this in
Go to the previous, next section.
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
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).
AC_CONFIG_HEADER
, AC_LINK_FILES
, or
AC_CONFIG_SUBDIRS
has been called, this macro also creates the
files named as their arguments.
AC_OUTPUT
looks like this:
AC_OUTPUT(Makefile src/Makefile man/Makefile X/Imakefile)
AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk)
configure
. You can use
init-cmds to pass variables from configure
to the
extra-cmds.
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
.
MAKE
on other directories:
@SET_MAKE@
Substitutions in Makefiles
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
.
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.
Preset Output Variables
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@
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.
Build Directories
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.
VPATH
, each `Makefile.in' should contain two
lines that look like:
srcdir = @srcdir@
VPATH = @srcdir@
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.in'.
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.
time.info: time.texinfo
$(MAKEINFO) $(srcdir)/time.texinfo
Automatic Remaking
VPATH
mechanism.
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 date
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
date > ${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
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
.
Configuration Header Files
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
.
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'.
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.
AC_CONFIG_HEADER(defines.h:defines.hin)
Doing this allows you to keep your filenames acceptable to MS-DOS.
Configuration Header Templates
#define
statements. For example, suppose your
`configure.in' makes these calls:
AC_CONFIG_HEADER(conf.h)
AC_CHECK_HEADERS(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
#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'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'. Otherwise,
autoheader
creates `config.h.in'.
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.
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.
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
Configuring Other Packages in Subdirectories
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.
Default Prefix
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.
AC_PREFIX_DEFAULT
macro.
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'.
Version Numbers in
configure
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)
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.
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.
AC_REVISION($Revision: 1.30 $)dnl
configure
:
#!/bin/sh
# From configure.in Revision: 1.30