From 0ebe7e7f4ac5ef86a48c0d016ab210c1e0a32549 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Wed, 19 Jul 2023 14:00:52 -0600
Subject: Tweak CacheDir docs  [skip appveyor]

Formatting, some wordsmithing.

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 CHANGES.txt           |  1 +
 RELEASE.txt           |  1 +
 SCons/Environment.xml | 46 ++++++++++++++++++------------------
 doc/user/caching.xml  | 64 ++++++++++++++++++---------------------------------
 4 files changed, 49 insertions(+), 63 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index 3725fa4..1c905b4 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -124,6 +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.
+    - Documentation tweaks around CacheDir.
 
   From Jonathon Reinhart:
     - Fix another instance of `int main()` in CheckLib() causing failures
diff --git a/RELEASE.txt b/RELEASE.txt
index bffe740..663fb0f 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -106,6 +106,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
 -----------
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 2b4c4af..3b00f47 100644
--- a/SCons/Environment.xml
+++ b/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 form
 &f-link-env-CacheDir;
 limits the effect to targets built
 through the specified construction environment.
@@ -906,6 +897,18 @@ 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
 &scons;
@@ -930,15 +933,14 @@ 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>
@@ -946,10 +948,10 @@ 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>
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index f00bd69..ff5d3a7 100644
--- a/doc/user/caching.xml
+++ b/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>
+    paramter 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>
-- 
cgit v0.12


From c2fc9e2bbbceebc285b68b40fbbb88a95058fb3c Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Fri, 21 Jul 2023 16:18:54 -0600
Subject: Typo in doc/user/caching.xml  [skip appveyor]

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 doc/user/caching.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index ff5d3a7..8cca510 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -526,7 +526,7 @@ Program('prog', ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
     <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>
-    paramter when calling &f-link-CacheDir; for global reach,
+    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
-- 
cgit v0.12


From c7ef32e3d51e8dbacc7910fd89682450de0471e7 Mon Sep 17 00:00:00 2001
From: William Deegan <bill@baddogconsulting.com>
Date: Sat, 22 Jul 2023 15:45:36 -0700
Subject: minor edit

---
 SCons/Environment.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 3b00f47..9d27c72 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -883,7 +883,7 @@ disables derived file caching.
 </para>
 
 <para>
-Calling the environment method form
+Calling the environment method 
 &f-link-env-CacheDir;
 limits the effect to targets built
 through the specified construction environment.
-- 
cgit v0.12