[PR #3836] add example of SConsign(dbm_modue=...) (skip appveyor)

It wasn't clear that you need to pass the module name to
SConsignFile, the expectation might be to pass a string,
so clarified and an example added to show it.

Some of the wording was simplified a bit.

Added a testcase of explicity passing dbm_module=SCons.dblite,
as this should work.

Signed-off-by: Mats Wichmann <mats@linux.com>

2 files changed, 119 insertions, 25 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 93c9278..d594bdf 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -2744,58 +2744,61 @@ SConscript('bar/SConscript')	# will chdir to bar
 </arguments>
 <summary>
 <para>
-Store the &SCons; file signature database in
-the file <parameter>name</parameter>,
-using <parameter>dbm_module</parameter>
-as the file format.
+Specify where to store the &SCons; file signature database,
+and which database format to use.
 This may be useful to specify alternate
 database files and/or file locations for different types of builds.
 </para>
 <para>
-If the optional first argument (or
-<parameter>name</parameter> keyword argument)
-is not an absolute path name,
-the file is placed relative to the directory containing the
+The optional <parameter>name</parameter> argument
+is the base name of the database file(s).
+If not an absolute path name,
+these are placed relative to the directory containing the
 top-level &SConstruct; file.
 The default is
 <filename>.sconsign</filename>.
-The actual file name stored on disk
+The actual database file(s) stored on disk
 may have an appropriate suffix appended
 by the chosen
 <parameter>dbm_module</parameter>
 </para>
 <para>
-The optional second argument (or
-<parameter>dbm_module</parameter>
-keyword argument) can be used to specify
-which Python database module to use
+The optional <parameter>dbm_module</parameter>
+argument specifies which
+Python database module to use
 for reading/writing the file.
-The default is to use a custom
-<filename>SCons.dblite</filename>
+The module must be imported first;
+then the imported module name
+is passed as the argument.
+The default is a custom
+<systemitem>SCons.dblite</systemitem>
 module that uses pickled
 Python data structures,
-and which works on all Python versions.
+which works on all Python versions.
+See documentation of the Python
+<systemitem>dbm</systemitem> module
+for other available types.
 </para>
 <para>
-If called with no arguments, 
-the filename will default to
+If called with no arguments,
+the database will default to
 <filename>.sconsign.dblite</filename>
-in the top directory of the project. 
-This also the default if
+in the top directory of the project,
+which is also the default if
 if &f-SConsignFile; is not called.
 </para>
 <para>
 The setting is global, so the only difference
 between the global function and the environment method form
-is variable expansion. There should only be
-one call to this function/method in a given build setup.
+is variable expansion on <parameter>name</parameter>.
+There should only be one active call to this
+function/method in a given build setup.
 </para>
 <para>
-If 
+If
 <parameter>name</parameter>
 is set to
 <constant>None</constant>,
-then
 &scons;
 will store file signatures
 in a separate
@@ -2805,7 +2808,7 @@ not in a single combined database file.
 This is a backwards-compatibility meaure to support
 what was the default behavior
 prior to &SCons; 0.97 (i.e. before 2008).
-Use of this mode is discouraged and may be 
+Use of this mode is discouraged and may be
 deprecated in a future &SCons; release.
 </para>
 
@@ -2830,6 +2833,10 @@ SConsignFile("/home/me/SCons/signatures")
 # Stores signatures in a separate .sconsign file
 # in each directory.
 SConsignFile(None)
+
+# Stores signatures in a GNU dbm format .sconsign file
+import dbm.gnu
+SConsignFile(dbm_module=dbm.gnu)
 </example_commands>
 </summary>
 </scons_function>
diff --git a/test/SConsignFile/explicit-dbm-module.py b/test/SConsignFile/explicit-dbm-module.py
new file mode 100644
index 0000000..09b75ae
--- /dev/null
+++ b/test/SConsignFile/explicit-dbm-module.py
@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+#
+# 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.
+
+"""Verify SConsignFile() when used with explicit SCons.dblite."""
+
+import os.path
+
+import TestSCons
+
+_python_ = TestSCons._python_
+
+test = TestSCons.TestSCons()
+
+import SCons.dblite
+use_db = 'SCons.dblite'
+
+test.subdir('subdir')
+
+test.write('build.py', r"""
+import sys
+with open(sys.argv[1], 'wb') as ofp, open(sys.argv[2], 'rb') as ifp:
+    ofp.write(ifp.read())
+sys.exit(0)
+""")
+
+test.write('SConstruct', """
+import %(use_db)s
+SConsignFile(dbm_module=%(use_db)s)
+B = Builder(action=r'%(_python_)s build.py $TARGETS $SOURCES')
+DefaultEnvironment(tools=[])
+env = Environment(BUILDERS={'B': B}, tools=[])
+env.B(target='f1.out', source='f1.in')
+env.B(target='f2.out', source='f2.in')
+env.B(target='subdir/f3.out', source='subdir/f3.in')
+env.B(target='subdir/f4.out', source='subdir/f4.in')
+""" % locals())
+
+test.write('f1.in', "f1.in\n")
+test.write('f2.in', "f2.in\n")
+test.write(['subdir', 'f3.in'], "subdir/f3.in\n")
+test.write(['subdir', 'f4.in'], "subdir/f4.in\n")
+
+test.run()
+
+test.must_exist(test.workpath('.sconsign.dblite'))
+test.must_not_exist(test.workpath('.sconsign'))
+test.must_not_exist(test.workpath('subdir', '.sconsign'))
+
+test.must_match('f1.out', "f1.in\n")
+test.must_match('f2.out', "f2.in\n")
+test.must_match(['subdir', 'f3.out'], "subdir/f3.in\n")
+test.must_match(['subdir', 'f4.out'], "subdir/f4.in\n")
+
+test.up_to_date(arguments='.')
+
+test.must_exist(test.workpath('.sconsign.dblite'))
+test.must_not_exist(test.workpath('.sconsign'))
+test.must_not_exist(test.workpath('subdir', '.sconsign'))
+
+test.pass_test()
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4: