available. If the results of the check were in the cache file that was
read, and @code{configure} was not given the @option{--quiet} or
@option{--silent} option, print a message saying that the result was
-cached; otherwise, run the shell commands @var{commands-to-set-it}.
-Those commands should have no side effects except for setting the
-variable @var{cache-id}. In particular, they should not call
-@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL}
-should do that, based on the cached value. Also, they should not print
-any messages, for example with @code{AC_MSG_CHECKING}; do that before
-calling @code{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 @code{configure} creates its output files. @xref{Cache
-Variable Names}, for how to choose the name of the @var{cache-id} variable.
-@end defmac
-
-@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands})
+cached; otherwise, run the shell commands @var{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 @code{configure} creates its output
+files. @xref{Cache Variable Names}, for how to choose the name of the
+@var{cache-id} variable.
+
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+@end defmac
+
+@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
@maindex CACHE_CHECK
A wrapper for @code{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 @code{AC_MSG_CHECKING} for
@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
-@end defmac
-@defmac AC_CACHE_LOAD
-@maindex CACHE_LOAD
-Loads values from existing cache file, or creates a new cache file if a
-cache file is not found. Called automatically from @code{AC_INIT}.
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
@end defmac
-@defmac AC_CACHE_SAVE
-@maindex CACHE_SAVE
-Flushes all cached values to the cache file. Called automatically from
-@code{AC_OUTPUT}, but it can be quite useful to call
-@code{AC_CACHE_SAVE} at key points in configure.in. Doing so
-checkpoints the cache in case of an early configure script abort.
-@end defmac
+It is very common to find buggy macros using @code{AC_CACHE_VAL} or
+@code{AC_CACHE_CHECK} because people are tempted to call
+@code{AC_DEFINE} in the @var{commands-to-set-it}. It is the code that
+follows the call to @code{AC_CACHE_VAL} should do that, based on the
+cached value. For instance the following macro:
+
+@example
+@group
+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[]dnl
+])])
+@end group
+@end example
+
+@noindent
+is broken: if the cache is enabled, the second time this macro is run,
+@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
+is:
+
+@example
+@group
+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[]dnl
+])
+@end group
+@end example
+
+Also, @var{commands-to-set-it} should not print any messages, for
+example with @code{AC_MSG_CHECKING}; do that before calling
+@code{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
transparently, as long as the same C compiler is used every time
(@pxref{Site Defaults}).
-If your configure script, or a macro called from configure.in, happens to
-abort the configure process, it may be useful to checkpoint the cache a
-few times at key points. 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.
+If your configure script, or a macro called from configure.in, happens
+to abort the configure process, it may be useful to checkpoint the cache
+a few times at key points using @code{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.
+
+@c FIXME: Do we really want to document this guy?
+@defmac AC_CACHE_LOAD
+@maindex CACHE_LOAD
+Loads values from existing cache file, or creates a new cache file if a
+cache file is not found. Called automatically from @code{AC_INIT}.
+@end defmac
+
+@defmac AC_CACHE_SAVE
+@maindex CACHE_SAVE
+Flushes all cached values to the cache file. Called automatically from
+@code{AC_OUTPUT}, but it can be quite useful to call
+@code{AC_CACHE_SAVE} at key points in configure.in.
+@end defmac
+
+For instance:
@example
@r{ ... AC_INIT, etc. ...}
+@group
# Checks for programs.
AC_PROG_CC
AC_PROG_GCC_TRADITIONAL
@r{ ... more program checks ...}
AC_CACHE_SAVE
+@end group
+@group
# Checks for libraries.
AC_CHECK_LIB(nsl, gethostbyname)
AC_CHECK_LIB(socket, connect)
@r{ ... more lib checks ...}
AC_CACHE_SAVE
+@end group
+@group
# Might abort...
AM_PATH_GTK(1.0.2,, (exit 1); exit)
AM_PATH_GTKMM(0.9.5,, (exit 1); exit)
+@end group
@r{ ... AC_OUTPUT, etc. ...}
@end example
projects / thirdparty / autoconf.git / commitdiff
