Anonymous avatar Anonymous committed 99b456b

Merged revisions 2454-2525 via svnmerge from
http://scons.tigris.org/svn/scons/branches/core

........
r2455 | stevenknight | 2007-09-20 01:27:23 -0500 (Thu, 20 Sep 2007) | 2 lines

Use ${TARGET.base} to make sure $TARGET attributes stay fixed.
........
r2456 | stevenknight | 2007-09-25 11:52:30 -0500 (Tue, 25 Sep 2007) | 5 lines

Issue 1734: Avoid having content signature calculation of Alias Nodes
consume excessive amounts of memory by having an Alias' "contents" be a
concatenation of the children's signatures, not the children's contents.
(Ken Deeter)
........
r2457 | stevenknight | 2007-09-26 12:18:49 -0500 (Wed, 26 Sep 2007) | 2 lines

Add an Options.UnknownOptions() method.
........
r2458 | stevenknight | 2007-09-26 16:26:05 -0500 (Wed, 26 Sep 2007) | 2 lines

Add a compatibility fnmatch.filter() function.
........
r2459 | stevenknight | 2007-09-27 18:26:03 -0500 (Thu, 27 Sep 2007) | 3 lines

Add a new Glob() function that matches in-memory Nodes as well as on-disk
files (including matching repository and source directories).
........
r2460 | stevenknight | 2007-09-28 15:01:37 -0500 (Fri, 28 Sep 2007) | 5 lines

Issue 1020: fix use of Clean() for files created by "side effect"
in BuildDir() by removing the file by absolute path, not by what str()
returns. (It will think that the file is a source file and return a
path to the source directory.)
........
r2461 | stevenknight | 2007-09-29 05:39:09 -0500 (Sat, 29 Sep 2007) | 2 lines

Update to TestCmd 0.28 modules.
........
r2462 | stevenknight | 2007-09-29 05:49:29 -0500 (Sat, 29 Sep 2007) | 3 lines

The RPM packaging can no longer take a "target" argument and produces
an appropriate error message. Update the test accordingly.
........
r2463 | pscholl | 2007-09-30 08:57:01 -0500 (Sun, 30 Sep 2007) | 3 lines

fix documentation issues (issue 1736 on the bugtracker)
........
r2464 | pscholl | 2007-09-30 09:39:49 -0500 (Sun, 30 Sep 2007) | 3 lines

fix target set up if multiple package builders are specified at once.
........
r2465 | stevenknight | 2007-10-01 13:00:44 -0500 (Mon, 01 Oct 2007) | 3 lines

Update to TestCmd 0.29, with new methods for searching for a list
of lines in output.
........
r2466 | stevenknight | 2007-10-01 13:58:41 -0500 (Mon, 01 Oct 2007) | 4 lines

Issue 1737: Fix use of Configure() contexts with the -c (clean) and -h
(help) options by supporting the ability to *configure* whether or no
configure context tests are executed during those modes.
........
r2467 | stevenknight | 2007-10-01 16:58:21 -0500 (Mon, 01 Oct 2007) | 2 lines

Update to TestCmd 0.30, with a new TestCmd.rmdir() method.
........
r2468 | stevenknight | 2007-10-01 17:05:44 -0500 (Mon, 01 Oct 2007) | 4 lines

Issue 1586: Capture a test script for "ghost" entries in .sconsign files.
Test cases by Morten Elo Peterson and Jason Orendorff, packaged by
Gary Oberbrunner.
........
r2469 | stevenknight | 2007-10-04 11:21:12 -0500 (Thu, 04 Oct 2007) | 4 lines

When cloning a construction environment, have the clone record the
re-binding of the methods that were added to the original construction
environment, so that further clones have their methods re-bound as well.
........
r2470 | stevenknight | 2007-10-05 13:02:34 -0500 (Fri, 05 Oct 2007) | 3 lines

Refactor the Glob() code for efficiency and readability. (Greg Noel)
Refactor Glob() unit tests for platform-independence.
........
r2471 | stevenknight | 2007-10-09 10:49:15 -0500 (Tue, 09 Oct 2007) | 2 lines

Back out Glob() refactoring to avoid Repository breakage.
........
r2472 | stevenknight | 2007-10-09 12:16:33 -0500 (Tue, 09 Oct 2007) | 3 lines

Fix ToolInitializer-related infinite recursion when the BUILDERS dict
and the environment attributes can get out of sync.
........
r2473 | stevenknight | 2007-10-10 14:39:19 -0500 (Wed, 10 Oct 2007) | 4 lines

Fix a race condition in the -j sub-test by using marker directories to
make sure (?) that the two build scripts are actually executed in parallel
(regardless of system load).
........
r2474 | stevenknight | 2007-10-11 12:32:07 -0500 (Thu, 11 Oct 2007) | 4 lines

Re-fix globbing on case-insensitive systems like Windows. Slight
efficiency improvements as well (avoiding unnecessary calls to
fnmatch.filter()).
........
r2475 | stevenknight | 2007-10-11 15:04:42 -0500 (Thu, 11 Oct 2007) | 3 lines

Refactor the Node lookup logic to fix handling Windows drive letters
after an initial '#'.
........
r2476 | stevenknight | 2007-10-12 00:01:31 -0500 (Fri, 12 Oct 2007) | 2 lines

Fix nested scope issues (for the benefit of older Python versions).
........
r2477 | stevenknight | 2007-10-12 11:36:21 -0500 (Fri, 12 Oct 2007) | 2 lines

Issue 1743: Document '#' interpretation, with examples.
........
r2478 | stevenknight | 2007-10-12 12:17:50 -0500 (Fri, 12 Oct 2007) | 3 lines

Fix the ability of our default ActionFactory function to handle Nodes
as input.
........
r2479 | stevenknight | 2007-10-12 13:53:37 -0500 (Fri, 12 Oct 2007) | 4 lines

Enhance Options() file execution to add the file's directory to sys.path
(and remove it afterwards) and to add a __name__ variable that can be
used for introspecting on the file's location.
........
r2480 | stevenknight | 2007-10-14 17:57:09 -0500 (Sun, 14 Oct 2007) | 4 lines

Remove unnecessary os.path.normpath() calls when looking up directories
or files by checking for whether we can just tack on a single entry name
to the already-normalized lookup path of the directory Node.
........
r2481 | stevenknight | 2007-10-17 01:08:47 -0500 (Wed, 17 Oct 2007) | 2 lines

Add a GetBuildFailures() function.
........
r2482 | stevenknight | 2007-10-17 09:56:18 -0500 (Wed, 17 Oct 2007) | 2 lines

Fix the GetBuildFailures() example in the man page.
........
r2483 | stevenknight | 2007-10-17 10:54:21 -0500 (Wed, 17 Oct 2007) | 3 lines

Use sys.exitfunc if there's no atexit module (Python 1.5.2).
Sort the failure list for deterministic build output under system load.
........
r2484 | stevenknight | 2007-10-20 12:33:07 -0500 (Sat, 20 Oct 2007) | 2 lines

Use more efficient Decider() defaults instead of {Target,Source}Signatures().
........
r2485 | stevenknight | 2007-10-20 17:42:27 -0500 (Sat, 20 Oct 2007) | 2 lines

Windows portability in GetBuildFailures() test scripts.
........
r2486 | stevenknight | 2007-10-20 20:46:26 -0500 (Sat, 20 Oct 2007) | 2 lines

Windows portability: rename internal copy.py script, use a stub instead of tar.
........
r2487 | stevenknight | 2007-10-24 23:36:24 -0500 (Wed, 24 Oct 2007) | 4 lines

Whenever a script configures SConsignFile(None), make sure it uses
stub compiler and linker scripts, not the system ones, to avoid writing
(or trying to write) .sconsign files in system directories.
........
r2488 | stevenknight | 2007-10-26 13:57:38 -0500 (Fri, 26 Oct 2007) | 2 lines

Issue 1764: Fix test-script portability issues on Solaris.
........
r2489 | stevenknight | 2007-10-27 07:37:37 -0500 (Sat, 27 Oct 2007) | 3 lines

Issue 1757: add a CheckTypeSize() call to Configure contexts
(David Cournapeau).
........
r2490 | stevenknight | 2007-10-28 07:58:30 -0500 (Sun, 28 Oct 2007) | 2 lines

Python 1.5.2 compatibility: no use of +=.
........
r2491 | stevenknight | 2007-10-29 12:13:35 -0500 (Mon, 29 Oct 2007) | 3 lines

Issue 1758: Fix the SCons packaging build for use with shared-lib
versions of Python and to avoid .egg-info naming issues.
........
r2492 | stevenknight | 2007-10-29 14:09:57 -0500 (Mon, 29 Oct 2007) | 2 lines

Document the "expect" argument to CheckTypeSize(). (David Cournapeau)
........
r2493 | stevenknight | 2007-11-05 20:57:27 -0600 (Mon, 05 Nov 2007) | 2 lines

Fix use of Glob() when a pattern is below an explicitly-named subdirectory.
........
r2495 | stevenknight | 2007-11-12 22:58:12 -0600 (Mon, 12 Nov 2007) | 5 lines

Add a get_sources() access method to avoid an O(n^2) problem when adding
sources to an Executor object. The old code weeded out duplicates
whenever a new source was added; the new code only does that when the
source is list going to be used.
........
r2496 | stevenknight | 2007-11-15 12:19:55 -0600 (Thu, 15 Nov 2007) | 4 lines

Redefine the $WINDOWSPROGMANIFESTSUFFIX and
$WINDOWSSHLIBMANIFESTSUFFIX variables so they pick up changes to
the underlying $SHLIBSUFFIX and $PROGSUFFIX variables.
........
r2497 | stevenknight | 2007-11-18 17:11:52 -0600 (Sun, 18 Nov 2007) | 4 lines

Support .status and .command attributes of BuildError exceptions.
Change Action objects to return BuildError objects (not raise them)
when an action fails.
........
r2498 | stevenknight | 2007-11-19 07:27:16 -0600 (Mon, 19 Nov 2007) | 3 lines

When converting .sconsign paths to Nodes, use the more efficient
_lookup_abs() method.
........
r2499 | stevenknight | 2007-11-25 00:18:20 -0600 (Sun, 25 Nov 2007) | 3 lines

Move the reflection-checking is_under() logic from the .srcdir_list()
method to the .srcdir_duplicate() method.
........
r2500 | stevenknight | 2007-11-25 00:31:33 -0600 (Sun, 25 Nov 2007) | 2 lines

Have the .srcnode() method use the .srcdir_list() method.
........
r2501 | stevenknight | 2007-11-28 22:56:39 -0600 (Wed, 28 Nov 2007) | 3 lines

Issue 1845: Have single-source Builders (like Object()) return
NodeList objects even when called with multiple files.
........
r2502 | stevenknight | 2007-11-28 23:00:46 -0600 (Wed, 28 Nov 2007) | 2 lines

Issue 1845: Document the NodeList behavior w.r.t Python's += operator.
........
r2503 | stevenknight | 2007-11-29 09:35:31 -0600 (Thu, 29 Nov 2007) | 3 lines

Issue 1840: Fix a lot of typos in the man page and Users' Guide.
(Malte Helmert)
........
r2504 | stevenknight | 2007-11-29 10:41:44 -0600 (Thu, 29 Nov 2007) | 3 lines

Issue 1841: Fix --implicit-cache spurious rebuilds and inefficiency
when using Builders that produce multiple targets. (Benoit Belley)
........
r2505 | stevenknight | 2007-11-30 17:36:03 -0600 (Fri, 30 Nov 2007) | 3 lines

Unit test fix for Python 1.5.2, which can't .extend() lists with
UserList objects.
........
r2506 | stevenknight | 2007-11-30 20:37:14 -0600 (Fri, 30 Nov 2007) | 2 lines

Python 1.5.2 portability: use string.join(), not ' '.join().
........
r2507 | stevenknight | 2007-11-30 21:42:19 -0600 (Fri, 30 Nov 2007) | 3 lines

When searching directory lists like $CPPPATH, don't make Dir Nodes for
directories that don't exist on disk.
........
r2508 | stevenknight | 2007-12-01 00:14:35 -0600 (Sat, 01 Dec 2007) | 2 lines

Add a Requires() function for specifying order-only prerequisites.
........
r2509 | stevenknight | 2007-12-01 07:32:24 -0600 (Sat, 01 Dec 2007) | 3 lines

Handle absolute paths without infinite recursion in the new code that
searches for implicit dependencies without creating unnecessary Dir Nodes.
........
r2510 | stevenknight | 2007-12-03 15:11:56 -0600 (Mon, 03 Dec 2007) | 2 lines

Restore the rel_path() method, for the benefit of SConscript files using it.
........
r2511 | stevenknight | 2007-12-04 00:34:02 -0600 (Tue, 04 Dec 2007) | 4 lines

User's Guide updates for the Big Signature refactoring, capturing mention
of things that still need documenting, and other changes from re-running
the examples through the latest code.
........
r2512 | stevenknight | 2007-12-04 08:48:51 -0600 (Tue, 04 Dec 2007) | 3 lines

Issue 1846: allow building only part of the dependency graph when
BuildDir(duplicate=0) is used. (Benoit Belley)
........
r2513 | stevenknight | 2007-12-06 05:02:56 -0600 (Thu, 06 Dec 2007) | 3 lines

Have the code that avoids creating unnecessary Dir Nodes when searching
$*PATH variables handle absolute paths with Windows drive letters.
........
r2514 | stevenknight | 2007-12-08 07:44:15 -0600 (Sat, 08 Dec 2007) | 6 lines

Issue 1852: Make the default behavior of
{Source,Target}Signatures('timestamp') equivalent to
'timestamp-match', not 'timestamp-newer'. Fix use of CacheDir with
Decider('timestamp-newer') by updating the modification time when copying
files from the cache.
........
r2515 | stevenknight | 2007-12-08 08:23:02 -0600 (Sat, 08 Dec 2007) | 4 lines

Update the mock compiler inin/sconsoutput to use $CPPPATH.
Capture the ripple effect in the Troubleshooting appendix.
Also add a -t option to the mock "touch" command.
........
r2516 | stevenknight | 2007-12-08 09:16:11 -0600 (Sat, 08 Dec 2007) | 3 lines

Update the Dependencies chapter for use of the Decider() function,
and to now discourage use of SourceSignatures() and TargetSignatures().
........
r2517 | stevenknight | 2007-12-08 12:31:10 -0600 (Sat, 08 Dec 2007) | 4 lines

Issue 1721: On Windows, wrap __builtin__.close() and __builtin__.file()
to disable file handle inheritance on any files opened by SCons during
the run.
........
r2518 | stevenknight | 2007-12-11 17:33:20 -0600 (Tue, 11 Dec 2007) | 4 lines

Prevent the _get_str() method from causing underlying stat() values
to be cached if we're not yet saving the string representations of
FS.Base() Nodes.
........
r2519 | stevenknight | 2007-12-11 23:27:05 -0600 (Tue, 11 Dec 2007) | 4 lines

Add a warning about the unreliability of -j if the pywin32 modules aren't
available or are old and can't suppress file handle inheritance.
Add a release note about the change to open() and file().
........
r2520 | stevenknight | 2007-12-11 23:28:05 -0600 (Tue, 11 Dec 2007) | 2 lines

Add an overlooked update, fix spelling.
........
r2521 | stevenknight | 2007-12-12 09:12:42 -0600 (Wed, 12 Dec 2007) | 3 lines

Use &TargetSignatures; (replace missing ampersand) in the title of
that section. Move the &Depends; section to before the &Ignore; section.
........
r2522 | stevenknight | 2007-12-12 09:20:46 -0600 (Wed, 12 Dec 2007) | 3 lines

Final documentation update for checkpoint release: propagate .in changes
to .xml files.
........
r2523 | stevenknight | 2007-12-12 09:29:11 -0600 (Wed, 12 Dec 2007) | 2 lines

Update release lines for new checkpoint release.
........

Comments (0)

Files changed (139)

QMTest/TestCmd.py

 
     test.subdir('subdir', ...)
 
+    test.rmdir('subdir', ...)
+
     test.write('file', "contents\n")
     test.write(['subdir', 'file'], "contents\n")
 
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 
 __author__ = "Steven Knight <knight at baldmt dot com>"
-__revision__ = "TestCmd.py 0.26.D001 2007/08/20 21:58:58 knight"
-__version__ = "0.26"
+__revision__ = "TestCmd.py 0.30.D001 2007/10/01 16:53:55 knight"
+__version__ = "0.30"
 
 import os
 import os.path
             raise ValueError, "mode must begin with 'r'"
         return open(file, mode).read()
 
+    def rmdir(self, dir):
+        """Removes the specified dir name.
+        The dir name may be a list, in which case the elements are
+        concatenated with the os.path.join() method.  The dir is
+        assumed to be under the temporary working directory unless it
+        is an absolute path name.
+        The dir must be empty.
+        """
+        dir = self.canonicalize(dir)
+        os.rmdir(dir)
+
     def run(self, program = None,
                   interpreter = None,
                   arguments = None,

QMTest/TestCommon.py

 
     test.must_contain('file', 'required text\n')
 
+    test.must_contain_lines(lines, output)
+
     test.must_exist('file1', ['file2', ...])
 
     test.must_match('file', "expected contents\n")
 
     test.must_not_be_writable('file1', ['file2', ...])
 
+    test.must_not_contain_lines(lines, output)
+
     test.must_not_exist('file1', ['file2', ...])
 
     test.run(options = "options to be prepended to arguments",
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 
 __author__ = "Steven Knight <knight at baldmt dot com>"
-__revision__ = "TestCommon.py 0.26.D001 2007/08/20 21:58:58 knight"
-__version__ = "0.26"
+__revision__ = "TestCommon.py 0.30.D001 2007/10/01 16:53:55 knight"
+__version__ = "0.30"
 
 import os
 import os.path
 from TestCmd import __all__
 
 __all__.extend([ 'TestCommon',
-                 'TestFailed',
-                 'TestNoResult',
                  'exe_suffix',
                  'obj_suffix',
                  'shobj_suffix',
             missing.append(f)
     return existing, missing
 
-class TestFailed(Exception):
-    def __init__(self, args=None):
-        self.args = args
-
-class TestNoResult(Exception):
-    def __init__(self, args=None):
-        self.args = args
-
 if os.name == 'posix':
     def _failed(self, status = 0):
         if self.status is None or status is None:
             return None
-        if os.WIFSIGNALED(self.status):
-            return None
         return _status(self) != status
     def _status(self):
         if os.WIFEXITED(self.status):
             return os.WEXITSTATUS(self.status)
+        elif os.WIFSIGNALED(self.status):
+            return os.WTERMSIG(self.status)
         else:
             return None
 elif os.name == 'nt':
             print file_contents
             self.fail_test(not contains)
 
+    def must_contain_lines(self, lines, output, title=None):
+        if title is None:
+            title = 'output'
+
+        missing = filter(lambda l, o=output: string.find(o, l) == -1, lines)
+
+        if missing:
+            print "Missing lines from %s:" % title
+            print string.join(missing, '\n')
+            print "%s ============================================================" % title
+            print output
+            self.fail_test()
+
     def must_exist(self, *files):
         """Ensures that the specified file(s) must exist.  An individual
         file be specified as a list of directory names, in which case the
             self.diff(expect, file_contents, 'contents ')
             raise
 
+    def must_not_contain_lines(self, lines, output=None, title=None):
+        if title is None:
+            title = 'output'
+
+        unexpected = filter(lambda l, o=output: string.find(o, l) != -1, lines)
+
+        if unexpected:
+            print "Unexpected lines in %s:" % title
+            print string.join(unexpected, '\n')
+            print "%s ============================================================" % title
+            print output
+            self.fail_test()
+
     def must_not_exist(self, *files):
         """Ensures that the specified file(s) must not exist.
         An individual file be specified as a list of directory names, in
             apply(TestCmd.run, [self], kw)
         except KeyboardInterrupt:
             raise
-        except:
+        except Exception, e:
             print self.banner('STDOUT ')
-            print self.stdout()
+            try:
+                print self.stdout()
+            except IndexError:
+                pass
             print self.banner('STDERR ')
-            print self.stderr()
-            raise
+            try:
+                print self.stderr()
+            except IndexError:
+                pass
+            raise e
         if _failed(self, status):
             expect = ''
             if status != 0:
             print self.stdout()
             print self.banner('STDERR ')
             print self.stderr()
-            raise TestFailed
+            self.fail_test()
         if not stdout is None and not match(self.stdout(), stdout):
             self.diff(stdout, self.stdout(), 'STDOUT ')
             stderr = self.stderr()
             if stderr:
                 print self.banner('STDERR ')
                 print stderr
-            raise TestFailed
+            self.fail_test()
         if not stderr is None and not match(self.stderr(), stderr):
             print self.banner('STDOUT ')
             print self.stdout()
             self.diff(stderr, self.stderr(), 'STDERR ')
-            raise TestFailed
+            self.fail_test()
 
     def skip_test(self, message="Skipping test.\n"):
         """Skips a test.
 import stat
 import string
 import sys
+import tempfile
 
 project = 'scons'
 default_version = '0.97.0'
 
 platform = distutils.util.get_platform()
 
+# Re-exporting LD_LIBRARY_PATH is necessary if the Python version was
+# built with the --enable-shared option.
+
 ENV = { 'PATH' : os.environ['PATH'] }
-for key in ['LOGNAME', 'PYTHONPATH']:
+for key in ['LOGNAME', 'PYTHONPATH', 'LD_LIBRARY_PATH']:
     if os.environ.has_key(key):
         ENV[key] = os.environ[key]
 
                           },
 }
 
-# The RPM spec file we generate will just execute "python", not
-# necessarily the one in sys.executable.  If that version of python has
-# a distutils that knows about Python eggs, then setup.py will generate
-# a .egg-info file.  Check for whether or not to add it to the expected
-# RPM files by executing "python" in a subshell.
+# Figure out the name of a .egg-info file that might be generated
+# as part of the RPM package.  There are two complicating factors.
+#
+# First, the RPM spec file we generate will just execute "python", not
+# necessarily the one in sys.executable.  If *that* version of python has
+# a distutils that knows about Python eggs, then setup.py will generate a
+# .egg-info file, so we have to execute any distutils logic in a subshell.
+#
+# Second, we can't just have the subshell check for the existence of the
+# distutils.command.install_egg_info module and generate the expected
+# file name by hand, the way we used to, because different systems can
+# have slightly different .egg-info naming conventions.  (Specifically,
+# Ubuntu overrides the default behavior to remove the Python version
+# string from the .egg-info file name.)  The right way to do this is to
+# actually call into the install_egg_info() class to have it generate
+# the expected name for us.
+#
+# This is all complicated enough that we do it by writing an in-line
+# script to a temporary file and then feeding it to a separate invocation
+# of "python" to tell us the actual name of the generated .egg-info file.
 
-cmd = "python -c 'import distutils.command.install_egg_info' > /dev/null 2>&1"
-import_egg_error = os.system(cmd)
+print_egg_info_name = """
+try:
+    from distutils.dist import Distribution
+    from distutils.command.install_egg_info import install_egg_info
+except ImportError:
+    pass
+else:
+    dist = Distribution({'name' : "scons", 'version' : '%s'})
+    i = install_egg_info(dist)
+    i.finalize_options()
+    import os.path
+    print os.path.split(i.outputs[0])[1]
+""" % version
 
-if not import_egg_error:
-    egg_info_file = 'scons-' + version + '.egg-info'
-    python_scons['extra_rpm_files'].append(egg_info_file)
+try:
+    fd, tfname = tempfile.mkstemp()
+    tfp = os.fdopen(fd, "w")
+    tfp.write(print_egg_info_name)
+    tfp.close()
+    egg_info_file = os.popen("python %s" % tfname).read()[:-1]
+    if egg_info_file:
+        python_scons['extra_rpm_files'].append(egg_info_file)
+finally:
+    try:
+        os.unlink(tfname)
+    except EnvironmentError:
+        pass
 
 #
 # The original packaging scheme would have have required us to push

bin/sconsoutput.py

 
 def CCCom(target, source, env):
     target = str(target[0])
-    f = open(target, "wb")
+    fp = open(target, "wb")
+    def process(source_file, fp=fp):
+        for line in open(source_file, "rb").readlines():
+            m = re.match(r'#include\s[<"]([^<"]+)[>"]', line)
+            if m:
+                include = m.group(1)
+                for d in [str(env.Dir('$CPPPATH')), '.']:
+                    f = os.path.join(d, include)
+                    if os.path.exists(f):
+                        process(f)
+                        break
+            elif line[:11] != "STRIP CCCOM":
+                fp.write(line)
     for src in map(str, source):
-        lines = open(src, "rb").readlines()
-        lines = filter(lambda l: l[:11] != "STRIP CCCOM", lines)
-        f.write(string.join(lines))
-    f.close()
+        process(src)
+        fp.write('debug = ' + ARGUMENTS.get('debug', '0') + '\\n')
+    fp.close()
 
 public_class_re = re.compile('^public class (\S+)', re.MULTILINE)
 
     return lines
 
 def command_touch(args, c, test, dict):
-    time.sleep(1)
+    if args[0] == '-t':
+        t = int(time.mktime(time.strptime(args[1], '%Y%m%d%H%M')))
+        times = (t, t)
+        args = args[2:]
+    else:
+        time.sleep(1)
+        times = None
     for file in args:
         if not os.path.isabs(file):
             file = os.path.join(test.workpath('WORK'), file)
         if not os.path.exists(file):
             open(file, 'wb')
-        os.utime(file, None)
+        os.utime(file, times)
     return []
 
 def command_edit(args, c, test, dict):
             elif lines:
                 content = string.join(lines, '\n' + p)
             if content:
+                content = re.sub(' at 0x[0-9a-fA-F]*\>', ' at 0x700000&gt;', content)
                 content = string.replace(content, '<', '&lt;')
                 content = string.replace(content, '>', '&gt;')
                 sys.stdout.write(p + content + '\n')
 in which case only the specified targets will be built
 (along with any derived files on which they depend).
 
-Specifying "cleanup" targets in SConscript files is not
-necessary.  The 
+Specifying "cleanup" targets in SConscript files is not usually necessary.
+The 
 .B -c
 flag removes all files
 necessary to build the specified target:
 Search the specified repository for any input and target
 files not found in the local directory hierarchy.  Multiple
 .B -Y
-options may specified, in which case the
+options may be specified, in which case the
 repositories are searched in the order specified.
 
 .SH CONFIGURATION FILE REFERENCE
 
 Additionally, a specific set of tools
 with which to initialize the environment
-may specified as an optional keyword argument:
+may be specified as an optional keyword argument:
 
 .ES
 env = Environment(tools = ['msvc', 'lex'])
 environment's builder methods.
 The arguments to the builder methods are
 .B target
-(a list of target files)
+(a list of targets to be built,
+usually file names)
 and
 .B source
-(a list of source files).
+(a list of sources to be built,
+usually file names).
 
 Because long lists of file names
 can lead to a lot of quoting,
 env.Program('bar', source = string.split('bar.c foo.c'))
 .EE
 
+Target and source file names
+that are not absolute path names
+(that is, do not begin with
+.B /
+on POSIX systems
+or 
+.B \\
+on Windows systems,
+with or without
+an optional drive letter)
+are interpreted relative to the directory containing the
+.B SConscript
+file being read.
+An initial
+.B #
+(hash mark)
+on a path name means that the rest of the file name
+is interpreted relative to
+the directory containing
+the top-level
+.B SConstruct
+file,
+even if the
+.B #
+is followed by a directory separator character
+(slash or backslash).
+
+Examples:
+
+.ES
+# The comments describing the targets that will be built
+# assume these calls are in a SConscript file in the
+# a subdirectory named "subdir".
+
+# Builds the program "subdir/foo" from "subdir/foo.c":
+env.Program('foo', 'foo.c')
+
+# Builds the program "/tmp/bar" from "subdir/bar.c":
+env.Program('/tmp/bar', 'bar.c')
+
+# An initial '#' or '#/' are equivalent; the following
+# calls build the programs "foo" and "bar" (in the
+# top-level SConstruct directory) from "subdir/foo.c" and
+# "subdir/bar.c", respectively:
+env.Program('#foo', 'foo.c')
+env.Program('#/bar', 'bar.c')
+
+# Builds the program "other/foo" (relative to the top-level
+# SConstruct directory) from "subdir/foo.c":
+env.Program('#other/foo', 'foo.c')
+.EE
+
 When the target shares the same base name
 as the source and only the suffix varies,
 and if the builder method has a suffix defined for the target file type,
 from SCons.Script import *
 .EE
 
-All builder methods return a list of Nodes
-that represent the target or targets that will be built.
+All builder methods return a list-like object
+containing Nodes that
+represent the target or targets that will be built.
 A
 .I Node
 is an internal SCons object
 which represents
 build targets or sources.
 
-The returned Node(s)
+The returned Node-list object
 can be passed to other builder methods as source(s)
 or passed to any SCons function or method
 where a filename would normally be accepted.
 
 Or you can use the
 .BR Flatten ()
-supplied by scons
+function supplied by scons
 to create a list containing just the Nodes,
 which may be more convenient:
 
     print str(object)
 .EE
 
+Note also that because Builder calls return
+a list-like object, not an actual Python list,
+you should
+.I not
+use the Python
+.B +=
+operator to append Builder results to a Python list.
+Because the list and the object are different types,
+Python will not update the original list in place,
+but will instead create a new Node-list object
+containing the concatenation of the list
+elements and the Builder results.
+This will cause problems for any other Python variables
+in your SCons configuration
+that still hold on to a reference to the original list.
+Instead, use the Python
+.B .extend()
+method to make sure the list is updated in-place.
+Example:
+
+.ES
+object_files = []
+
+# Do NOT use += as follows:
+#
+#    object_files += Object('bar.c')
+#
+# It will not update the object_files list in place.
+#
+# Instead, use the .extend() method:
+object_files.extend(Object('bar.c'))
+
+.EE
+
 The path name for a Node's file may be used
 by passing the Node to the Python-builtin
 .B str()
 .RI FindInstalledFiles( )
 .TP
 .RI env.FindInstalledFiles( )
-Returns the list of targets setup by the
+Returns the list of targets set up by the
 .B Install()
 or
 .B InstallAs()
 builders.
 
 This function serves as a convenient method to select the contents of
-a Binary Package.
+a binary package.
 
 Example:
 
 It does so by inspecting the dependency tree starting at the optional
 argument
 .B node
-which defaults to the '"."'-node. It will then return all leafs of
+which defaults to the '"."'-node. It will then return all leaves of
 .B node.
 These are all children which have no further children.
 
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI GetBuildFailures()
+Returns a list of exceptions for the
+actions that failed while
+attempting to build targets.
+Each element in the returned list is a
+.B BuildError
+object
+with the following attributes
+that record various aspects
+of the build failure:
+
+.B .node
+The node that was being built
+when the build failure occurred.
+
+.B .status
+The numeric exit status
+returned by the command or Python function
+that failed when trying to build the
+specified Node.
+
+.B .errstr
+The SCons error string
+describing the build failure.
+(This is often a generic
+message like "Error 2"
+to indicate that an executed
+command exited with a status of 2.)
+
+.B .filename
+The name of the file or
+directory that actually caused the failure.
+This may be different from the
+.B .node
+attribute.
+For example,
+if an attempt to build a target named
+.B sub/dir/target
+fails because the
+.B sub/dir
+directory could not be created,
+then the
+.B .node
+attribute will be
+.B sub/dir/target
+but the
+.B .filename
+attribute will be
+.BR sub/dir .
+
+.B .executor
+The SCons Executor object
+for the target Node
+being built.
+This can be used to retrieve
+the construction environment used
+for the failed action.
+
+.B .action
+The actual SCons Action object that failed.
+This will be one specific action
+out of the possible list of
+actions that would have been
+executed to build the target.
+
+.B .command
+The actual expanded command that was executed and failed,
+after expansion of
+.BR $TARGET ,
+.BR $SOURCE ,
+and other construction variables.
+
+Note that the
+.BR GetBuildFailures ()
+function
+will always return an empty list
+until any build failure has occurred,
+which means that
+.BR GetBuildFailures ()
+will always return an empty list
+while the
+.B SConscript
+files are being read.
+Its primary intended use is
+for functions that will be
+executed before SCons exits
+by passing them to the
+standard Python
+.BR atexit.register ()
+function.
+Example:
+
+.ES
+import atexit
+
+def print_build_failures():
+    from SCons.Script import GetBuildFailures
+    for bf in GetBuildFailures():
+        print "%s failed: %s" % (bf.node, bf.errstr)
+
+atexit.register(print_build_failures)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI GetBuildPath( file ", [" ... ])
 .TP
 .IR SetOption () 
 for a description of the options available.
 
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
+.TP
+.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
+Returns Nodes (or strings) that match the specified
+.IR pattern ,
+relative to the directory of the current
+.B SConscript
+file.
+The
+.BR env.Glob ()
+form performs string substition on
+.I pattern
+and returns whatever matches
+the resulting expanded pattern.
+
+The specified
+.I pattern
+uses Unix shell style metacharacters for matching:
+
+.ES
+  *       matches everything
+  ?       matches any single character
+  [seq]   matches any character in seq
+  [!seq]  matches any char not in seq
+.EE
+
+Character matches do
+.I not
+span directory separators.
+
+The
+.BR Glob ()
+knows about
+repositories
+(see the
+.BR Repository ()
+function)
+and source directories
+(see the
+.BR BuildDir ()
+function)
+and
+returns a Node (or string, if so configured)
+in the local (SConscript) directory
+if matching Node is found
+anywhere in a corresponding
+repository or source directory.
+
+The
+.B ondisk
+argument may be set to
+.B False
+(or any other non-true value)
+to disable the search for matches on disk,
+thereby only returning matches among
+already-configured File or Dir Nodes.
+The default behavior is to
+return corresponding Nodes
+for any on-disk matches found.
+
+The
+.B source
+argument may be set to
+.B True
+(or any equivalent value)
+to specify that,
+when the local directory is a
+.BR BuildDir (),
+the returned Nodes should be from the
+corresponding source directory,
+not the local directory.
+
+The
+.B strings
+argument may be set to
+.B True
+(or any equivalent value)
+to have the
+.BR Glob ()
+function return strings, not Nodes,
+that represent the matched files or directories.
+The returned strings will be relative to
+the local (SConscript) directory.
+(Note that This may make it easier to perform
+arbitrary manipulation of file names,
+but if the returned strings are
+passed to a different
+.B SConscript
+file,
+any Node translation will be relative
+to the other
+.B SConscript
+directory,
+not the original
+.B SConscript
+directory.)
+
+Example:
+
+.ES
+Program('foo', Glob('*.c'))
+.EE
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 '\".TP
 '\".RI GlobalBuilders( flag )
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI Requires( target ", " prerequisite )
+.TP
+.RI env.Requires( target ", " prerequisite )
+Specifies an order-only relationship
+between the specified target file(s)
+and the specified prerequisite file(s).
+The prerequisite file(s)
+will be (re)built, if necessary,
+.I before
+the target file(s),
+but the target file(s) do not actually
+depend on the prerequisites
+and will not be rebuilt simply because
+the prerequisite file(s) change.
+
+Example:
+
+.ES
+env.Requires('foo', 'file-that-must-be-built-before-foo')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 .RI Return([ vars "... , " stop= ])
 By default,
 this stops processing the current SConscript
 .RI SourceSignatures( type )
 .TP
 .RI env.SourceSignatures( type )
-This function tells
+Note:  Although it is not yet officially deprecated,
+use of this function is discouraged.
+See the
+.BR Decider ()
+function for a more flexible and straightforward way
+to configure SCons' decision-making.
+
+The
+.BR SourceSignatures ()
+function tells
 .B scons
 how to decide if a source file
 (a file that is not built from any other files)
 means
 .B scons
 decides that a source file has changed
-if its timestamp (modification time) is newer than
+if its timestamp (modification time) has changed since
 the last time it was used to rebuild a particular target file.
+(Note that although this is similar to the behavior of Make,
+by default it will also rebuild if the dependency is
+.I older
+than the last time it was used to rebuild the target file.)
 
 There is no different between the two behaviors
 for Python
 .RI TargetSignatures( type )
 .TP
 .RI env.TargetSignatures( type )
-This function tells
+Note:  Although it is not yet officially deprecated,
+use of this function is discouraged.
+See the
+.BR Decider ()
+function for a more flexible and straightforward way
+to configure SCons' decision-making.
+
+The
+.BR TargetSignatures ()
+function tells
 .B scons
 how to decide if a target file
 (a file that
 means
 .B scons
 decides that a target file has changed
-if its timestamp (modification time) is newer than
+if its timestamp (modification time) has changed since
 the last time it was used to rebuild some other target file.
+(Note that although this is similar to the behavior of Make,
+by default it will also rebuild if the dependency is
+.I older
+than the last time it was used to rebuild the target file.)
 
 .B "source"
 means
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
 '\"
-'\" The descriptions below of the various SCons contruction variables
+'\" The descriptions below of the various SCons construction variables
 '\" are generated from the .xml files that live next to the various
 '\" Python modules in the build enginer library.  If you're reading
 '\" this [gnt]roff file with an eye towards patching this man page,
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
 '\"
-'\" The descriptions above of the various SCons contruction variables
+'\" The descriptions above of the various SCons construction variables
 '\" are generated from the .xml files that live next to the various
 '\" Python modules in the build enginer library.  If you're reading
 '\" this [gnt]roff file with an eye towards patching this man page,
 The following methods can be used to perform checks:
 
 .TP
-.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
-.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
+.TP
+.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
 This creates a configure context, which can be used to perform checks.
 .I env
 specifies the environment for building the tests.
 .I config_h
 file is being built.
 
+The optional
+.B clean
+and
+.B help
+arguments can be used to suppress execution of the configuration
+tests when the
+.B -c/--clean
+or
+.B -H/-h/--help
+options are used, respectively.
+The default behavior is always to execute
+configure context tests,
+since the results of the tests may
+affect the list of targets to be cleaned
+or the help text.
+If the configure tests do not affect these,
+then you may add the
+.B clean=False
+or
+.B help=False
+arguments
+(or both)
+to avoid unnecessary test execution.
+
 .EE
 A created
 .B Configure
 env = conf.Finish() 
 .EE
 
+.TP
+.RI Configure.CheckTypeSize( self ", " type_name ", [" header ", " language ", " expect ])
+Checks for the size of a type defined by
+.BR typedef .
+.I type_name
+specifies the typedef name to check for.
+The optional
+.I header
+argument is a string
+that will be
+placed at the top
+of the test file
+that will be compiled
+to check if the function exists;
+the default is empty.
+The optional
+.I language
+argument should be
+.B C
+or
+.B C++
+and selects the compiler to be used for the check;
+the default is "C".
+The optional
+.I expect
+argument should be an integer.
+If this argument is used,
+the function will only check whether the type
+given in type_name has the expected size (in bytes).
+For example,
+.B "CheckTypeSize('short', expect = 2)"
+will return success only if short is two bytes.
+
+.ES
+.EE
+
 .EE
 You can define your own custom checks. 
 in addition to the predefined checks.
 locations, or site-specific compiler options may need to be passed to the
 compiler. 
 .B scons
-provides a mechanism for overridding construction variables from the
-command line or a text-based SConscript file through an Options
-object. To create an Options object, call the Options() function:
+provides an Options object for overridding construction variables
+on the command line:
+.ES
+$ scons VARIABLE=foo
+.EE
+The variable values can also be specified in a text-based SConscript file.
+To create an Options object, call the Options() function:
 
 .TP
 .RI Options([ files "], [" args ])
 .RI Update( env ", [" args ])
 This updates a construction environment
 .I env
-with the customized construction variables. Normally this method is not
-called directly, but is called indirectly by passing the Options object to
+with the customized construction variables.
+Any specified variables that are
+.I not
+configured for the Options object
+will be saved and may be
+retrieved with the
+.BR UnknownOptions ()
+method, below.
+
+Normally this method is not called directly,
+but is called indirectly by passing the Options object to
 the Environment() function:
 
 .ES
 are executed as Python scripts,
 and the values of (global) Python variables set in the file
 are added to the construction environment.
+
 Example:
 
 .ES
 .EE
 
 .TP
+.RI UnknownOptions( )
+Returns a dictionary containing any
+variables that were specified
+either in the files or the dictionary
+with which the Options object was intialized,
+but for which the Options object was
+not configured.
+
+.ES
+env = Environment(options=opts)
+for key, value in opts.UnknownOptions():
+    print "unknown variable:  %s=%s" % (key, value)
+.EE
+
+.TP
 .RI Save( filename ", " env )
 This saves the currently set options into a script file named  
 .I filename
 (for example, 'liba.a' on POSIX systems,
 'a.lib' on Windows).
 
-.SS Customizing contruction variables from the command line.
+.SS Customizing construction variables from the command line.
 
 The following would allow the C compiler to be specified on the command
 line or in the file custom.py. 
 <!ENTITY Command "<function>Command</function>">
 <!ENTITY Configure "<function>Configure</function>">
 <!ENTITY Copy "<function>Copy</function>">
+<!ENTITY Decider "<function>Decider</function>">
 <!ENTITY Default "<function>Default</function>">
 <!ENTITY DefaultRules "<function>DefaultRules</function>">
 <!ENTITY Delete "<function>Delete</function>">
     The drawback is that the build can behave
     differently if it's run by people with
     different &PATH; values in their environment--for example,
-    both the <literal>/bin</literal> and
+    if both the <literal>/bin</literal> and
     <literal>/usr/local/bin</literal> directories
     have different &cc; commands,
     then which one will be used to compile programs
     The drawback is that the build can behave
     differently if it's run by people with
     different &PATH; values in their environment--for example,
-    both the <literal>/bin</literal> and
+    if both the <literal>/bin</literal> and
     <literal>/usr/local/bin</literal> directories
     have different &cc; commands,
     then which one will be used to compile programs

doc/user/builders-writing.in

 
     <para>
 
-    To be able use both our own defined &Builder; objects
+    To be able to use both our own defined &Builder; objects
     and the default &Builder; objects in the same &consenv;,
     you can either add to the &cv-BUILDERS; variable
     using the &Append; function:

doc/user/builders-writing.xml

 
     <para>
 
-    To be able use both our own defined &Builder; objects
+    To be able to use both our own defined &Builder; objects
     and the default &Builder; objects in the same &consenv;,
     you can either add to the &cv-BUILDERS; variable
     using the &Append; function:

doc/user/command-line.in

     <para>
 
     If, for example,
-    and you're using a POSIX shell that's
+    you're using a POSIX shell that's
     compatible with the Bourne shell,
     and you always want &SCons; to use the
     <literal>-Q</literal> option,
 
     <para>
 
-    Windows users may typically want to set this
+    Windows users may typically want to set the
     &SCONSFLAGS; in the appropriate tab of the
     <literal>System Properties</literal> window.
 
       to control an expected path name.
       If, for example, you need to
       define a variable in the preprocessor
-      that control the location of a
+      that controls the location of a
       configuration file:
 
       </para>
     </para>
 
   </section>
+
+  <!--
+
+  AddOption() function for things like - -prefix=, - -force
+
+  -->

doc/user/command-line.xml

     <para>
 
     If, for example,
-    and you're using a POSIX shell that's
+    you're using a POSIX shell that's
     compatible with the Bourne shell,
     and you always want &SCons; to use the
     <literal>-Q</literal> option,
 
     <para>
 
-    Windows users may typically want to set this
+    Windows users may typically want to set the
     &SCONSFLAGS; in the appropriate tab of the
     <literal>System Properties</literal> window.
 
       to control an expected path name.
       If, for example, you need to
       define a variable in the preprocessor
-      that control the location of a
+      that controls the location of a
       configuration file:
 
       </para>
     </para>
 
   </section>
+
+  <!--
+
+  AddOption() function for things like - -prefix=, - -force
+
+  -->

doc/user/depends.in

   <para>
 
   So far we've seen how &SCons; handles one-time builds.
-  But the real point of a build tool like &SCons;
+  But one of the main functions of a build tool like &SCons;
   is to rebuild only the necessary things
   when source files change--or, put another way,
   &SCons; should <emphasis>not</emphasis>
   waste time rebuilding things that have already been built.
-  You can see this at work simply be re-invoking &SCons;
+  You can see this at work simply by re-invoking &SCons;
   after building our simple &hello; example:
 
   </para>
   </para>
 
   <section>
-  <title>Deciding When a Source File Has Changed:  the &SourceSignatures; Function</title>
+  <title>Deciding When an Input File Has Changed:  the &Decider; Function</title>
 
     <para>
 
-    The other side of avoiding unnecessary rebuilds
+    Another aspect of avoiding unnecessary rebuilds
     is the fundamental build tool behavior
     of <emphasis>rebuilding</emphasis>
-    things when a source file changes,
+    things when an input file changes,
     so that the built software is up to date.
-    &SCons; keeps track of this through a
-    &signature; for each source file,
-    and allows you to configure
-    whether you want to use the source
-    file contents or the modification time (timestamp)
-    as the signature.
+    By default,
+    &SCons; keeps track of this through an
+    MD5 &signature;, or checksum, of the contents of each file,
+    although you can easily configure
+    &SCons; to use the
+    modification times (or time stamps)
+    instead.
+    You can even specify your own Python function
+    for deciding if an input file has changed.
 
     </para>
 
     <section>
-    <title>MD5 Source File Signatures</title>
+    <title>Using MD5 Signatures to Decide if a File Has Changed</title>
 
       <para>
 
       By default,
-      &SCons; keeps track of whether a source file has changed
-      based on the file's contents,
-      not the modification time.
+      &SCons; keeps track of whether a file has changed
+      based on an MD5 checksum of the file's contents,
+      not the file's modification time.
       This means that you may be surprised by the
       default &SCons; behavior if you are used to the
       &Make; convention of forcing
       Note that you can, if you wish,
       specify this default behavior
       (MD5 signatures) explicitly
-      using the &SourceSignatures; function as follows:
+      using the &Decider; function as follows:
 
       </para>
 
       <sconstruct>
         Program('hello.c')
-        SourceSignatures('MD5')
+        Decider('MD5')
       </sconstruct>
 
+      <para>
+
+      You can also use the string <literal>'content'</literal>
+      as a synonym for <literal>'MD5'</literal>
+      when calling the &Decider; function.
+
+      </para>
+
+      <section>
+      <title>Ramifications of Using MD5 Signatures</title>
+
+        <para>
+
+        Using MD5 Signatures to decide if an input file has changed
+        has one surprising benefit:
+        if a source file has been changed
+        in such a way that the contents of the
+        rebuilt target file(s)
+        will be exactly the same as the last time
+        the file was built,
+        then any "downstream" target files
+        that depend on the rebuilt-but-not-changed target
+        file actually need not be rebuilt.
+
+        </para>
+
+        <para>
+
+        So if, for example,
+        a user were to only change a comment in a &hello_c; file,
+        then the rebuilt &hello_o; file
+        would be exactly the same as the one previously built
+        (assuming the compiler doesn't put any build-specific
+        information in the object file).
+        &SCons; would then realize that it would not
+        need to rebuild the &hello; program as follows:
+
+        </para>
+
+        <scons_output example="ex1" os="posix">
+           <scons_output_command>scons -Q hello</scons_output_command>
+           <scons_output_command output="  [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</scons_output_command>
+           <scons_output_command>scons -Q hello</scons_output_command>
+        </scons_output>
+
+        <para>
+
+        In essence, &SCons;
+        "short-circuits" any dependent builds
+        when it realizes that a target file
+        has been rebuilt to exactly the same file as the last build.
+        This does take some extra processing time
+        to read the contents of the target (&hello_o;) file,
+        but often saves time when the rebuild that was avoided
+        would have been time-consuming and expensive.
+
+        </para>
+
+      </section>
+
     </section>
 
     <section>
-    <title>Source File Time Stamps</title>
+    <title>Using Time Stamps to Decide If a File Has Changed</title>
 
       <para>
 
       If you prefer, you can
       configure &SCons; to use the modification time
-      of source files,
-      not the file contents,
-      when deciding if something needs to be rebuilt.
-      To do this, call the &SourceSignatures;
+      of a file, not the file contents,
+      when deciding if a target needs to be rebuilt.
+      &SCons; gives you two ways to use time stamps
+      to decide if an input file has changed
+      since the last time a target has been built.
+
+      </para>
+
+      <para>
+
+      The most familiar way to use time stamps
+      is the way &Make; does:
+      that is, have &SCons; decide
+      and target must be rebuilt if
+      if a source file's modification time is
+      <emphasis>newer</emphasis>
+      than the target file.
+      To do this, call the &Decider;
       function as follows:
 
       </para>
 
-      <scons_example name="ex2">
+      <scons_example name="newer">
         <file name="SConstruct" printme="1">
         Program('hello.c')
-        SourceSignatures('timestamp')
+        Decider('timestamp-newer')
         </file>
         <file name="hello.c">
         int main() { printf("Hello, world!\n"); }
 
       </para>
 
-      <scons_output example="ex2" os="posix">
+      <scons_output example="newer" os="posix">
          <scons_output_command>scons -Q hello</scons_output_command>
          <scons_output_command>touch hello.c</scons_output_command>
          <scons_output_command>scons -Q hello</scons_output_command>
       </scons_output>
 
-    </section>
+      <para>
 
-  </section>
+      And, in fact, because this behavior is the same
+      as the behavior of &Make;,
+      you can also use the string <literal>'make'</literal>
+      as a synonym for <literal>'timestamp-newer'</literal>
+      when calling the &Decider; function:
 
-  <section>
-  <title>Deciding When a Target File Has Changed:  the &TargetSignatures; Function</title>
+      </para>
 
-    <para>
-
-    As you've just seen,
-    &SCons; uses signatures to decide whether a
-    target file is up to date or must be rebuilt.
-    When a target file depends on another target file,
-    &SCons; allows you to configure separately
-    how the signatures of "intermediate" target files
-    are used when deciding if a dependent target file
-    must be rebuilt.
-
-    </para>
-
-    <section>
-    <title>Build Signatures</title>
+      <sconstruct>
+        Program('hello.c')
+        Decider('make')
+      </sconstruct>
 
       <para>
 
-      Modifying a source file
-      will cause not only its direct target file to be rebuilt,
-      but also the target file(s)
-      that depend on that direct target file.
-      In our example,
-      changing the contents of the &hello_c; file causes
-      the &hello_o; file to be rebuilt,
-      which in turn causes the
-      &hello; program to be rebuilt:
-
-      </para>
-
-      <scons_output example="ex1" os="posix">
-         <scons_output_command>scons -Q hello</scons_output_command>
-         <scons_output_command output="    [CHANGE THE CONTENTS OF hello.c]">edit hello.c</scons_output_command>
-         <scons_output_command>scons -Q hello</scons_output_command>
-      </scons_output>
-
-      <para>
-
-      What's not obvious, though,
-      is that &SCons; internally handles the signature of
-      the target file(s)
-      (&hello_o; in the above example)
-      differently from the signature of the source file
-      (&hello_c;).
-      By default,
-      &SCons; tracks whether a target file must be rebuilt
-      by using a &buildsignature;
-      that consists of the combined
-      signatures of all the files
-      that go into making the target file.
-      This is efficient because
-      the accumulated signatures
-      actually give &SCons; all of the
-      information it needs
-      to decide if the target file is out of date.
+      One drawback to using times stamps exactly like &Make;
+      is that if an input file's modification time suddenly
+      becomes <emphasis>older</emphasis> than a target file,
+      the target file will not be rebuilt.
+      This can happen if an old copy of a source file is restored
+      from a backup archive, for example.
+      The contents of the restored file will likely be different
+      than they were the last time a dependent target was built,
+      but the target won't be rebuilt
+      because the modification time of the source file
+      is not newer than the target.
 
       </para>
 
       <para>
 
-      If you wish, you can
-      specify this default behavior
-      (build signatures) explicitly
-      using the &TargetSignatures; function:
+      Because &SCons; actually stores information
+      about the source files' time stamps whenever a target is built,
+      it can handle this situation by checking for
+      an exact match of the source file time stamp,
+      instead of just whether or not the source file
+      is newer than the target file.
+      To do this, specify the argument
+      <literal>'timestamp-match'</literal>
+      when calling the &Decider; function:
 
       </para>
 
-      <sconstruct>
-        Program('hello.c')
-        TargetSignatures('build')
-      </sconstruct>
-
-    </section>
-
-    <section>
-    <title>File Contents</title>
-
-      <para>
-
-      Sometimes a source file can be changed
-      in such a way that the contents of the
-      rebuilt target file(s)
-      will be exactly the same as the last time
-      the file was built.
-      If so, then any other target files
-      that depend on such a built-but-not-changed target
-      file actually need not be rebuilt.
-      You can make &SCons;
-      realize that it does not need to rebuild
-      a dependent target file in this situation
-      using the &TargetSignatures; function as follows:
-
-      </para>
-
-      <scons_example name="ex3">
+      <scons_example name="match">
         <file name="SConstruct" printme="1">
         Program('hello.c')
-        TargetSignatures('content')
+        Decider('timestamp-match')
         </file>
         <file name="hello.c">
         int main() { printf("Hello, world!\n"); }
 
       <para>
 
-      So if, for example,
-      a user were to only change a comment in a C file,
-      then the rebuilt &hello_o; file
-      would be exactly the same as the one previously built
-      (assuming the compiler doesn't put any build-specific
-      information in the object file).
-      &SCons; would then realize that it would not
-      need to rebuild the &hello; program as follows:
+      When configured this way,
+      &SCons; will rebuild a target whenever
+      a source file's modification time has changed.
+      So if we use the <literal>touch -t</literal>
+      option to change the modification time of
+      &hello_c; to an old date (January 1, 1989),
+      &SCons; will still rebuild the target file:
 
       </para>
 
-      <scons_output example="ex3" os="posix">
+      <scons_output example="match" os="posix">
          <scons_output_command>scons -Q hello</scons_output_command>
-         <scons_output_command output="  [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</scons_output_command>
+         <scons_output_command>touch -t 198901010000 hello.c</scons_output_command>
          <scons_output_command>scons -Q hello</scons_output_command>
       </scons_output>
 
       <para>
 
-      In essence, &SCons; has
-      "short-circuited" any dependent builds
-      when it realizes that a target file
-      has been rebuilt to exactly the same file as the last build.
-      So configured,
-      &SCons; does take some extra processing time
-      to scan the contents of the target (&hello_o;) file,
-      but this may save time
-      if the rebuild that was avoided
-      would have been very time-consuming and expensive.
+      In general, the only reason to prefer
+      <literal>timestamp-newer</literal>
+      instead of
+      <literal>timestamp-match</literal>,
+      would be if you have some specific reason
+      to require this &Make;-like behavior of 
+      not rebuilding a target when an otherwise-modified
+      source file is older.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Deciding If a File Has Changed Using Both MD Signatures and Time Stamps</title>
+
+      <para>
+
+      As a performance enhancement,
+      &SCons; provides a way to use
+      MD5 checksums of file contents
+      but to only read the contents
+      whenever the file's timestamp has changed.
+      To do this, call the &Decider;
+      function with <literal>'MD5-timestamp'</literal>
+      argument as follows:
+
+      </para>
+
+      <scons_example name="MD5-timestamp">
+        <file name="SConstruct" printme="1">
+        Program('hello.c')
+        Decider('MD5-timestamp')
+        </file>
+        <file name="hello.c">
+        int main() { printf("Hello, world!\n"); }
+        </file>
+      </scons_example>
+
+      <para>
+
+      So configured, &SCons will still behave like
+      it does when using <literal>Decider('MD5')</literal>:
+
+      </para>
+
+      <scons_output example="MD5-timestamp" os="posix">
+         <scons_output_command>scons -Q hello</scons_output_command>
+         <scons_output_command>touch hello.c</scons_output_command>
+         <scons_output_command>scons -Q hello</scons_output_command>
+       <scons_output_command output="    [CHANGE THE CONTENTS OF hello.c]">edit hello.c</scons_output_command>
+         <scons_output_command>scons -Q hello</scons_output_command>
+      </scons_output>
+
+      <para>
+
+      However, the second call to &SCons; in the above output,
+      when the build is up-to-date,
+      will have been performed by simply looking at the
+      modification time of the &hello_c; file,
+      not by opening it and performing
+      an MD5 checksum calcuation on its contents.
+      This can significantly speed up many up-to-date builds.
+
+      </para>
+
+      <para>
+
+      The only drawback to using
+      <literal>Decider('MD5-timestamp')</literal>
+      is that &SCons; will <emphasis>not</emphasis>
+      rebuild a target file if a source file was modified
+      within one second of the last time &SCons; built the file.
+      While most developers are programming,
+      this isn't a problem in practice,
+      since it's unlikely that someone will have built
+      and then thought quickly enought to make a substantive
+      change to a source file within one second.
+      Certain build scripts or
+      continuous integration tools may, however,
+      rely on the ability to applying changes to files
+      automatically and then rebuild as quickly as possible,
+      in which case use of
+      <literal>Decider('MD5-timestamp')</literal>
+      may not be appropriate.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Writing Your Own Custom &Decider; Function</title>
+
+      <para>
+
+      The different string values that we've passed to
+      the &Decider; function are essentially used by &SCons;
+      to pick one of several specific internal functions
+      that implement various ways of deciding if a dependency
+      (usually a source file)
+      has changed since a target file has been built.
+      As it turns out,
+      you can also supply your own function
+      to decide if a dependency has changed.
+
+      </para>
+
+      <para>
+
+      For example, suppose we have an input file
+      that contains a lot of data,
+      in some specific regular format,
+      that is used to rebuild a lot of different target files,
+      but each target file really only depends on
+      one particular section of the input file.
+      We'd like to have each target file depend on
+      only its section of the input file.
+      However, since the input file may contain a lot of data,
+      we only want to open the input file if its timestamp has changed.
+      This could done with a custom
+      &Decider; function that might look something like this:
+
+      </para>
+
+      <scons_example name="function">
+        <file name="SConstruct" printme="1">
+        Program('hello.c')
+        def decide_if_changed(dependency, target, prev_ni):
+            if self.get_timestamp() != prev_ni.timestamp:
+                dep = str(dependency)
+                tgt = str(target)
+                if specific_part_of_file_has_changed(dep, tgt):
+                    return True
+            return False
+        Decider(decide_if_changed)
+        </file>
+        <file name="hello.c">
+        int main() { printf("Hello, world!\n"); }
+        </file>
+      </scons_example>
+
+      <para>
+
+      Note that in the function definition,
+      the <literal>dependency</literal>
+      (input file) is the first argument,
+      and then the <literal>target</literal>.
+      Both of these are passed to the functions as
+      SCons &Node; objects,
+      which we convert to strings using the Python
+      <function>str()</function>.
+      The third argument, <literal>prev_ni</literal>,
+      is an object that holds the
+      signature or timestamp information
+      that was recorded about the dependency
+      the last time the target was built.
+
+      </para>
+
+      <para>
+
+      Note that ignoring some of the arguments
+      in your custom &Decider; function
+      is a perfectly normal thing to do,
+      if they don't impact the way you want to
+      decide if the dependency file has changed.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Mixing Different Ways of Deciding If a File Has Changed</title>
+
+      <para>
+
+      The previous examples have all demonstrated calling
+      the global &Decider; function
+      to configure all dependency decisions that &SCons; makes.
+      Sometimes, however, you want to be able to configure
+      different decision-making for different targets.
+      When that's necessary, you can use the
+      <function>env.Decider</function>
+      method to affect only the configuration
+      decisions for targets built with a
+      specific construction environment.
+
+      </para>
+
+      <para>
+
+      For example, if we arbitrarily want to build
+      one program using MD5 checkums
+      and another use file modification times
+      from the same source
+      we might configure it this way:
+
+      </para>
+
+      <scons_example name="mixing">
+        <file name="SConstruct" printme="1">
+        env1 = Environment(CPPPATH = ['.'])
+        env2 = env1.Clone()
+        env2.Decider('timestamp-match')
+        env1.Program('prog-MD5', 'program1.c')
+        env2.Program('prog-timestamp', 'program2.c')
+        </file>
+        <file name="program1.c">
+        #include "inc.h"
+        int main() { printf("Hello, world!\n"); }
+        </file>
+        <file name="program2.c">
+        #include "inc.h"
+        int main() { printf("Hello, world!\n"); }
+        </file>
+        <file name="inc.h">
+        #define INC     1
+        </file>
+      </scons_example>
+
+      <para>
+
+      If both of the programs include the same
+      <filename>inc.h</filename> file,
+      then updating the modification time of
+      <filename>inc.h</filename>
+      (using the &touch; command)
+      will cause only <filename>prog-timestamp</filename>
+      to be rebuilt:
+
+      </para>
+
+      <scons_output example="mixing" os="posix">
+         <scons_output_command>scons -Q</scons_output_command>
+         <scons_output_command>touch inc.h</scons_output_command>
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Older Functions for Deciding When an Input File Has Changed</title>
+
+    <para>
+
+    &SCons; still supports two functions that used to be the
+    primary methods for configuring the
+    decision about whether or not an input file has changed.
+    Although they're not officially deprecated yet,
+    their use is discouraged,
+    mainly because they rely on a somewhat
+    confusing distinction between how
+    source files and target files are handled.
+    These functions are documented here mainly in case you
+    encounter them in existing &SConscript; files.
+
+    </para>
+  
+    <section>
+    <title>The &SourceSignatures; Function</title>
+
+      <para>
+
+      The &SourceSignatures; function is fairly straightforward,
+      and supports two different argument values
+      to configure whether source file changes should be decided
+      using MD5 signatures:
+
+      </para>
+
+      <sconstruct>
+        Program('hello.c')
+        SourceSignatures('MD5')
+      </sconstruct>
+
+      <para>
+
+      Or using time stamps:
+
+      </para>
+
+      <sconstruct>
+        Program('hello.c')
+        SourceSignatures('timestamp')
+      </sconstruct>
+
+      <para>
+
+      These are roughly equivalent to specifying
+      <function>Decider('MD5')</function>
+      or
+      <function>Decider('timestamp-match')</function>,
+      respectively,
+      although it only affects how SCons makes
+      decisions about dependencies on
+      <emphasis>source</emphasis> files--that is,
+      files that are not built from any other files.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &TargetSignatures; Function</title>
+
+      <para>
+
+      The &TargetSignatures; function
+      specifies how &SCons; decides
+      when a target file has changed
+      <emphasis>when it is used as a
+      dependency of (input to) another target</emphasis>--that is,
+      the &TargetSignatures; function configures
+      how the signatures of "intermediate" target files
+      are used when deciding if a "downstream" target file
+      must be rebuilt.
+      <footnote><para>
+      This easily-overlooked distinction between
+      how &SCons; decides if the target itself must be rebuilt
+      and how the target is then used to decide if a different
+      target must be rebuilt is one of the confusing
+      things that has led to the &TargetSignatures;
+      and &SourceSignatures; functions being
+      replaced by the simpler &Decider; function.
+      </para></footnote>
+
+      </para>
+
+      <para>
+
+      The &TargetSignatures; function supports the same
+      <literal>'MD5'</literal> and <literal>'timestamp'</literal>
+      argument values that are supported by the &SourceSignatures;,
+      with the same meanings, but applied to target files.
+      That is, in the example:
+
+      </para>
+
+      <sconstruct>
+        Program('hello.c')
+        TargetSignatures('MD5')
+      </sconstruct>
+
+      <para>
+
+      The MD5 checksum of the &hello_o; target file
+      will be used to decide if it has changed since the last
+      time the "downstream" &hello; target file was built.
+      And in the example:
+      
+      </para>
+
+      <sconstruct>
+        Program('hello.c')
+        TargetSignatures('timestamp')
+      </sconstruct>
+
+      <para>
+
+      The modification time of the &hello_o; target file
+      will be used to decide if it has changed since the last
+      time the "downstream" &hello; target file was built.
+
+      </para>
+
+      <para>
+
+      The &TargetSignatures; function supports
+      two additional argument values:
+      <literal>'source'</literal> and <literal>'build'</literal>.
+      The <literal>'source'</literal> argument
+      specifies that decisions involving
+      whether target files have changed
+      since a previous build
+      should use the same behavior
+      for the decisions configured for source files
+      (using the &SourceSignatures; function).
+      So in the example:
+
+      </para>
+
+      <sconstruct>
+        Program('hello.c')
+        TargetSignatures('source')
+        SourceSignatures('timestamp')
+      </sconstruct>
+
+      <para>
+
+      All files, both targets and sources,
+      will use modification times
+      when deciding if an input file
+      has changed since the last
+      time a target was built.
+
+      </para>
+
+      <para>
+
+      Lastly, the <literal>'build'</literal> argument
+      specifies that &SCons; should examine
+      the build status of a target file
+      and always rebuild a "downstream" target
+      if the target file was itself rebuilt,
+      without re-examining the contents or timestamp
+      of the newly-built target file.
+      If the target file was not rebuilt during
+      this &scons; invocation,
+      then the target file will be examined
+      the same way as configured by
+      the &SourceSignature; call
+      to decide if it has changed.
+
+      </para>
+
+      <para>
+
+      This mimics the behavior of
+      <literal>build signatures</literal>
+      in earlier versions of &SCons;.
+      A &buildsignature; re-combined
+      signatures of all the input files
+      that went into making the target file,
+      so that the target file itself
+      did not need to have its contents read
+      to compute an MD5 signature.
+      This can improve performance for some configurations,
+      but is generally not as effective as using
+      <literal>Decider('MD5-timestamp')</literal>.
 
       </para>
 
     <para>
 
     Now suppose that our "Hello, World!" program
-    actually has a <literal>#include</literal> line
+    actually has an <literal>#include</literal> line
     to include the &hello_h; file in the compilation:
 
     </para>
 
-    <scons_example name="ex4">
+    <scons_example name="include">
       <file name="SConstruct">
        Program('hello.c', CPPPATH = '.')
       </file>
 
     </para>
 
-    <scons_example_file example="ex4"  name="hello.h">
+    <scons_example_file example="include"  name="hello.h">
     </scons_example_file>
 
     <para>
 
     </para>
 
-    <scons_example_file example="ex4"  name="SConstruct">
+    <scons_example_file example="include"  name="SConstruct">
     </scons_example_file>
 
     <para>
 
     </para>
 
-    <scons_output example="ex4" os="posix">
+    <scons_output example="include" os="posix">
        <scons_output_command>scons -Q hello</scons_output_command>
        <scons_output_command>scons -Q hello</scons_output_command>
        <scons_output_command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command>
     the &cv-CPPPATH; variable
     may be a list of directories,
     or a string separated by
-    the system-specific path separate character
+    the system-specific path separation character
     (':' on POSIX/Linux, ';' on Windows).
     Either way, &SCons; creates the
     right command-line options
   </section>
 
</