File: autoconf.info,  Node: Caching Results,  Next: Printing Messages,  Prev: Special Chars in Variables,  Up: Results

7.4 Caching Results
===================

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” (*note
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.

 -- Macro: AC_CACHE_VAL (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 is saved in the
     cache file just before ‘configure’ creates its output files.  *Note
     Cache Variable Names::, for how to choose the name of the CACHE-ID
     variable.

     The COMMANDS-TO-SET-IT _must have no side effects_ except for
     setting the variable CACHE-ID, see below.

 -- Macro: AC_CACHE_CHECK (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-IT _must have no side effects_ except for
     setting the variable CACHE-ID, see below.

   It is 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], [my_cv_shell_true_works],
                     [my_cv_shell_true_works=no
                      (true) 2>/dev/null && my_cv_shell_true_works=yes
                      if test "x$my_cv_shell_true_works" = xyes; 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_WORKS’ _will not be defined_.  The proper implementation is:

     AC_DEFUN([AC_SHELL_TRUE],
     [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
                     [my_cv_shell_true_works=no
                      (true) 2>/dev/null && my_cv_shell_true_works=yes])
      if test "x$my_cv_shell_true_works" = xyes; 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.

* Menu:

* Cache Variable Names::        Shell variables used in caches
* Cache Files::                 Files ‘configure’ uses for caching
* Cache Checkpointing::         Loading and saving the cache file