cleanups for cache documentation

[Steven G. Johnson]

2001-03-31  Steven G. Johnson  <address@hidden>

        * doc/autoconf.texi: Clean up cache documentation: Document
        --config-cache/-C option, and recommend instead of --cache-file.
        Indented example AC_CACHE_VAL macros for clarity.  Added new
        "Cache Checkpointing" section for AC_CACHE_SAVE (and
        AC_CACHE_LOAD), so that the "Cache Files" section focuses solely
        on features visible to end-users (e.g. to better fit the cross
        references).  Various minor rewordings for clarity, felicity,
        and/or grammar.

Index: autoconf.texi
===================================================================
RCS file: /cvs/autoconf/doc/autoconf.texi,v
retrieving revision 1.437
diff -u -r1.437 autoconf.texi
--- autoconf.texi       2001/03/30 12:50:29     1.437
+++ autoconf.texi       2001/03/31 06:32:11
@@ -132,7 +132,7 @@
 
 @menu
 * Introduction::                Autoconf's purpose, strengths, and weaknesses
-* The GNU build system::
+* The GNU build system::        
 * Making configure Scripts::    How to organize and produce Autoconf scripts
 * Setup::                       Initialization and output
 * Existing Tests::              Macros that check for particular features
@@ -287,6 +287,7 @@
 
 * Cache Variable Names::        Shell variables used in caches
 * Cache Files::                 Files @code{configure} uses for caching
+* Cache Checkpointing::         Loading and saving the cache file
 
 Writing Macros
 
@@ -536,7 +537,7 @@
 
 @item
 an optional shell script normally called @file{config.cache}
-(created when using @samp{configure --cache-file=config.cache}) that
+(created when using @samp{configure --config-cache}) that
 saves the results of running many of the tests (@pxref{Cache Files});
 
 @item
@@ -6862,12 +6863,13 @@
 @cindex Cache
 
 To avoid checking for the same features repeatedly in various
address@hidden scripts (or repeated runs of one script),
address@hidden saves the results of many of its checks in a @dfn{cache
-file}.  If, when a @code{configure} script runs, it finds a cache file,
-it reads from it the results from previous runs and avoids rerunning
-those checks.  As a result, @code{configure} can run much faster than if
-it had to perform all of the checks every time.
address@hidden scripts (or in repeated runs of one script),
address@hidden can optionally save the results of many checks in a
address@hidden file} (@pxref{Cache Files}).  If a @code{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, @code{configure} can then run much faster than if it had to
+perform all of the checks every time.
 
 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
 @maindex CACHE_VAL
@@ -6898,27 +6900,28 @@
 @end defmac
 
 It is very common to find buggy macros using @code{AC_CACHE_VAL} or
address@hidden because people are tempted to call
address@hidden 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:
address@hidden, because people are tempted to call
address@hidden in the @var{commands-to-set-it}. Instead, the code that
address@hidden the call to @code{AC_CACHE_VAL} should call
address@hidden, by examining the value of the cache variable.  For
+instance, the following macro is broken:
 
 @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
-])])
+                [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])
+])
 @end group
 @end example
 
 @noindent
-is broken: if the cache is enabled, the second time this macro is run,
+This fails if the cache is enabled: the second time this macro is run,
 @code{TRUE_WORKS} @emph{will not be defined}.  The proper implementation
 is:
 
@@ -6926,12 +6929,12 @@
 @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
+                [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
 ])
 @end group
 @end example
@@ -6945,6 +6948,7 @@
 @menu
 * Cache Variable Names::        Shell variables used in caches
 * Cache Files::                 Files @code{configure} uses for caching
+* Cache Checkpointing::         Loading and saving the cache file
 @end menu
 
 @node Cache Variable Names, Cache Files, Caching Results, Caching Results
@@ -6992,7 +6996,7 @@
 Usually, their values will be boolean (@samp{yes} or @samp{no}) or the
 names of files or functions; so this is not an important restriction.
 
address@hidden Cache Files,  , Cache Variable Names, Caching Results
address@hidden Cache Files, Cache Checkpointing, Cache Variable Names, Caching 
Results
 @subsection Cache Files
 
 A cache file is a shell script that caches the results of configure
@@ -7000,18 +7004,18 @@
 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
address@hidden/dev/null}), so as to forestall problems caused by
-accidental use of stale cache files.
-
-To enable caching, @code{configure} accepts
address@hidden@var{file}} where @var{file} is the name of the
-cache file to use, traditionally @file{config.cache}.  The cache file is
-created if it does not exist already.  When @code{configure} calls
address@hidden scripts in subdirectories, it uses the
address@hidden argument so that they share the same cache.
address@hidden, for information on configuring subdirectories
-with the @code{AC_CONFIG_SUBDIRS} macro.
+By default, @code{configure} uses no cache file (technically, it uses
address@hidden/dev/null}), to avoid problems caused by accidental
+use of stale cache files.
+
+To enable caching, @code{configure} accepts @option{--config-cache} (or
address@hidden) to cache results in the file @file{config.cache}.
+Alternatively, @address@hidden specifies that
address@hidden be the cache file.  The cache file is created if it does not
+exist already.  When @code{configure} calls @code{configure} scripts in
+subdirectories, it uses the @option{--cache-file} argument so that they
+share the same cache.  @xref{Subdirectories}, for information on
+configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
 
 @file{config.status} only pays attention to the cache file if it is
 given the @option{--recheck} option, which makes it rerun
@@ -7022,14 +7026,17 @@
 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 (@pxref{Manual Configuration}).
+
+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
address@hidden script.  (Running @code{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.
 
-The cache file on a particular system will gradually accumulate whenever
-someone runs a @code{configure} script; it will be initially
-nonexistent.  Running @code{configure} merges the new cache results with
-the existing cache file.  The site initialization script can specify a
-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}).
address@hidden Cache Checkpointing,  , Cache Files, Caching Results
address@hidden Cache Checkpointing
 
 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
@@ -8680,10 +8687,11 @@
 code are really appropriate to be in them.  Because @code{configure}
 reads any cache file after it has read any site files, a site file can
 define a default cache file to be shared between all Autoconf-generated
address@hidden scripts run on that system.  If you set a default cache
-file in a site file, it is a good idea to also set the output variable
address@hidden in that site file, because the cache file is only valid for a
-particular compiler, but many systems have several available.
address@hidden scripts run on that system (@pxref{Cache Files}).  If
+you set a default cache file in a site file, it is a good idea to also
+set the output variable @code{CC} in that site file, because the cache
+file is only valid for a particular compiler, but many systems have
+several available.
 
 You can examine or override the value set by a command line option to
 @code{configure} in a site file; options set shell variables that have