* doc/autoconf.texi (Caching Results): Bigger warning about the

extremely frequent action-in-commands bug.
Move the documentation of AC_CACHE_SAVE and AC_CACHE_LOAD...
(Cache Files): in here.

ChangeLog

@@ -1,3 +1,10 @@
+2000-06-13  Akim Demaille  <akim@epita.fr>
+
+	* doc/autoconf.texi (Caching Results): Bigger warning about the
+	extremely frequent action-in-commands bug.
+	Move the documentation of AC_CACHE_SAVE and AC_CACHE_LOAD...
+	(Cache Files): in here.
+
 2000-06-09  Steven G. Johnson  <stevenj@alum.mit.edu>
 
 	* acgeneral.m4 (AC_CHECK_TOOL): Even if VALUE-IF-NOT-FOUND is not

configure

@@ -1318,6 +1318,12 @@ SHELL=${CONFIG_SHELL-/bin/sh}
 config_files="\
   acversion.m4 Makefile m4/Makefile man/Makefile doc/Makefile tests/Makefile
   tests/atconfig"
+EOF
+# Be careful that the expansion of AC_LIST_LINKS (which may contain
+# uses of shell variables) is itself expanded in an unquoted `here'-document.
+cat >>$CONFIG_STATUS <<EOF
+EOF
+cat >>$CONFIG_STATUS <<\EOF
 
 ac_cs_usage="\
 \`$me' instantiates files from templates according to the

doc/autoconf.texi

@@ -5367,42 +5367,72 @@ Ensure that the results of the check identified by @var{cache-id} are
 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}.
+cached; otherwise, run the shell commands @var{commands-to-set-it}.  If
-Those commands should have no side effects except for setting the
+the shell commands are run to determine the value, the value will be
-variable @var{cache-id}.  In particular, they should not call
+saved in the cache file just before @code{configure} creates its output
-@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL}
+files.  @xref{Cache Variable Names}, for how to choose the name of the
-should do that, based on the cached value.  Also, they should not print
+@var{cache-id} variable.
-any messages, for example with @code{AC_MSG_CHECKING}; do that before
+
-calling @code{AC_CACHE_VAL}, so the messages are printed regardless of
+The @var{commands-to-set-it} @emph{must have no side effects} except for
-whether the results of the check are retrieved from the cache or
+setting the variable @var{cache-id}, see below.
-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})
+@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}.
+
+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_LOAD
+It is very common to find buggy macros using @code{AC_CACHE_VAL} or
-@maindex CACHE_LOAD
+@code{AC_CACHE_CHECK} because people are tempted to call
-Loads values from existing cache file, or creates a new cache file if a
+@code{AC_DEFINE} in the @var{commands-to-set-it}. It is the code that
-cache file is not found.  Called automatically from @code{AC_INIT}.
+follows the call to @code{AC_CACHE_VAL} should do that, based on the
-@end defmac
+cached value.  For instance the following macro:
 
-@defmac AC_CACHE_SAVE
+@example
-@maindex CACHE_SAVE
+@group
-Flushes all cached values to the cache file.  Called automatically from
+AC_DEFUN([AC_SHELL_TRUE],
-@code{AC_OUTPUT}, but it can be quite useful to call
+[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
-@code{AC_CACHE_SAVE} at key points in configure.in.  Doing so
+[ac_cv_shell_true_works=no
-checkpoints the cache in case of an early configure script abort.
+true && ac_cv_shell_true_works=yes
-@end defmac
+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
@@ -5493,29 +5523,51 @@ 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
 (@pxref{Site Defaults}).
 
-If your configure script, or a macro called from configure.in, happens to
+If your configure script, or a macro called from configure.in, happens
-abort the configure process, it may be useful to checkpoint the cache a
+to abort the configure process, it may be useful to checkpoint the cache
-few times at key points.  Doing so will reduce the amount of time it
+a few times at key points using @code{AC_CACHE_SAVE}.  Doing so will
-takes to re-run the configure script with (hopefully) the error that
+reduce the amount of time it takes to re-run the configure script with
-caused the previous abort corrected.
+(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