Added custom cachedir class tests and docs

4 files changed, 168 insertions, 0 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 335ab13..1156a02 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -244,6 +244,16 @@ that are part of this construction environment.
 </summary>
 </cvar>
 
+<cvar name="CACHEDIR_CLASS">
+    <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.
+        </para>
+    </summary>
+</cvar>
+
 <!-- Functions /  Construction environment methods -->
 
 <scons_function name="Action">
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index 790aa93..c0f1e17 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -511,6 +511,48 @@ Program('prog',
 
   </section>
 
+  <section>
+    <title>Using a Custom CacheDir class</title>
+
+    <para>
+
+    SCons built-in &f-link-CacheDir; 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.
+
+    </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
+    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.
+
+    </para>
+
+    <scons_example name="custom_caching">
+      <file name="SConstruct" printme="1">
+        import SCons
+        class CustomCacheDir(SCons.CacheDir.CacheDir):
+            total_retrieved = 0
+
+            @classmethod
+            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)
+
+        env = Environment()
+        env['CACHEDIR_CLASS'] = CustomCacheDir
+        env.CacheDir('scons-cache')
+        ...
+      </file>
+    </scons_example>
+
+  </section>
+
   <!--
 
   <section>
diff --git a/test/CacheDir/CustomCacheDir.py b/test/CacheDir/CustomCacheDir.py
new file mode 100644
index 0000000..ef34605
--- /dev/null
+++ b/test/CacheDir/CustomCacheDir.py
@@ -0,0 +1,60 @@
+#!/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.write(['SConstruct'], """\
+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)
+
+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"])
+
+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/InvalidCustomCacheDir.py b/test/CacheDir/InvalidCustomCacheDir.py
new file mode 100644
index 0000000..365ebde
--- /dev/null
+++ b/test/CacheDir/InvalidCustomCacheDir.py
@@ -0,0 +1,56 @@
+#!/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.write(['SConstruct'], """\
+import SCons
+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.pass_test()
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4: