diff --git a/CHANGES.txt b/CHANGES.txt
index f56910c97..630754bc9 100644
--- a/CHANGES.txt
+++ b/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
diff --git a/RELEASE.txt b/RELEASE.txt
index 36a06067a..f5d612d2f 100644
--- a/RELEASE.txt
+++ b/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
-----------
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 3ac1f5438..25eaafdf6 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -917,121 +917,83 @@ Direct
&scons;
to maintain a derived-file cache in
cache_dir.
-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
cache_dir.
-Specifying a
-cache_dir
-of
-None
-disables derived file caching.
+Setting cache_dir
+to None disables caching.
-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.
-Caching behavior can be configured by passing a specialized cache
-class as the optional custom_class parameter.
-This class must be a subclass of
-SCons.CacheDir.CacheDir.
-&SCons; will internally invoke the custom class for performing
-caching operations.
-If the parameter is omitted or set to
-None, &SCons; will use the default
-SCons.CacheDir.CacheDir class.
+Caching behavior can be customized by passing a subclass of
+SCons.CacheDir.CacheDir
+as the optional custom_class parameter.
+If omitted or set to None,
+&SCons; uses the default class.
-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
-Retrieved `file' from cache
-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;.
-The
+By default, &scons; reports
Retrieved `file' from cache
-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.
-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
+
+option to hide that the cache was involved
+and display the normal build string instead,
+for consistent log output.
-Derived-file caching
-may be disabled for any invocation
-of &scons; by giving the
-
-command line option;
-cache updating may be disabled, leaving cache
-fetching enabled, by giving the
- option.
+Disable caching for a specific invocation with the
+
+option.
+To allow retreival but prevent updates, use
+.
-If the
-
-option is used,
-&scons;
-will place a copy of
-all
-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
-cache_dir
-is used for a build,
-or to bring a cache up to date after
-a build with cache updating disabled
-(
-or )
-has been done.
+The
+
+option copies all derived files into the cache,
+even pre-existing ones.
+This helps populate a new cache or update it
+after building with cache updating disabled
+(
+or ).
-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.
-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.
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index fa18060b8..9a1e72f51 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -715,10 +715,11 @@ If
file
is a hyphen
(-),
-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;.
+the debug information is printed to standard output.
+The messages describe cache operations,
+such as which &buildsig; is being searched for,
+retrieved, or stored in the cache specified by &f-link-CacheDir;.
+
@@ -731,9 +732,9 @@ derived-file cache specified by &f-link-CacheDir;.
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.
@@ -745,15 +746,14 @@ modifying the build scripts.
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.
+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.
+
@@ -761,7 +761,7 @@ option.
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.
@@ -770,15 +770,14 @@ built during this invocation.
-When using a derived-file cache, show the command
+When using a derived-file cache, display the command
that would have been executed to build the file
(or the corresponding *COMSTR
-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.