Tweak documentation for CacheDir [skip appveyor]

Tighten up descriptions for the function and for the related
command-line argument flags.

Signed-off-by: Mats Wichmann <mats@linux.com>

Author: mwichmann

CHANGES.txt

@@ -81,18 +81,16 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       on a one-time uuid to make a path to the file.
     - Clarify VariantDir behavior when switching to not duplicate sources
       and tweak wording a bit.
-<<<<<<< feature/py315
     - Test suite: add support for Python 3.15 in the Action unit tests.
-=======
     - Update documentation of the three file-finding functions in the API
       (FindFile, FindInstalledFiles, FindSourceFiles) as well as FindPathDirs.
       Also add a test for FindFile to be sure it locates non-existing
       derived files as advertised.
->>>>>>> master
     - zip tool now uses zipfile module's "from_file" method to populate
       ZipInfo records, rather than doing manually.
     - Update documentation for linking-related construction variables.
       Add a few more live links.
+    - Update documentation for CacheDir and related option flags
 
 
 RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700

RELEASE.txt

@@ -124,9 +124,12 @@ DOCUMENTATION
 
 - Update documentation of the three file-finding functions in the API
   (FindFile, FindInstalledFiles, FindSourceFiles) as well as FindPathDirs.
+
 - Update documentation for linking-related construction variables.
   Add a few more live links.
 
+- Update documentation for CacheDir and related option flags
+
 DEVELOPMENT
 -----------
 

SCons/Environment.xml

@@ -917,121 +917,83 @@ Direct
 &scons;
 to maintain a derived-file cache in
 <parameter>cache_dir</parameter>.
-The derived files in the cache will be shared
-among all the builds specifying the same
+Cached files are shared across builds that specify the same
 <parameter>cache_dir</parameter>.
-Specifying a
-<parameter>cache_dir</parameter>
-of
-<constant>None</constant>
-disables derived file caching.
+Setting <parameter>cache_dir</parameter>
+to <constant>None</constant> disables caching.
 </para>
 
 <para>
-Calling the environment method
+The environment method
 &f-link-env-CacheDir;
-limits the effect to targets built
-through the specified &consenv;.
-Calling the global function
-&f-link-CacheDir;
-sets a global default
-that will be used by all targets built
-through &consenvs;
-that do not set up environment-specific
-caching by calling &f-env-CacheDir;.
+applies caching only to targets built
+through that specific &consenv;.
+The global function &f-link-CacheDir;
+sets a default that applies
+to all targets unless overridden by an
+environment-specific call.
 </para>
 
 <para>
-Caching behavior can be configured by passing a specialized cache
-class as the optional <parameter>custom_class</parameter> parameter.
-This class must be a subclass of
-<classname>SCons.CacheDir.CacheDir</classname>.
-&SCons; will internally invoke the custom class for performing
-caching operations.
-If the parameter is omitted or set to
-<constant>None</constant>, &SCons; will use the default
-<classname>SCons.CacheDir.CacheDir</classname> class.
+Caching behavior can be customized by passing a subclass of
+<classname>SCons.CacheDir.CacheDir</classname>
+as the optional <parameter>custom_class</parameter> parameter.
+If omitted or set to <constant>None</constant>,
+&SCons; uses the default class.
 </para>
 
 <para>
-When derived-file caching
-is being used and
-&scons;
-finds a derived file that needs to be rebuilt,
-it will first look in the cache to see if a
-file with matching &buildsig; exists
-(indicating the input file(s) and build action(s)
-were identical to those for the current target),
-and if so, will retrieve the file from the cache.
-&scons;
-will report
-<computeroutput>Retrieved `file' from cache</computeroutput>
-instead of the normal build message.
-If the derived file is not present in the cache,
-&scons;
-will build it and
-then place a copy of the built file in the cache,
-identified by its &buildsig;, for future use.
+When caching is enabled and &scons;
+needs to rebuild a derived file,
+it first checks the cache for a matching &buildsig;
+(indicating identical inputs and build actions).
+If found, the file is retrieved from the cache.
+Otherwise, &scons; builds the file and
+stores a copy the cache under its &buildsig;.
 </para>
 
 <para>
-The
+By default, &scons; reports
 <computeroutput>Retrieved `file' from cache</computeroutput>
-messages are useful for human consumption,
-but less useful when comparing log files between
-&scons; runs which will show differences that are
-noisy and not actually significant.
-To disable,
-use the <option>--cache-show</option> option.
-With this option, &scons; changes printing
-to always show the action that would
-have been used to build the file without caching.
+on cache hits.
+Use the
+<link linkend="opt-cache-show"><option>--cache-show</option></link>
+option to hide that the cache was involved
+and display the normal build string instead,
+for consistent log output.
 </para>
 
 <para>
-Derived-file caching
-may be disabled for any invocation
-of &scons; by giving the
-<option>--cache-disable</option>
-command line option;
-cache updating may be disabled, leaving cache
-fetching enabled, by giving the
-<option>--cache-readonly</option> option.
+Disable caching for a specific invocation with the
+<link linkend="opt-cache-disable"><option>--cache-disable</option></link>
+option.
+To allow retreival but prevent updates, use
+<link linkend="opt-cache-readonly"><option>--cache-readonly</option></link>.
 </para>
 
 <para>
-If the
-<option>--cache-force</option>
-option is used,
-&scons;
-will place a copy of
-<emphasis>all</emphasis>
-derived files into the cache,
-even if they already existed
-and were not built by this invocation.
-This is useful to populate a cache
-the first time a
-<parameter>cache_dir</parameter>
-is used for a build,
-or to bring a cache up to date after
-a build with cache updating disabled
-(<option>--cache-disable</option>
-or <option>--cache-readonly</option>)
-has been done.
+The
+<link linkend="opt-cache-force"><option>--cache-force</option></link>
+option copies <emphasis>all</emphasis> derived files into the cache,
+even pre-existing ones.
+This helps populate a new cache or update it
+after building with cache updating disabled
+(<link linkend="opt-cache-disable"><option>--cache-disable</option></link>
+or <link linkend="opt-cache-readonly"><option>--cache-readonly</option></link>).
 </para>
 
 <para>
-The
+Use
 &f-link-NoCache;
-method can be used to disable caching of specific files.  This can be
-useful if inputs and/or outputs of some tool are impossible to
-predict or prohibitively large.
+to exclude specific files from caching,
+such as those with unpredictable inputs or outputs,
+or excessively large output files.
 </para>
 
 <para>
-Note that (at this time) &SCons; provides no facilities
-for managing the derived-file cache. It is up to the developer
-to arrange for cache pruning, expiry, access control, etc. if needed.
+&SCons; does not provide built-in tools for cache management.
+You will need to handle pruning, expiration,
+access control, and other maintenance tasks manually.
 </para>
 
 </summary>

doc/man/scons.xml

@@ -715,10 +715,11 @@ If
 <replaceable>file</replaceable>
 is a hyphen
 (<literal>-</literal>),
-the debug information is printed to the standard output.
-The printed messages describe what signature-file names
-are being looked for in, retrieved from, or written to the
-derived-file cache specified by &f-link-CacheDir;.</para>
+the debug information is printed to standard output.
+The messages describe cache operations,
+such as which &buildsig; is being sarched for,
+retrieved, or stored in the cache specified by &f-link-CacheDir;.
+</para>
   </listitem>
   </varlistentry>
 
@@ -731,9 +732,9 @@ derived-file cache specified by &f-link-CacheDir;.</para>
 <para>Disable derived-file caching.
 &scons;
 will neither retrieve files from the cache
-nor copy files to the cache.  This option can
-be used to temporarily disable the cache without
-modifying the build scripts.
+nor copy files to the cache.
+This option allows temporarily disabling the cache without
+modifying build scripts.
 </para>
   </listitem>
   </varlistentry>
@@ -745,23 +746,22 @@ modifying the build scripts.
   </term>
   <listitem>
 <para>When using &f-link-CacheDir;,
-populate a derived-file cache by copying any already-existing,
-up-to-date derived files to the cache,
-in addition to files built by this invocation.
-This is useful to populate a new cache with
-all the current derived files,
-or to add to the cache any derived files
-recently built with caching disabled via the
-<option>--cache-disable</option>
-option.</para>
+populate a derived-file cache by copying any existing,
+up-to-date derived files to it,
+in addition to files built during this invocation.
+This is useful for initializing a new cache with
+current derived files or
+adding files that were recently built with caching disabled
+(via the <option>--cache-disable</option> option.
+</para>
   </listitem>
   </varlistentry>
 
   <varlistentry id="opt-cache-readonly">
   <term><option>--cache-readonly</option></term>
   <listitem>
 <para>Use the derived-file cache, if enabled, to retrieve files,
-but do not not update the cache with any files actually
+but do not not update the cache with any files
 built during this invocation.
 </para>
   </listitem>
@@ -770,15 +770,14 @@ built during this invocation.
   <varlistentry id="opt-cache-show">
   <term><option>--cache-show</option></term>
   <listitem>
-<para>When using a derived-file cache, show the command
+<para>When using a derived-file cache, display the command
 that would have been executed to build the file
 (or the corresponding <literal>*COMSTR</literal>
-contents if set)
-even if the file is retrieved from cache.
-Without this option, &scons; shows a cache retrieval message
-if the file is fetched from cache.
-This allows producing consistent output for build logs,
-regardless of whether a target
+contents if set),
+even if the file is retrieved from the cache.
+Without this option, &scons; shows a cache retrieval message.
+This ensures consistent output in build logs,
+regardless of whether the
 file was rebuilt or retrieved from the cache.</para>
   </listitem>
   </varlistentry>