Merge branch 'master' into doc/framework-upd

CHANGES.txt

@@ -124,7 +124,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER
  - Cleaned up dblite module (checker warnings, etc.).
  - Some cleanup in the FortranCommon tool.
  - Changed the message about scons -H to clarify it shows built-in options.
-
+ - Improve CacheDir() Documentation.
  - Release-building setup tweaked. (most of) the targets listed in
  SCons' own "scons --help" now work again.
  - Fix platform unit test on Windows for Py 3.12+. Fixes #4376.

RELEASE.txt

@@ -109,6 +109,7 @@ DOCUMENTATION
  the results would be incorrect (does not apply to positional argument
  usage, which had no problem).
 - Changed the message about scons -H to clarify it shows built-in options only.
+- Cachedir description updated.
 
 DEVELOPMENT
 -----------

SCons/Environment.xml

@@ -251,8 +251,8 @@ that are part of this construction environment.
  <summary>
  <para>
 The class type that SCons should use when instantiating a
-new &f-link-CacheDir; for the given environment. It must be
-a subclass of the SCons.CacheDir.CacheDir class.
+new &f-link-CacheDir; in this &consenv;. Must be
+a subclass of the <classname>SCons.CacheDir.CacheDir</classname> class.
  </para>
  </summary>
 </cvar>
@@ -883,16 +883,7 @@ disables derived file caching.
 </para>
 
 <para>
-When specifying a
-<parameter>custom_class</parameter> which should be a class type which is a subclass of
-<classname>SCons.CacheDir.CacheDir</classname>, SCons will
-internally invoke this class to use for performing caching operations.
-This argument is optional and if left to default <constant>None</constant>, will use the
-default <classname>SCons.CacheDir.CacheDir</classname> class.
-</para>
-
-<para>
-Calling the environment method
+Calling the environment method 
 &f-link-env-CacheDir;
 limits the effect to targets built
 through the specified construction environment.
@@ -905,6 +896,18 @@ that do not set up environment-specific
 caching by calling &f-env-CacheDir;.
 </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.
+</para>
+
 <para>
 When derived-file caching
 is being used and
@@ -930,26 +933,25 @@ identified by its &buildsig;, for future use.
 The
 <computeroutput>Retrieved `file' from cache</computeroutput>
 messages are useful for human consumption,
-but less so when comparing log files between
+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;
-will print the action that would
-have been used to build the file without
-considering cache retrieval.
+With this option, &scons; changes printing
+to always show the action that would
+have been used to build the file without caching.
 </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
+command line option;
+cache updating may be disabled, leaving cache
 fetching enabled, by giving the
-<option>--cache-readonly</option>.
+<option>--cache-readonly</option> option.
 </para>
 
 <para>
@@ -959,7 +961,7 @@ option is used,
 &scons;
 will place a copy of
 <emphasis>all</emphasis>
-derived files in the cache,
+derived files into the cache,
 even if they already existed
 and were not built by this invocation.
 This is useful to populate a cache
@@ -984,7 +986,7 @@ predict or prohibitively large.
 <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, etc. if needed.
+to arrange for cache pruning, expiry, access control, etc. if needed.
 </para>
 
 </summary>

doc/user/caching.xml

@@ -1,4 +1,10 @@
 <?xml version='1.0'?>
+<!--
+SPDX-License-Identifier: MIT
+
+Copyright The SCons Foundation
+-->
+
 <!DOCTYPE sconsdoc [
  <!ENTITY % scons SYSTEM "../scons.mod">
  %scons;
@@ -20,33 +26,6 @@
  xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
 <title>Caching Built Files</title>
 
-<!--
-
- MIT License
-
- Copyright The SCons Foundation
-
- Permission is hereby granted, free of charge, to any person obtaining
- a copy of this software and associated documentation files (the
- "Software"), to deal in the Software without restriction, including
- without limitation the rights to use, copy, modify, merge, publish,
- distribute, sublicense, and/or sell copies of the Software, and to
- permit persons to whom the Software is furnished to do so, subject to
- the following conditions:
-
- The above copyright notice and this permission notice shall be included
- in all copies or substantial portions of the Software.
-
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
- KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
- WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
--->
-
  <para>
 
  On multi-developer software projects,
@@ -534,22 +513,25 @@ Program('prog', ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
 
  <para>
 
- &SCons;' internal <classname>CacheDir</classname> class can be extended to support customization
- around the details of caching behaviors, for example using compressed cache files,
- encrypted cache files, gathering statistics and data, or many other aspects.
+ You can customize the behavior of derived-file caching to
+ add your own features, for example to support compressed and/or
+ encrypted cache files, modify cache file permissions to better
+ support shared caches, gather additional statistics and data, etc.
 
  </para>
 
  <para>
 
- To create your own custom cache class,
- your custom class must be a subclass
- of the <classname>SCons.CacheDir.CacheDir</classname> class.
- You can then pass your custom class to the &f-link-CacheDir;
- method or set the &consvar;
- &cv-link-CACHEDIR_CLASS; to the class before configuring the cache
- in that environment.
- SCons will internally invoke and use your custom class when performing
+ To define custom cache behavior, subclass the
+ <classname>SCons.CacheDir.CacheDir</classname> class,
+ specializing those methods you want to change.
+ You can pass this custom class as the <parameter>custom_class</parameter>
+ parameter when calling &f-link-CacheDir; for global reach,
+ or when calling &f-link-env-CacheDir; for a specific environment.
+ You can also set the &consvar;
+ &cv-link-CACHEDIR_CLASS; to the custom class - this needs to happen
+ before configuring the cache in that environment.
+ &SCons; will internally invoke and use your custom class when performing
  cache operations.
  The below example shows a simple use case of overriding the
  <function>copy_from_cache</function>
@@ -559,8 +541,8 @@ Program('prog', ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
 
  <scons_example name="custom_caching">
  <file name="SConstruct" printme="1">
-import SCons
 import os
+import SCons.CacheDir
 
 class CustomCacheDir(SCons.CacheDir.CacheDir):
  total_retrieved = 0
@@ -569,10 +551,10 @@ class CustomCacheDir(SCons.CacheDir.CacheDir):
  def copy_from_cache(cls, env, src, dst):
  # record total bytes pulled from cache
  cls.total_retrieved += os.stat(src).st_size
- super().copy_from_cache(env, src, dst)
+ return super().copy_from_cache(env, src, dst)
 
 env = Environment()
-env.CacheDir('scons-cache', CustomCacheDir)
+env.CacheDir('scons-cache', custom_class=CustomCacheDir)
 # ...
  </file>
  </scons_example>