To avoid checking for the same features repeatedly in various configure scripts (or in repeated runs of one script), configure can optionally save the results of many checks in a cache file (the section called “Cache Files ”). If a configure script runs with caching enabled and finds a cache file, it reads the results of previous runs from the cache and avoids rerunning those checks. As a result, configure can then run much faster than if it had to perform all of the checks every time.
function>AC_CACHE_VAL/function> (cache-id, commands-to-set-it) Ensure that the results of the check identified by cache-id are available. If the results of the check were in the cache file that was read, and 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. 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. the section called “Cache Variable Names”, for how to choose the name of the cache-id variable.
The commands-to-set-itmust have no side effects except for setting the variable cache-id, see below.
function>AC_CACHE_CHECK/function> (message, cache-id, commands-to-set-it) A wrapper for 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.
The commands-to-set-itmust have no side effects except for setting the variable cache-id, see below.
It is very common to find buggy macros using AC_CACHE_VAL or AC_CACHE_CHECK, because people are tempted to call AC_DEFINE in the commands-to-set-it. Instead, the code that follows the call to AC_CACHE_VAL should call AC_DEFINE, by examining the value of the cache variable. For instance, the following macro is broken:
AC_DEFUN([AC_SHELL_TRUE], [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], [ac_cv_shell_true_works=no true ac_cv_shell_true_works=yes if test $ac_cv_shell_true_works = yes; then AC_DEFINE([TRUE_WORKS], 1 [Define if `true(1)' works properly.]) fi]) ])
This fails if the cache is enabled: the second time this macro is run, TRUE_WORKSwill not be defined. The proper implementation is:
AC_DEFUN([AC_SHELL_TRUE], [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], [ac_cv_shell_true_works=no true ac_cv_shell_true_works=yes]) if test $ac_cv_shell_true_works = yes; then AC_DEFINE([TRUE_WORKS], 1 [Define if `true(1)' works properly.]) fi ])
Also, commands-to-set-it 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.
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:
An abbreviation for your package or organization; the same prefix you begin local Autoconf macros with, except lowercase by convention. For cache values used by the distributed Autoconf macros, this value is ac.
Indicates that this shell variable is a cache value. This string must be present in the variable name, including the leading underscore.
A convention for classifying cache values, to produce a rational naming system. The values used in Autoconf are listed in the section called “Macro Names”.
Which member of the class of cache values this test applies to. For example, which function (alloca), program (gcc), or output variable (INSTALL).
Any particular behavior of the specific member that this test applies to. For example, broken or set. This part of the name may be omitted if it does not apply.
The values assigned to cache variables may not contain newlines. 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 no cache file (technically, it uses -cache-file=/dev/null), to avoid problems caused by accidental use of stale cache files.
To enable caching, configure accepts -config-cache (or -C) to cache results in the file config.cache. Alternatively, -cache-file=file specifies that file be the cache file. The cache file is created if it does not exist already. When configure calls configure scripts in subdirectories, it uses the -cache-file argument so that they share the same cache. the section called “Configuring Other Packages in Subdirectories”, for information on configuring subdirectories with the AC_CONFIG_SUBDIRS macro.
config.status only pays attention to the cache file if it is given the -recheck option, which makes it rerun configure.
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 (Chapter 12).
The site initialization script can specify a site-wide cache file to use, instead of the usual per-program cache. In this case, the cache file will gradually accumulate information whenever someone runs a new configure script. (Running configure merges the new cache results with the existing cache file.) This may cause problems, however, if the system configuration (e.g. the installed libraries or compilers) changes and the stale cache file is not deleted.
If your configure script, or a macro called from configure.ac, happens to abort the configure process, it may be useful to checkpoint the cache a few times at key points using AC_CACHE_SAVE. Doing so will reduce the amount of time it takes to re-run the configure script with (hopefully) the error that caused the previous abort corrected.
function>AC_CACHE_LOAD/function> Loads values from existing cache file, or creates a new cache file if a cache file is not found. Called automatically from AC_INIT.
function>AC_CACHE_SAVE/function> Flushes all cached values to the cache file. Called automatically from AC_OUTPUT, but it can be quite useful to call AC_CACHE_SAVE at key points in configure.ac.
For instance:
… AC_INIT, etc. … # Checks for programs. AC_PROG_CC AC_PROG_GCC_TRADITIONAL … more program checks … AC_CACHE_SAVE # Checks for libraries. AC_CHECK_LIB(nsl, gethostbyname) AC_CHECK_LIB(socket, connect) … more lib checks … AC_CACHE_SAVE # Might abort... AM_PATH_GTK(1.0.2,, [AC_MSG_ERROR([GTK not in path])]) AM_PATH_GTKMM(0.9.5,, [AC_MSG_ERROR([GTK not in path])]) … AC_OUTPUT, etc. …