Once configure has determined whether a feature exists, what can
it do to record that information? There are four sorts of things it can
do: define a C preprocessor symbol, set a variable in the output files,
save the result in a cache file for future configure runs, and
print a message letting the user know the result of the test.
configure runs.
A common action to take in response to a feature test is to define a C
preprocessor symbol indicating the results of the test. That is done by
calling AC_DEFINE or AC_DEFINE_UNQUOTED.
By default, AC_OUTPUT places the symbols defined by these macros
into the output variable DEFS, which contains an option
`-Dsymbol=value' for each symbol defined. Unlike in
Autoconf version 1, there is no variable DEFS defined while
configure is running. To check whether Autoconf macros have
already defined a certain C preprocessor symbol, test the value of the
appropriate cache variable, as in this example:
AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF)) if test "$ac_cv_func_vprintf" != yes; then AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT)) fi
If AC_CONFIG_HEADER has been called, then instead of creating
DEFS, AC_OUTPUT creates a header file by substituting the
correct values into #define statements in a template file.
See section Configuration Header Files, for more information about this kind of
output.
AC_CONFIG_HEADER it should not contain any `#'
characters, as make tends to eat them. To use a shell variable
(which you need to do in order to define a value containing the
m4 quote characters `[' or `]'), use
AC_DEFINE_UNQUOTED instead. The following example defines the C
preprocessor variable EQUATION to be the string constant
`"$a > $b"':
AC_DEFINE(EQUATION, "$a > $b")
AC_DEFINE, but three shell expansions are
performed--once--on variable and value: variable expansion
(`$'), command substitution (``'), and backslash escaping
(`\'). Single and double quote characters in the value have no
special meaning. Use this macro instead of AC_DEFINE when
variable or value is a shell variable. Examples:
AC_DEFINE_UNQUOTED(config_machfile, "${machfile}")
AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
AC_DEFINE_UNQUOTED(${ac_tr_hdr})
Due to the syntactical bizarreness of the Bourne shell, do not use
semicolons to separate AC_DEFINE or AC_DEFINE_UNQUOTED
calls from other macro calls or shell code; that can cause syntax errors
in the resulting configure script. Use either spaces or
newlines. That is, do this:
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf")
or this:
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf")
instead of this:
AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf")
One way to record the results of tests is to set output variables,
which are shell variables whose values are substituted into files that
configure outputs. The two macros below create new output
variables. See section Preset Output Variables, for a list of output
variables that are always available.
AC_OUTPUT
substitute the variable variable into output files (typically one
or more `Makefile's). This means that AC_OUTPUT will
replace instances of `@variable@' in input files with the
value that the shell variable variable has when AC_OUTPUT
is called. The value of variable should not contain literal
newlines.
AC_OUTPUT insert (without substitutions) the contents of the file
named by shell variable variable into output files. This means
that AC_OUTPUT will replace instances of
`@variable@' in output files (such as `Makefile.in')
with the contents of the file that the shell variable variable
names when AC_OUTPUT is called. Set the variable to
`/dev/null' for cases that do not have a file to insert.
This macro is useful for inserting `Makefile' fragments containing
special dependencies or other make directives for particular host
or target types into `Makefile's. For example, `configure.in'
could contain:
AC_SUBST_FILE(host_frag)dnl host_frag=$srcdir/conf/sun4.mh
and then a `Makefile.in' could contain:
@host_frag@
To avoid checking for the same features repeatedly in various
configure scripts (or repeated runs of one script),
configure saves the results of many of its checks in a cache
file. If, when a configure script runs, it finds a cache file,
it reads from it the results from previous runs and avoids rerunning
those checks. As a result, configure can run much faster than if
it had to perform all of the checks every time.
configure was not given the `--quiet' or
`--silent' option, print a message saying that the result was
cached; otherwise, run the shell commands commands-to-set-it.
Those commands should have no side effects except for setting the
variable cache-id. In particular, they should not call
AC_DEFINE; the code that follows the call to AC_CACHE_VAL
should do that, based on the cached value. Also, they should not print
any messages, for example with AC_MSG_CHECKING; do that before
calling AC_CACHE_VAL, so the messages are printed regardless of
whether the results of the check are retrieved from the cache or
determined by running the shell commands. If the shell commands are run
to determine the value, the value will be saved in the cache file just
before configure creates its output files. See section Cache Variable Names, for how to choose the name of the cache-id variable.
AC_CACHE_VAL that takes care of printing the
messages. This macro provides a convenient shorthand for the most
common way to use these macros. It calls AC_MSG_CHECKING for
message, then AC_CACHE_VAL with the cache-id and
commands arguments, and AC_MSG_RESULT with cache-id.
configure uses for caching.
The names of cache variables should have the following format:
package-prefix_cv_value-type_specific-value[_additional-options]
for example, `ac_cv_header_stat_broken' or `ac_cv_prog_gcc_traditional'. The parts of the variable name are:
_cv_
Like their names, the values that may be assigned to cache variables have a few restrictions. The values may not contain single quotes or curly braces. Usually, their values will be boolean (`yes' or `no') or the names of files or functions; so this is not an important restriction.
A cache file is a shell script that caches the results of configure tests run on one system so they can be shared between configure scripts and configure runs. It is not useful on other systems. If its contents are invalid for some reason, the user may delete or edit it.
By default, configure uses `./config.cache' as the cache file,
creating it if it does not exist already. configure accepts the
`--cache-file=file' option to use a different cache file;
that is what configure does when it calls configure
scripts in subdirectories, so they share the cache.
See section Configuring Other Packages in Subdirectories, for information on configuring subdirectories
with the AC_CONFIG_SUBDIRS macro.
Giving `--cache-file=/dev/null' disables caching, for debugging
configure. `config.status' only pays attention to the cache
file if it is given the `--recheck' option, which makes it rerun
configure. If you are anticipating a long debugging period, you
can also disable cache loading and saving for a configure script
by redefining the cache macros at the start of `configure.in':
define([AC_CACHE_LOAD], )dnl define([AC_CACHE_SAVE], )dnl AC_INIT(whatever) ... rest of configure.in ...
It is wrong to try to distribute cache files for particular system types. There is too much room for error in doing that, and too much administrative overhead in maintaining them. For any features that can't be guessed automatically, use the standard method of the canonical system type and linking files (see section Manual Configuration).
The cache file on a particular system will gradually accumulate whenever
someone runs a configure script; it will be initially
nonexistent. Running configure merges the new cache results with
the existing cache file. The site initialization script can specify a
site-wide cache file to use instead of the default, to make it work
transparently, as long as the same C compiler is used every time
(see section Setting Site Defaults).
configure scripts need to give users running them several kinds
of information. The following macros print messages in ways appropriate
for each kind. The arguments to all of them get enclosed in shell
double quotes, so the shell performs variable and backquote substitution
on them.
These macros are all wrappers around the echo shell command.
configure scripts should rarely need to run echo directly
to print messages for the user. Using these macros makes it easy to
change how and when each kind of message is printed; such changes need
only be made to the macro definitions, and all of the callers change
automatically.
configure is checking for a particular
feature. This macro prints a message that starts with `checking '
and ends with `...' and no newline. It must be followed by a call
to AC_MSG_RESULT to print the result of the check and the
newline. The feature-description should be something like
`whether the Fortran compiler accepts C++ comments' or `for
c89'.
This macro prints nothing if configure is run with the
`--quiet' or `--silent' option.
AC_MSG_CHECKING, and the result-description should be
the completion of the message printed by the call to
AC_MSG_CHECKING.
This macro prints nothing if configure is run with the
`--quiet' or `--silent' option.
configure from
completing. This macro prints an error message on the standard error
output and exits configure with a nonzero status.
error-description should be something like `invalid value
$HOME for \$HOME'.
configure user of a possible problem. This macro
prints the message on the standard error output; configure
continues running afterward, so macros that call AC_MSG_WARN should
provide a default (back-up) behavior for the situations they warn about.
problem-description should be something like `ln -s seems to
make hard links'.
The following two macros are an obsolete alternative to
AC_MSG_CHECKING and AC_MSG_RESULT.
AC_MSG_CHECKING, except that it prints a
newline after the feature-description. It is useful mainly to
print a general description of the overall purpose of a group of feature
checks, e.g.,
AC_CHECKING(if stack overflow is detectable)
AC_MSG_RESULT, except that it is meant
to follow a call to AC_CHECKING instead of
AC_MSG_CHECKING; it starts the message it prints with a tab. It
is considered obsolete.