Update to add CacheDir arg and address some review comments.

8 files changed, 83 insertions, 26 deletions

diff --git a/SCons/Environment.py b/SCons/Environment.py
index 208c840..c27f94e 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -1989,11 +1989,14 @@ class Base(SubstitutionEnvironment):
         nkw = self.subst_kw(kw)
         return SCons.Builder.Builder(**nkw)
 
-    def CacheDir(self, path):
+    def CacheDir(self, path, custom_class=None):
         if path is not None:
             path = self.subst(path)
         self._CacheDir_path = path
 
+        if custom_class:
+            self['CACHEDIR_CLASS'] = custom_class
+
         if SCons.Action.execute_actions:
             # Only initialize the CacheDir if  -n/-no_exec was NOT specified.
             # Now initialized the CacheDir and prevent a race condition which can
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 1156a02..754b59f 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -756,7 +756,7 @@ until after the Builder object is actually called.
 
 <scons_function name="CacheDir">
 <arguments>
-(cache_dir)
+(cache_dir, custom_class=<constant>None</constant>)
 </arguments>
 <summary>
 <para>
@@ -772,6 +772,10 @@ Specifying a
 of
 <constant>None</constant>
 disables derived file caching.
+A custom class which is a subclass of
+<classname>SCons.CacheDir.CacheDir<classname>
+can be passed as the optional second parameter
+allowing customization of the caching behaviors.
 </para>
 
 <para>
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index c0f1e17..eff4388 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -516,16 +516,16 @@ Program('prog',
 
     <para>
 
-    SCons built-in &f-link-CacheDir; class can be extended to support customization
+    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 or many other aspects.
+    encrypted cache files, gathering statistics and data or many other aspects.
 
     </para>
 
     <para>
 
-    To create a custom &f-link-CacheDir; class, your custom class must be a subclass of SCons.CacheDir.CacheDir class.
-    You can then pass your custom &f-link-CacheDir; class to the environment &cv-link-CACHEDIR_CLASS; before configuring the cache
+    To create a custom &f-link-CacheDir; class, your custom class must be a subclass of SCons internal <classname>SCons.CacheDir.CacheDir</classname> class.
+    You can then pass your custom &f-link-CacheDir; class to the CacheDir call or set the environment construction variable &cv-link-CACHEDIR_CLASS; 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 copy_from_cache
     method to record the total number of bytes pulled from the cache.
@@ -535,6 +535,7 @@ Program('prog',
     <scons_example name="custom_caching">
       <file name="SConstruct" printme="1">
         import SCons
+        import os
         class CustomCacheDir(SCons.CacheDir.CacheDir):
             total_retrieved = 0
 
@@ -545,8 +546,7 @@ Program('prog',
                 super().copy_from_cache(env, src, dst)
 
         env = Environment()
-        env['CACHEDIR_CLASS'] = CustomCacheDir
-        env.CacheDir('scons-cache')
+        env.CacheDir('scons-cache', CustomCacheDir)
         ...
       </file>
     </scons_example>
diff --git a/test/CacheDir/CACHEDIR_CLASS.py b/test/CacheDir/CACHEDIR_CLASS.py
new file mode 100644
index 0000000..2846b28
--- /dev/null
+++ b/test/CacheDir/CACHEDIR_CLASS.py
@@ -0,0 +1,55 @@
+#!/usr/bin/env python
+#
+# __COPYRIGHT__
+#
+# 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.
+#
+
+"""
+Test that a custom cache dir can be passed to scons.
+"""
+
+import TestSCons
+
+test = TestSCons.TestSCons()
+
+test.dir_fixture('custom_cachedir')
+
+test.write(['CustomCacheDirModule.py'], """\
+import SCons
+class CustomCacheDir(SCons.CacheDir.CacheDir):
+
+    @classmethod
+    def copy_to_cache(cls, env, src, dst):
+        print("MY_CUSTOM_CACHEDIR_CLASS")
+        super().copy_to_cache(env, src, dst)
+""")
+
+test.run()
+
+test.must_contain_all_lines(test.stdout(), ["MY_CUSTOM_CACHEDIR_CLASS"])
+
+test.pass_test()
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4:
diff --git a/test/CacheDir/CustomCacheDir.py b/test/CacheDir/CustomCacheDir.py
index ef34605..2846b28 100644
--- a/test/CacheDir/CustomCacheDir.py
+++ b/test/CacheDir/CustomCacheDir.py
@@ -30,7 +30,9 @@ import TestSCons
 
 test = TestSCons.TestSCons()
 
-test.write(['SConstruct'], """\
+test.dir_fixture('custom_cachedir')
+
+test.write(['CustomCacheDirModule.py'], """\
 import SCons
 class CustomCacheDir(SCons.CacheDir.CacheDir):
 
@@ -38,15 +40,8 @@ class CustomCacheDir(SCons.CacheDir.CacheDir):
     def copy_to_cache(cls, env, src, dst):
         print("MY_CUSTOM_CACHEDIR_CLASS")
         super().copy_to_cache(env, src, dst)
-
-env = Environment(tools=[])
-env['CACHEDIR_CLASS'] = CustomCacheDir
-env.CacheDir('cache')
-env.Command('file.out', 'file.in', Copy('$TARGET', '$SOURCE'))
 """)
 
-test.write('file.in', "file.in\n")
-
 test.run()
 
 test.must_contain_all_lines(test.stdout(), ["MY_CUSTOM_CACHEDIR_CLASS"])
diff --git a/test/CacheDir/InvalidCustomCacheDir.py b/test/CacheDir/InvalidCustomCacheDir.py
index 365ebde..604ee56 100644
--- a/test/CacheDir/InvalidCustomCacheDir.py
+++ b/test/CacheDir/InvalidCustomCacheDir.py
@@ -30,22 +30,16 @@ import TestSCons
 
 test = TestSCons.TestSCons()
 
-test.write(['SConstruct'], """\
-import SCons
+test.dir_fixture('custom_cachedir')
+
+test.write(['CustomCacheDirModule.py'], """\
 class CustomCacheDir:
     pass
-
-env = Environment(tools=[])
-env['CACHEDIR_CLASS'] = CustomCacheDir
-env.CacheDir('cache')
-env.Command('file.out', 'file.in', Copy('$TARGET', '$SOURCE'))
 """)
 
-test.write('file.in', "file.in\n")
-
 test.run(status = 2, stderr = None)
 
-test.must_contain_all_lines(test.stderr(), ["Custom CACHEDIR_CLASS <class 'SCons.Script.CustomCacheDir'> not derived from CacheDir"])
+test.must_contain_all_lines(test.stderr(), ["Custom CACHEDIR_CLASS <class 'CustomCacheDirModule.CustomCacheDir'> not derived from CacheDir"])
 
 test.pass_test()
 
diff --git a/test/CacheDir/custom_cachedir/SConstruct b/test/CacheDir/custom_cachedir/SConstruct
new file mode 100644
index 0000000..0b24564
--- /dev/null
+++ b/test/CacheDir/custom_cachedir/SConstruct
@@ -0,0 +1,5 @@
+from CustomCacheDirModule import CustomCacheDir
+
+env = Environment(tools=[])
+env.CacheDir('cache', CustomCacheDir)
+env.Command('file.out', 'file.in', Copy('$TARGET', '$SOURCE'))
\ No newline at end of file
diff --git a/test/CacheDir/custom_cachedir/file.in b/test/CacheDir/custom_cachedir/file.in
new file mode 100644
index 0000000..1912927
--- /dev/null
+++ b/test/CacheDir/custom_cachedir/file.in
@@ -0,0 +1 @@
+file.in