From 0921af6416e6941ddeb36bd6d78062da7b0f10e7 Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Tue, 13 Jun 2000 09:31:55 +0000 Subject: [PATCH] * 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 | 7 +++ configure | 6 +++ doc/autoconf.texi | 112 +++++++++++++++++++++++++++++++++------------- 3 files changed, 95 insertions(+), 30 deletions(-) diff --git a/ChangeLog b/ChangeLog index ece03f75..d2667acc 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2000-06-13 Akim Demaille + + * 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 * acgeneral.m4 (AC_CHECK_TOOL): Even if VALUE-IF-NOT-FOUND is not diff --git a/configure b/configure index cd16a698..83c646ff 100755 --- a/configure +++ b/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 <>$CONFIG_STATUS <<\EOF ac_cs_usage="\ \`$me' instantiates files from templates according to the diff --git a/doc/autoconf.texi b/doc/autoconf.texi index 9741aec5..9b8e8044 100644 --- a/doc/autoconf.texi +++ b/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}. -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. +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}) +@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 -@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 +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: -@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 +@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 @@ -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 -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