Merged revisions 2302-2362,2364-2452 via svnmerge from

http://scons.tigris.org/svn/scons/branches/core

................
  r2311 | stevenknight | 2007-08-17 07:51:31 -0500 (Fri, 17 Aug 2007) | 2 lines

  Fix the CHECKPOINT= help text.
................
  r2313 | stevenknight | 2007-08-17 13:12:13 -0500 (Fri, 17 Aug 2007) | 2 lines

  Make sure the --debug=time works when -h is specified, too.
................
  r2320 | stevenknight | 2007-08-18 08:54:49 -0500 (Sat, 18 Aug 2007) | 3 lines

  Don't execute any Configure() actions while reading SConscript files
  when -c or -h or -H are specified.
................
  r2321 | stevenknight | 2007-08-20 08:48:57 -0500 (Mon, 20 Aug 2007) | 2 lines

  Cleaner test failure if before-and-after PostScript files don't match.
................
  r2322 | stevenknight | 2007-08-20 11:02:57 -0500 (Mon, 20 Aug 2007) | 2 lines

  Remove function definitions that make some Java versions fail.
................
  r2354 | stevenknight | 2007-08-20 14:26:13 -0500 (Mon, 20 Aug 2007) | 3 lines

  Relax test conditions for two scripts that have differing behavior
  under different versions of Java + SWIG (+ gcc...?).
................
  r2355 | stevenknight | 2007-08-20 14:29:36 -0500 (Mon, 20 Aug 2007) | 2 lines

  Fix the SConstruct file so it doesn't die if Subversion isn't installed.
................
  r2356 | stevenknight | 2007-08-20 22:26:35 -0500 (Mon, 20 Aug 2007) | 3 lines

  Update to latest Test{Cmd,Common}.py, with better avoidance of
  race conditions on temporary file and directory names.
................
  r2373 | stevenknight | 2007-08-27 10:47:21 -0500 (Mon, 27 Aug 2007) | 2 lines

  Windows portability fixes in tests.
................
  r2377 | stevenknight | 2007-08-27 12:33:47 -0500 (Mon, 27 Aug 2007) | 2 lines

  Add a null command list to suppress the baseline build when testing.
................
  r2380 | stevenknight | 2007-08-27 16:33:42 -0500 (Mon, 27 Aug 2007) | 616 lines

  Merged revisions 1503-1543,1545-1546,1548-1558,1560-1562,1564-1886,1888-1909,1911-1941,1943,1945-1955,1957-1960,1962-1963,1965-1999,2001-2019,2021-2037,2039-2061,2063-2067,2069-2146,2148-2150,2152-2156,2158-2199,2201-2208,2210-2212,2214-2238,2240,2242-2288,2290-2291,2293-2305,2307-2364,2366-2373,2375-2377,2379 via svnmerge from
  http://scons.tigris.org/svn/scons/branches/sigrefactor

  ........
    r1550 | stevenknight | 2006-07-27 21:40:08 -0500 (Thu, 27 Jul 2006) | 3 lines

    First cut at storing csig separately in the NodeInfo,
    but still using bsigs for up-to-date checks.
  ........
    r1551 | stevenknight | 2006-07-28 07:07:27 -0500 (Fri, 28 Jul 2006) | 2 lines

    Refactor the use of dictify() to avoid __builtin__ issues with zip on 1.5.
  ........
    r1552 | stevenknight | 2006-07-28 10:05:18 -0500 (Fri, 28 Jul 2006) | 3 lines

    Have msvsTests.py print why it's not executing tests
    when on a non-win32 system.
  ........
    r1553 | stevenknight | 2006-07-28 11:28:37 -0500 (Fri, 28 Jul 2006) | 3 lines

    Refactor when NodeInfo objects get instantiated (when requested
    explicitly, not as a side effect of creating a BuildInfo object).
  ........
    r1554 | stevenknight | 2006-07-28 11:42:53 -0500 (Fri, 28 Jul 2006) | 3 lines

    Refactor test/{Source,Target}Signatures.py to make changing their
    semantics easier.
  ........
    r1555 | stevenknight | 2006-07-28 13:18:35 -0500 (Fri, 28 Jul 2006) | 6 lines

    Eliminate use of build signatures, changing interfaces and semantics
    of SourceSignature() and TargetSignatures(), accordingly.  Make use
    of content signatures the default behavior.  Get rid of most uses
    the Sig/*.py calculator modules and passing around a "calc" argument
    everywhere.
  ........
    r1556 | stevenknight | 2006-07-28 15:14:03 -0500 (Fri, 28 Jul 2006) | 3 lines

    Fix use of CacheDir() with Alias and Value Nodes.
    Refactor sub-tests in test/CacheDir.py into separate test scripts.
  ........
    r1557 | stevenknight | 2006-07-28 21:40:31 -0500 (Fri, 28 Jul 2006) | 2 lines

    Finish the necessary coding to remove the no-longer-needed Sig/*.py modules.
  ........
    r1560 | stevenknight | 2006-07-29 05:52:27 -0500 (Sat, 29 Jul 2006) | 3 lines

    Move current_*() methods for the different flavors of file comparison into
    (e.g.) the Node.FS.File class itself, not its FileNodeInfo class.
  ........
    r1562 | stevenknight | 2006-07-29 08:46:23 -0500 (Sat, 29 Jul 2006) | 2 lines

    Fix the default returned Boolean value of changed_{content,timestamp}().
  ........
    r1564 | stevenknight | 2006-07-29 10:51:24 -0500 (Sat, 29 Jul 2006) | 3 lines

    Fix the --debug=explain option.  Move test/explain.py to
    test/option/debug-explain.py.
  ........
    r1565 | stevenknight | 2006-07-29 16:09:31 -0500 (Sat, 29 Jul 2006) | 2 lines

    Refactor Taskmaster to visit source file Nodes in its walk.
  ........
    r1566 | stevenknight | 2006-07-29 17:50:38 -0500 (Sat, 29 Jul 2006) | 4 lines

    Merge Node.FS._cur2() into Node.FS.is_up_to_date().
    Use a Node.FS.*.make_ready() to handle disambiguation.
    Split the guts of has_src_builder() into a separate find_src_builder() method.
  ........
    r1567 | stevenknight | 2006-07-29 17:55:36 -0500 (Sat, 29 Jul 2006) | 2 lines

    Make the sconsign script print the stored action information.
  ........
    r1568 | stevenknight | 2006-07-29 17:59:03 -0500 (Sat, 29 Jul 2006) | 2 lines

    Refactor for test readability.
  ........
    r1569 | stevenknight | 2006-07-29 20:32:26 -0500 (Sat, 29 Jul 2006) | 2 lines

    Get rid of the now-unnecessary "module" argument to SConsign methods.
  ........
    r1570 | stevenknight | 2006-07-29 22:05:47 -0500 (Sat, 29 Jul 2006) | 3 lines

    Move content signature calcuation to an explicit make_ready()
    function.  Collect NodeInfo field updating in the base class.
  ........
    r1571 | stevenknight | 2006-07-30 06:26:17 -0500 (Sun, 30 Jul 2006) | 2 lines

    Eliminte the no-longer-necessary is_pseudo_derived() method.
  ........
    r1572 | stevenknight | 2006-07-30 07:53:40 -0500 (Sun, 30 Jul 2006) | 2 lines

    Add tgt_sig_type arguments to various changed() methods' calling arguments.
  ........
    r1573 | stevenknight | 2006-07-30 08:17:43 -0500 (Sun, 30 Jul 2006) | 2 lines

    More informative output from test/SideEffect.py when it fails.
  ........
    r1574 | stevenknight | 2006-07-30 09:53:11 -0500 (Sun, 30 Jul 2006) | 3 lines

    Restore the ability to fall back gracefully to timestamps if the running
    version of Python has no md5 module available.
  ........
    r1575 | stevenknight | 2006-08-02 20:21:04 -0500 (Wed, 02 Aug 2006) | 3 lines

    Fix a failing Qt test by calling disambiguate() before make_ready()
    for all of the targets in a list, not just the first.
  ........
    r1646 | stevenknight | 2006-10-17 17:21:58 -0500 (Tue, 17 Oct 2006) | 6 lines

    Move all the scons.org stuff from the scons source tree itself to a
    directory next to the trunk, and delete the copies from the branches.
    There's a lot of stuff there (what with all of the documentation of
    the different versions) and it's ridiculous to make everyone sync it
    just to work on the code.
  ........
    r1888 | stevenknight | 2007-04-17 14:57:47 -0500 (Tue, 17 Apr 2007) | 2 lines

    More efficient/cleaner code for dictifying --debug=explain info.
  ........
    r1889 | stevenknight | 2007-04-17 15:55:00 -0500 (Tue, 17 Apr 2007) | 3 lines

    More efficient taskmaster:  filter the list once for anything that hasn't
    been built, then extract a sub-list of anything that hasn't been visited.
  ........
    r1894 | stevenknight | 2007-04-25 13:07:29 -0500 (Wed, 25 Apr 2007) | 4 lines

    Push conversion of individual NodeInfo objects into the objects themselves
    (instead of having the FileBuildInfo class assume that every dependency
    is a file system Entry of some kind).
  ........
    r1895 | stevenknight | 2007-05-04 23:49:13 -0500 (Fri, 04 May 2007) | 3 lines

    Store content signatures for Aliases so we can really use them
    as dependencies.
  ........
    r1896 | stevenknight | 2007-05-07 16:37:06 -0500 (Mon, 07 May 2007) | 3 lines

    Move the TargetSignatures.py test into a subdirectory, which we can
    populate with other tests (of the new settings, etc.).
  ........
    r1897 | stevenknight | 2007-05-07 17:36:04 -0500 (Mon, 07 May 2007) | 3 lines

    Fix use of TargetSignatures('content') to override settings of
    SourceSignatures('timestamp').
  ........
    r1900 | stevenknight | 2007-05-14 18:48:39 -0500 (Mon, 14 May 2007) | 5 lines

    More specific sconsign signature tests: check for an actual 32-digit-long
    hex string when an MD5 checksum is expected, so we can correctly detect
    test failures if "None" shows up instead.  (This will be used for getting
    avoiding calculating the content signature in 'timestamp' mode.)
  ........
    r1949 | stevenknight | 2007-05-30 22:45:25 -0500 (Wed, 30 May 2007) | 7 lines

    Refactor the get_{csig,timestamp,size}() methods so they use the Memoizer
    pattern, instead of the the NodeInfo object, to cache the results.

    This won't be the final form (we have to reach and stuff a csig value
    in the cache slot to make --implicit-cache work) but it's a step that
    should make it easier to work on other in-progress modifications.
  ........
    r1957 | stevenknight | 2007-06-01 10:18:15 -0500 (Fri, 01 Jun 2007) | 14 lines

    Shift updating a Node's signature/timestamp/size information until after
    the Node has been built (or visited, if it's a leaf Node).  This therefore
    changes the semantics of the .visited() method, so that it's called for
    *every* Node visited, not just leaf Nodes.

    This adds a Taskmaster method for updating a Node's status without
    calling the .built() and .visited() methods, which is used by the
    CleanTask subclass to avoid writing .sconsign info when cleaning (-c).

    Interesting ripple effect in the SConf.py module:  we have to manually
    override the .store_info() method on the Nodes we create, so that they
    don't write out their normal .sconsign information.  The SConf subsystem
    writes out its own by hand.
  ........
    r1962 | stevenknight | 2007-06-01 13:12:24 -0500 (Fri, 01 Jun 2007) | 5 lines

    Fix the ability to catch {IO,OS}Errors during build preparation and
    display the actual Node that triggered the error.  (Which Node actually
    triggers this case, and therefore the displayed error message, changed
    after we delayed content evaluation until *after* a Node is built.)
  ........
    r1975 | stevenknight | 2007-06-04 15:21:09 -0500 (Mon, 04 Jun 2007) | 3 lines

    Small refactoring:  use {new,get}_ninfo() instead of instantiating
    self.NodeInfo() directly.
  ........
    r1976 | stevenknight | 2007-06-04 16:14:12 -0500 (Mon, 04 Jun 2007) | 5 lines

    Similar to the previous change, call new_binfo() instead of instantiating
    the BuildInfo() type directly.  Change new_binfo() so it doesn't
    automatically attach a NodeInfo object (because sometimes we want the
    existing NodeInfo, and sometimes we want a completely new one).
  ........
    r1977 | stevenknight | 2007-06-04 16:35:44 -0500 (Mon, 04 Jun 2007) | 3 lines

    The body of DirFile.write() was all indented underneath a "if self.dirty:"
    block.  Invert the test and outdent the body.
  ........
    r1978 | stevenknight | 2007-06-04 16:52:14 -0500 (Mon, 04 Jun 2007) | 2 lines

    Memoize the stored information we get from the .sconsign file.
  ........
    r1979 | stevenknight | 2007-06-05 14:17:32 -0500 (Tue, 05 Jun 2007) | 6 lines

    Delay merging a Node's build information into the .sconsign entry until
    the entry is being written out.  This will allow us to include information
    (such as a content signature) that gets fetched for the first time *after*
    a Node is built.  (The code here isn't the prettiest at the moment, but
    this checkpoints an implementation that passes all the tests.)
  ........
    r1980 | stevenknight | 2007-06-06 10:06:56 -0500 (Wed, 06 Jun 2007) | 4 lines

    Refactor to have the store_info() method pull the binfo from
    the Node (instead of having the Node passing it in).
    Add a do_not_store_info() method to override the behavior.
  ........
    r1981 | stevenknight | 2007-06-06 11:18:29 -0500 (Wed, 06 Jun 2007) | 3 lines

    Refactor the unit test invocation so we can run multiple test
    methods from each class.
  ........
    r1982 | stevenknight | 2007-06-06 11:48:00 -0500 (Wed, 06 Jun 2007) | 7 lines

    Move responsibility for merging buildinfo entries from Node.FS to the
    SConsign module, through a new Base.store_info() method.  Return the
    existing Base.set_entry() method to actually setting the entry, and use
    the new Base.store_info() method for things that need delayed storage
    and merging.  Adds some commented-out prototype code for delaying
    the buildinfo entry merge until later.
  ........
    r1983 | stevenknight | 2007-06-06 22:57:14 -0500 (Wed, 06 Jun 2007) | 4 lines

    Better testing for parallel-build exceptions:  re-order the file names
    so that the input files are evaluated before the output files, increasing
    the likelihood of all three being built by simultaneous threads.
  ........
    r1984 | stevenknight | 2007-06-06 22:57:55 -0500 (Wed, 06 Jun 2007) | 2 lines

    Have Trace() flush after write so interleaving stays correct.
  ........
    r1985 | stevenknight | 2007-06-06 23:01:23 -0500 (Wed, 06 Jun 2007) | 11 lines

    Pull the NodeInfo objects out of the BuildInfo object and just deal
    with them as co-equal attributes of a Node.

    .sconsign files now have a place-holder SConsignEntry class that holds a
    Node's separate binfo and ninfo objects.  This will also be more flexible
    if we ever add more information in the future.

    Since this changes the format (but not content) of the .sconsign file
    entries, we will need to double back and figure out how to make the
    transition from pre-BSR .sconsign files before this goes live.
  ........
    r1986 | stevenknight | 2007-06-07 00:08:21 -0500 (Thu, 07 Jun 2007) | 2 lines

    Store the computed csig in the NodeInfo structure.
  ........
    r1987 | stevenknight | 2007-06-07 18:59:31 -0500 (Thu, 07 Jun 2007) | 12 lines

    Track the content signature directly in the NodeInfo object, not in the
    _memo dictionary.

    Wipe out the existing NodeInfo after the Node has
    been built so the content signature gets recalculated correctly.

    Change the NodeInfoBase.update() method so that the default behavior is
    to always update the specified fields, not just ones that exist.  This
    was necessary to get Alias and Value Nodes to work with this.

    Remove left-over comments.
  ........
    r1988 | stevenknight | 2007-06-08 17:09:24 -0500 (Fri, 08 Jun 2007) | 5 lines

    Invert the logic (is_up_to_date => changed) when gathering Configure
    Node states, and eliminate (most) Boolean logic that short-circuits
    some of the tests.  (This area isn't critical, so making sure the code
    is readable is more important than pure performance.)
  ........
    r1990 | stevenknight | 2007-06-09 17:14:32 -0500 (Sat, 09 Jun 2007) | 7 lines

    Refactor the Node.changed() method so it always evaluates every
    dependency, instead of returning early as soon as it finds a difference
    (like a different number of old and new dependencies).  This will be
    necessary to delay evaluation of Node information (content signatures)
    until it's actually needed (instead of evaluating it up front in case
    it's needed later).
  ........
    r2001 | stevenknight | 2007-06-11 11:20:29 -0500 (Mon, 11 Jun 2007) | 3 lines

    Use SCons.compat in the refactored SConsign.py so use of True/False/etc.
    works on Python 1.5 and 2.1.
  ........
    r2002 | stevenknight | 2007-06-11 11:57:56 -0500 (Mon, 11 Jun 2007) | 3 lines

    Have the "sconsign" script handle Configure context .sconsign information,
    which comes from different structures that have no NodeInfo objects.
  ........
    r2003 | stevenknight | 2007-06-11 15:08:52 -0500 (Mon, 11 Jun 2007) | 8 lines

    Avoid generating content signatures unless they're actually used:

    Don't automatically create a content signature after a File Node is
    built/visited, and delay the .sconsign merge of the information until
    just before the information will be written.  This means we'll only write
    out information that's actually fetched and used as part of deciding
    whether or not to rebuild any targets.
  ........
    r2004 | stevenknight | 2007-06-13 00:05:52 -0500 (Wed, 13 Jun 2007) | 4 lines

    Fetch the {Source,Target}Signatures() values inside the
    Node.FS.changed_since_last_build() method, not in Node.Node.changed().
    This is slightly less efficient, but cleaner architecturally.
  ........
    r2005 | stevenknight | 2007-06-13 10:18:17 -0500 (Wed, 13 Jun 2007) | 6 lines

    Use zip() to collect the children and previous signatures info more
    efficiently when deciding if a node must be rebuilt.  (The comment in
    the previous version of the source code about not using zip() because
    of Python 1.5 name space problems was due to the way the SConfTests.py
    module tried to reset the world's state.)
  ........
    r2006 | stevenknight | 2007-06-13 10:59:16 -0500 (Wed, 13 Jun 2007) | 4 lines

    Add a NotImplementedError base class implementation of
    changed_since_last_build(), with doc string commentary about why the
    method is called through the dependency Node, not the target Node.
  ........
    r2019 | stevenknight | 2007-06-18 12:26:06 -0500 (Mon, 18 Jun 2007) | 4 lines

    Remove the unnecessary cut-and-paste "import SCons.Action" in the
    changed_since_last_build() method, which was a left-over cut and paste.
    SCons.Action was already imported up top.
  ........
    r2021 | stevenknight | 2007-06-18 18:31:09 -0500 (Mon, 18 Jun 2007) | 2 lines

    Make sure all "is up to date" messages get printed when -j is used.
  ........
    r2022 | stevenknight | 2007-06-19 16:26:22 -0500 (Tue, 19 Jun 2007) | 3 lines

    Refactor the __checkClass() and must_be_a_Dir() methods into a more
    general and more efficient must_be_same() method.
  ........
    r2024 | stevenknight | 2007-06-19 19:16:09 -0500 (Tue, 19 Jun 2007) | 3 lines

    More clean up:  change various self.fs.Entry() calls to calls through
    the bound directory.Entry() method.
  ........
    r2026 | stevenknight | 2007-06-19 22:10:04 -0500 (Tue, 19 Jun 2007) | 10 lines

    Refactor lookup of Node.FS nodes as follows:
    * Completely get rid of _doLookup(), which was old, complicated code
      that implemented a top-down, entry-by-entry search for path names.
    * Use a new FS._lookup() method, which normalizes names to absolute
      paths, with a new RootDir._lookup_abs() method, which handles the
      actual lookup.  We plan to use the latter method for fast(er) internal
      lookups of already-normalized paths.
    * Create a new separate FS.get_root() method, just to avoid clutter
      in the RootDir._lookup_abs() method.
  ........
    r2027 | stevenknight | 2007-06-20 13:29:19 -0500 (Wed, 20 Jun 2007) | 3 lines

    Remove the debug-explain.py test from sigrefactor, branches/core
    split this up into multiple sub-tests.
  ........
    r2028 | stevenknight | 2007-06-20 13:38:28 -0500 (Wed, 20 Jun 2007) | 2 lines

    Handle a line-ending mismatch on Windows.
  ........
    r2029 | stevenknight | 2007-06-20 13:39:05 -0500 (Wed, 20 Jun 2007) | 2 lines

    Support the ability to -d when path names have Windows \ separators.
  ........
    r2030 | stevenknight | 2007-06-20 13:55:11 -0500 (Wed, 20 Jun 2007) | 2 lines

    Windows portability:  TestSConsign._obj instead of a hard-coded '.o' suffix.
  ........
    r2031 | stevenknight | 2007-06-20 15:30:06 -0500 (Wed, 20 Jun 2007) | 2 lines

    Python 1.5 namespace portability.
  ........
    r2032 | stevenknight | 2007-06-20 16:38:28 -0500 (Wed, 20 Jun 2007) | 2 lines

    Fix tests affected by the -d fix for runtest.py.
  ........
    r2039 | stevenknight | 2007-06-21 12:17:06 -0500 (Thu, 21 Jun 2007) | 2 lines

    Ignore *.pyo files, too, now that one of the tests causes us to generate them.
  ........
    r2041 | stevenknight | 2007-06-21 12:36:30 -0500 (Thu, 21 Jun 2007) | 7 lines

    In the .sconsign file, store the paths to all of the dependencies relative
    to the top-level SConstruct directory, not the target's directory.
    This allows us to be much more efficient when writing the .sconsign file
    (since we can just store the already-computed path) and reading the
    .sconsign file (since we can use the quick, normalized-lookup method to
    translate the string into the correct Node).
  ........
    r2042 | stevenknight | 2007-06-22 13:25:26 -0500 (Fri, 22 Jun 2007) | 2 lines

    Remove left-over debug code (instrumenting os.path.normpath()).
  ........
    r2043 | stevenknight | 2007-06-22 13:28:35 -0500 (Fri, 22 Jun 2007) | 8 lines

    Actually use the new Dir._lookup_abs() method for fast .sconsign lookups
    relative to the top-level SConstruct directory and make it work correctly.
    (I had commented out the call to binfo.prepare_dependencies() and
    forgot to un-comment it.)  This simplifies things by getting rid of the
    target node we attached to a BuildInfo (purely so we could do relative
    path lookups) and the corresponding conversions into and out of the
    .sconsign file.
  ........
    r2044 | stevenknight | 2007-06-22 19:31:00 -0500 (Fri, 22 Jun 2007) | 5 lines

    Delay fetching the {Source,Target}Signature() values from an environment
    until they're actually needed.  (If the performance here is "close
    enough", then we may not have to look at more complicated loop-invariant
    schemes.)
  ........
    r2045 | stevenknight | 2007-06-22 22:06:19 -0500 (Fri, 22 Jun 2007) | 4 lines

    Replace the Environment.our_deepcopy() function with a
    Util.semi_deepcopy() function, rewritten to use the more efficient
    dispatch-table approach that the normal Python copy.py module uses.
  ........
    r2050 | stevenknight | 2007-06-24 23:49:06 -0500 (Sun, 24 Jun 2007) | 5 lines

    Make the latest signature refactoring portable to Windows, and between
    platforms, by always storing the dependency paths with POSIX separators.
    Handle multiple drive letters by tracking a separate "labspath" attribute
    for the lookup path relative to the root directory's drive letter.
  ........
    r2065 | stevenknight | 2007-06-27 11:02:48 -0500 (Wed, 27 Jun 2007) | 2 lines

    Branch files that were left out of the last merge.
  ........
    r2066 | stevenknight | 2007-06-27 11:03:05 -0500 (Wed, 27 Jun 2007) | 2 lines

    Branch files that were left out of the last merge.
  ........
    r2067 | stevenknight | 2007-06-27 11:03:24 -0500 (Wed, 27 Jun 2007) | 2 lines

    Branch files that were left out of the last merge.
  ........
    r2069 | stevenknight | 2007-06-27 19:08:50 -0500 (Wed, 27 Jun 2007) | 2 lines

    Remove an unnecessary target.has_builder() call in changed_since_last_build().
  ........
    r2070 | stevenknight | 2007-06-27 19:25:47 -0500 (Wed, 27 Jun 2007) | 3 lines

    Refactor changed_since_last_build() to avoid code duplication and simplify
    (?) the structure--probably negligible performance impact.
  ........
    r2071 | stevenknight | 2007-06-29 16:21:37 -0500 (Fri, 29 Jun 2007) | 3 lines

    Add the Decider() function, globally, and settable per construction
    environment or per Node.  This hasn't yet been optimized.
  ........
    r2072 | stevenknight | 2007-06-29 18:01:53 -0500 (Fri, 29 Jun 2007) | 2 lines

    Memoize Executor.get_build_env().
  ........
    r2073 | stevenknight | 2007-06-30 01:04:43 -0500 (Sat, 30 Jun 2007) | 5 lines

    Constructing a dictionary to map signature types ('build', 'MD5', etc.)
    to a dependency's methods ends up being less efficient than just using
    a series of if-elif statements.  Refactor the default_decider_function()
    accordingly.
  ........
    r2074 | stevenknight | 2007-07-01 08:59:35 -0500 (Sun, 01 Jul 2007) | 4 lines

    Now that the objects returned by Node.FS.get_stored_implicit() already
    convert the .sconsign strings to Nodes, don't have the --implicit-cache
    loop run them through the source_factory method.
  ........
    r2075 | stevenknight | 2007-07-02 09:46:21 -0500 (Mon, 02 Jul 2007) | 4 lines

    Eliminate an if-test for the intialized default construction environment
    for internal calls of SCons.Defaults.DefaultEnvironment(), and some
    external calls as well.
  ........
    r2076 | stevenknight | 2007-07-02 10:17:58 -0500 (Mon, 02 Jul 2007) | 3 lines

    More efficient use of the changed_since_last_build() method from
    the default construction environment.
  ........
    r2077 | stevenknight | 2007-07-02 12:26:34 -0500 (Mon, 02 Jul 2007) | 6 lines

    Move the decision about whether a given dependent Node has a Builder
    or not back to when the Builder is actually set, by splitting the
    decision path in two;  one for sources and one for targets.  (Setting a
    construction environment's decider sets both of them, which may or may
    not be what we want in the long term.))
  ........
    r2079 | stevenknight | 2007-07-02 13:14:40 -0500 (Mon, 02 Jul 2007) | 4 lines

    Now explicity set the source decider function for a construction
    environment when the SourceSignatures() method is called, avoiding
    the delayed-evaluation tests.
  ........
    r2081 | stevenknight | 2007-07-02 13:55:58 -0500 (Mon, 02 Jul 2007) | 6 lines

    And now explicity set the target decider function for a construction
    environment when the TargetSignatures() method is called, avoiding even
    more delayed-evaluation tests.

    This also renames the cslb_*() functions to decide_*().
  ........
    r2084 | stevenknight | 2007-07-03 07:13:38 -0500 (Tue, 03 Jul 2007) | 3 lines

    Memoize the Node.get_build_env() value, too, since we're now callng
    that repeatedly.
  ........
    r2085 | stevenknight | 2007-07-03 09:50:25 -0500 (Tue, 03 Jul 2007) | 5 lines

    Get rid of the str_to_nodes() function within the
    FileBuildInfo.prepare_dependencies() method that checks for Alias lookups,
    in favor of a loop that uses new str_to_nodes() methods in the individual
    *NodeInfo classes to convert the strings to Nodes more directly.
  ........
    r2086 | stevenknight | 2007-07-03 10:07:04 -0500 (Tue, 03 Jul 2007) | 3 lines

    Format the FileBuildInfo entries by zipping the children and their
    NodeInfo signatures, not by fetching each one by index.
  ........
    r2089 | stevenknight | 2007-07-03 20:20:15 -0500 (Tue, 03 Jul 2007) | 4 lines

    Remove the _add_child() checks that verify that the argument is a list
    and contains all Nodes.  It's internal, so any necessary verification
    can happen in the methods that call it.
  ........
    r2101 | stevenknight | 2007-07-08 16:13:56 -0500 (Sun, 08 Jul 2007) | 3 lines

    Add string aliases for the canned Decider functions we'll support out of the
    box:  timestamp-match (a.k.a. make), timestamp-newer, MD5 (a.k.a.  content).
  ........
    r2115 | stevenknight | 2007-07-10 21:00:14 -0500 (Tue, 10 Jul 2007) | 2 lines

    Refactor test/option-q.py into two separate subtests.
  ........
    r2144 | stevenknight | 2007-07-16 01:04:25 -0500 (Mon, 16 Jul 2007) | 3 lines

    Fix -q exiting with a non-zero exit status when a file with no builder
    is specified on the command line.
  ........
    r2314 | stevenknight | 2007-08-17 13:46:27 -0500 (Fri, 17 Aug 2007) | 3 lines

    Capture a test case to make sure get_csig() can be called from
    within a function Action.  (Damyan Pepper)
  ........
    r2315 | stevenknight | 2007-08-17 15:05:54 -0500 (Fri, 17 Aug 2007) | 3 lines

    Uncomment the test for content signatures with directories as sources,
    which the signature refactoring makes work.
  ........
    r2316 | stevenknight | 2007-08-17 16:33:25 -0500 (Fri, 17 Aug 2007) | 2 lines

    Make sure that CacheDir() works even when timestamp signatures are used.
  ........
    r2317 | stevenknight | 2007-08-17 16:51:02 -0500 (Fri, 17 Aug 2007) | 2 lines

    Change line endings from DOS to UNIX.
  ........
    r2318 | stevenknight | 2007-08-18 07:13:09 -0500 (Sat, 18 Aug 2007) | 4 lines

    Add a new MD5-timestamp decider function that assumes that if the
    timestamp hasn't changed, then the content hasn't changed either, and
    it should then just re-use the content signature from the last run.
  ........
    r2319 | stevenknight | 2007-08-18 07:41:59 -0500 (Sat, 18 Aug 2007) | 3 lines

    Add a test script to verify that action changes cause rebuilds even
    when file decisions are configured for timestamps.
  ........
    r2360 | stevenknight | 2007-08-23 08:07:16 -0500 (Thu, 23 Aug 2007) | 2 lines

    Fix the test by resetting the content3.in file to the correct timestamp.
  ........
    r2361 | stevenknight | 2007-08-23 12:02:04 -0500 (Thu, 23 Aug 2007) | 3 lines

    Use the new hashlib module for our MD5 signature calculations, with the
    introduction of a compatibility module for pre-2.5 Python versions.
  ........
    r2362 | stevenknight | 2007-08-23 14:02:56 -0500 (Thu, 23 Aug 2007) | 2 lines

    Make targets implicitly depend on the commands used to build them.
  ........
    r2364 | stevenknight | 2007-08-24 00:07:46 -0500 (Fri, 24 Aug 2007) | 2 lines

    Add code to convert what we can from the old .sconsign file entries.
  ........
    r2366 | stevenknight | 2007-08-24 19:40:09 -0500 (Fri, 24 Aug 2007) | 2 lines

    Add a $IMPLICIT_COMMAND_DEPENDENCIES variable.
  ........
    r2367 | stevenknight | 2007-08-24 19:43:58 -0500 (Fri, 24 Aug 2007) | 2 lines

    Add mention of $IMPLICIT_COMMAND_DEPENDENCIES to the release notes.
  ........
    r2375 | stevenknight | 2007-08-27 11:43:04 -0500 (Mon, 27 Aug 2007) | 2 lines

    Windows portability fixes in tests.
  ........
    r2376 | stevenknight | 2007-08-27 12:19:52 -0500 (Mon, 27 Aug 2007) | 2 lines

    Use string.join() instead of a more modern string object method.
  ........
    r2379 | stevenknight | 2007-08-27 12:40:02 -0500 (Mon, 27 Aug 2007) | 3 lines

    Add version ID's to the classes stored in a .sconsign file, for easier
    future conversion as we change schemas.
  ........
................
  r2390 | stevenknight | 2007-08-27 17:32:00 -0500 (Mon, 27 Aug 2007) | 4 lines

  Remove the old TargetSignatures.py test, which was
  overlooked in the merge.  (Its functionality got moved to
  test/TargetSignatures/build-content.py.)
................
  r2391 | stevenknight | 2007-08-28 10:47:15 -0500 (Tue, 28 Aug 2007) | 2 lines

  Don't die if an old .sconsign entry has no .ninfo attribute.
................
  r2392 | stevenknight | 2007-08-28 15:52:56 -0500 (Tue, 28 Aug 2007) | 2 lines

  Fix an O(N^2) search in Tool.install.add_targets_to_INSTALLED_FILES().
................
  r2393 | stevenknight | 2007-08-28 21:28:30 -0500 (Tue, 28 Aug 2007) | 2 lines

  Add support for an ensure_suffix Builder keyword argument.
................
  r2394 | stevenknight | 2007-08-28 21:37:04 -0500 (Tue, 28 Aug 2007) | 3 lines

  Separate the failure tests when trying to connect to an X server,
  so we can tell why it's failing...
................
  r2395 | stevenknight | 2007-08-29 11:46:34 -0500 (Wed, 29 Aug 2007) | 3 lines

  Look for a raw exit status of 1, or the shifted exit status, so we're
  not dependent on how the test infrastructure hands it to us.
................
  r2396 | stevenknight | 2007-08-29 18:12:39 -0500 (Wed, 29 Aug 2007) | 2 lines

  Disable universal_newlines when calling subprocess.
................
  r2397 | stevenknight | 2007-08-29 18:13:29 -0500 (Wed, 29 Aug 2007) | 3 lines

  Add a Progress() hook to support display of per-Node progress while
  walking the DAG.
................
  r2398 | stevenknight | 2007-08-29 19:43:12 -0500 (Wed, 29 Aug 2007) | 7 lines

  Add a test case (courtesy Greg Noel) to characterize how we handle
  mid-build changes to implicit dependency files (we currently don't detect
  the change and rebuild all dependents).

  Move two other test scripts related to implicit dependency behavior
  into a common subdirectory.
................
  r2399 | stevenknight | 2007-08-30 10:32:50 -0500 (Thu, 30 Aug 2007) | 4 lines

  Add a $JAVABOOTCLASSPATH variable.
  Commonize $JAVA*PATH expansion with a utility class.
  (Greg Ward)
................
  r2400 | stevenknight | 2007-08-30 10:59:56 -0500 (Thu, 30 Aug 2007) | 3 lines

  Make sure extra auxiliary files generated by LaTeX packages are deleted
  by scons -c.  (Matthias Troffaes)
................
  r2401 | stevenknight | 2007-08-30 18:43:24 -0500 (Thu, 30 Aug 2007) | 3 lines

  Issue 1589:  when Cloning a construction environment, apply set variables
  both before and after calling tools (like during intialization).
................
  r2402 | stevenknight | 2007-08-30 18:52:02 -0500 (Thu, 30 Aug 2007) | 3 lines

  Issue 1555:  add Windows64 support for the Intel C compiler.
  (Gary Oberbrunner)
................
  r2403 | stevenknight | 2007-08-30 19:57:24 -0500 (Thu, 30 Aug 2007) | 4 lines

  Issue 1493:  have ParseConfig(), MergeFlags() and ParseFlags() handle
  output from *-config commands with quoted arguments (path names that
  contain spaces).
................
  r2410 | stevenknight | 2007-09-04 00:28:46 -0500 (Tue, 04 Sep 2007) | 4 lines

  Add a shlex.split() compatability wrapper for pre-Python 2.3 versions.
  Unfortunately, it doesn't behave exactly like later versions (it doesn't
  detect mid-token quotes), but we're not going to worry about that.
................
  r2411 | stevenknight | 2007-09-04 12:56:36 -0500 (Tue, 04 Sep 2007) | 3 lines

  Add a Sig.py module that generates a warning if user code tries to
  "import SCons.Sig" directly.
................
  r2412 | stevenknight | 2007-09-04 20:53:09 -0500 (Tue, 04 Sep 2007) | 3 lines

  Make the Return() function return immediately.  Add a stop= keyword
  argument in case anyone really needs the old behavior.
................
  r2413 | stevenknight | 2007-09-05 10:38:40 -0500 (Wed, 05 Sep 2007) | 4 lines

  Refactor initialization of different pieces (the underlying
  InstallBuilder, the Install() and InstallAs() wrappers) into separate
  blocks.
................
  r2414 | stevenknight | 2007-09-05 11:39:25 -0500 (Wed, 05 Sep 2007) | 4 lines

  Move the definitions of the wrapper functions to the global namespace
  (nesting them and delaying intialization of global variables doesn't
  save anything and just complicates reading the code).
................
  r2415 | stevenknight | 2007-09-05 13:31:27 -0500 (Wed, 05 Sep 2007) | 3 lines

  When Cloning a construction environment, re-bind any methods added by
  the AddMethod() method to the new construction environment.
................
  r2416 | stevenknight | 2007-09-06 10:04:18 -0500 (Thu, 06 Sep 2007) | 7 lines

  Add a MethodWrapper class that handles generic association of a
  callable and an object that wants to use the callable as a "method."
  Provide hooks for centralized cloning of the different "methods" on to
  a new, copied underlying environment (used by the env.Clone() method).
  Make BuilderWrapper a subclass of MethodWrapper.  Modify env.Clone()
  for the new, combined way of handling these "methods."
................
  r2417 | stevenknight | 2007-09-06 14:11:35 -0500 (Thu, 06 Sep 2007) | 2 lines

  Refactor test failure conditions to use test.must_match().
................
  r2418 | stevenknight | 2007-09-06 14:28:52 -0500 (Thu, 06 Sep 2007) | 9 lines

  Restore the ability to use the Install() and InstallAs() builders without
  having to specify the 'install' tool directly.
  Add a ToolInitializer class that handles delayed intialization of tool
  modules when added to a construction environment as a "method."
  Add an env.RemoveModule() method that takes care of removing an added
  MethodWrapper instance from the environment, deleting it from the
  list that gets copied on cloning (and changing the name of that list
  back to "added_methods").
................
  r2419 | stevenknight | 2007-09-07 06:27:33 -0500 (Fri, 07 Sep 2007) | 3 lines

  Issue 1725:  avoid race conditions when pushing a file to CacheDir().
  (Carsten Koch)
................
  r2420 | pscholl | 2007-09-07 09:13:28 -0500 (Fri, 07 Sep 2007) | 7 lines

   * delete the push_emitter() function. Direct manipulation of the source and
     target lists seem the way to go for packaging. Fix all packagers using this
     function.

   * fix the internationalization testcase
................
  r2421 | pscholl | 2007-09-07 09:14:12 -0500 (Fri, 07 Sep 2007) | 3 lines

   * new testcase for building multiple rpm packages from one scons call.
................
  r2422 | stevenknight | 2007-09-07 14:12:22 -0500 (Fri, 07 Sep 2007) | 4 lines

  Capture a test script with a particular reported test case for multiple
  Package() calls spread across different SConscript subdirectories.
  (Use case courtesy Andrew Smith.)
................
  r2423 | stevenknight | 2007-09-07 17:40:25 -0500 (Fri, 07 Sep 2007) | 4 lines

  Fix use of exitstatfunc on Action objects by getting rid of the ability
  to override exitstatfunc when calling a function (which we were only using
  internally to basically suppress whatever was set on the Action object).
................
  r2424 | stevenknight | 2007-09-10 20:06:59 -0500 (Mon, 10 Sep 2007) | 3 lines

  Make sure the library dependencies show up in --tree=derived output.
  (The Microsoft toolchain used to fail this on SCons 0.97 and earlier.)
................
  r2425 | stevenknight | 2007-09-10 22:25:27 -0500 (Mon, 10 Sep 2007) | 5 lines

  When adding a new entry to a directory, reset the .implicit attribute to
  None so that the directory will get "re-scanned" for implicit dependencies
  (the entries within the directory) if it gets re-visited later in the
  DAG walk.
................
  r2426 | stevenknight | 2007-09-12 12:38:05 -0500 (Wed, 12 Sep 2007) | 2 lines

  String method fix for Python 1.5.2.
................
  r2427 | stevenknight | 2007-09-12 12:38:29 -0500 (Wed, 12 Sep 2007) | 2 lines

  Remove left-over commented-out Trace() call.
................
  r2428 | stevenknight | 2007-09-13 01:36:34 -0500 (Thu, 13 Sep 2007) | 2 lines

  Handle Java inner class names with $ in them.  (Tzvetan Mikov)
................
  r2429 | stevenknight | 2007-09-13 14:29:09 -0500 (Thu, 13 Sep 2007) | 2 lines

  Add a check that should (possibly) avoid import errors on Solaris.
................
  r2430 | stevenknight | 2007-09-13 14:30:36 -0500 (Thu, 13 Sep 2007) | 5 lines

  Windows portability fixes for Progress() tests, restoring the original
  universal_newlines setting on the test infrastructure, changing file
  names to make the order in which Nodes are visited case-insensitive, and
  fixing line endings on output we expect to read from files.
................
  r2431 | stevenknight | 2007-09-14 07:58:44 -0500 (Fri, 14 Sep 2007) | 2 lines

  Make sure all function examples are introduced by "Example:" or "Examples:".
................
  r2432 | stevenknight | 2007-09-14 11:35:03 -0500 (Fri, 14 Sep 2007) | 3 lines

  Clean up Options files initialization so we don't have to check on usage
  for whether it's been set.
................
  r2433 | stevenknight | 2007-09-14 23:12:32 -0500 (Fri, 14 Sep 2007) | 4 lines

  Fix use of {Source,Target}Signatures() with construction variable
  overrides by making the default decider_*() things unbound functions,
  instead of bound methods.
................
  r2434 | stevenknight | 2007-09-14 23:14:25 -0500 (Fri, 14 Sep 2007) | 2 lines

  Don't use "True" in the test infrastructure, use 1 instead.
................
  r2435 | stevenknight | 2007-09-15 00:52:56 -0500 (Sat, 15 Sep 2007) | 2 lines

  Avoid use of False in two tests.
................
  r2436 | pscholl | 2007-09-17 08:14:35 -0500 (Mon, 17 Sep 2007) | 21 lines

   * additional testcase for packaging:
      * building multiple packages from one scons call
      * supplying explicit target names for msi and rpm
      * test the Find*Files() functions

   * modify the package-type option test to not only catch
     the PACKAGETYPE, but also the --package-type alias
     command line argument

   * move FindInstalledFiles to Environment.py and remove
     Find*Files() functions from the packaging module.

   * capitalize the VENDOR tag for msi

   * remove the superfluous packager.py files

   * Add documentation for FindInstalledFiles() and
     FindSourceFiles()
................
  r2437 | stevenknight | 2007-09-17 11:06:28 -0500 (Mon, 17 Sep 2007) | 2 lines

  Provide compatibility for the variables defined in SCons.Sig.
................
  r2438 | stevenknight | 2007-09-17 23:13:27 -0500 (Mon, 17 Sep 2007) | 5 lines

  Handle duplicate fies in a target list:  only decrement the reference
  count once for the target, not once for each time it shows up in the
  list, so dependencies don't "disappear" from the DAG walk because the
  reference count gets decremented past zero.
................
  r2439 | stevenknight | 2007-09-17 23:15:45 -0500 (Mon, 17 Sep 2007) | 2 lines

  Fix syntax errors from failure to quote the package type.
................
  r2440 | stevenknight | 2007-09-17 23:21:20 -0500 (Mon, 17 Sep 2007) | 2 lines

  Use AddOption() to support the --package-type option.
................
  r2441 | stevenknight | 2007-09-17 23:31:40 -0500 (Mon, 17 Sep 2007) | 2 lines

  Skip the test if tar isn't available.
................
  r2442 | stevenknight | 2007-09-18 06:35:04 -0500 (Tue, 18 Sep 2007) | 2 lines

  Remove Tool/packaging/packager.py from the manifest.
................
  r2443 | garyo | 2007-09-18 08:13:15 -0500 (Tue, 18 Sep 2007) | 1 line

  SGI IRIX: use proper C++ compiler for SHCXX, don't hardcode CC.
................
  r2444 | garyo | 2007-09-18 08:17:03 -0500 (Tue, 18 Sep 2007) | 1 line

  Avoid running MinGW tests on IRIX; they're irrelevant there and they fail anyway (they seem to pass on Linux, so left them in there.)
................
  r2445 | garyo | 2007-09-18 08:20:52 -0500 (Tue, 18 Sep 2007) | 1 line

  Fixed wrong return type in test code; caused warnings on IRIX which made test fail.
................
  r2446 | stevenknight | 2007-09-18 11:21:53 -0500 (Tue, 18 Sep 2007) | 2 lines

  Record Gary's change to the sgic++ tool.
................
  r2451 | stevenknight | 2007-09-19 00:01:46 -0500 (Wed, 19 Sep 2007) | 2 lines

  Windows portability fix (when checking for path names in output).
................
  r2452 | stevenknight | 2007-09-19 00:08:23 -0500 (Wed, 19 Sep 2007) | 2 lines

  Handle the ImportError if there's no threading module on Windows.
................

2 files changed, 677 insertions, 54 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index a20a0f6..6f87b20 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -2013,6 +2013,8 @@ specified
 .I function
 itself is used for the method name.
 
+Examples:
+
 .ES
 # Note that the first argument to the function to
 # be attached as a method must be the object through
@@ -2192,6 +2194,8 @@ can be called multiple times for the same
 alias to add additional targets to the alias,
 or additional actions to the list for this alias.
 
+Examples:
+
 .ES
 Alias('install')
 Alias('install', '/usr/bin')
@@ -2225,6 +2229,7 @@ If
 is called multiple times,
 each call completely overwrites the previous list
 of allowed exceptions.
+
 Example:
 
 .ES
@@ -2276,6 +2281,8 @@ are both coerced to lists,
 and the lists are added together.
 (See also the Prepend method, below.)
 
+Example:
+
 .ES
 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
 .EE
@@ -2298,6 +2305,7 @@ and
 This can also handle the
 case where the given old path variable is a list instead of a
 string, in which case a list will be returned instead of a string.
+
 Example:
 
 .ES
@@ -2325,6 +2333,8 @@ construction variable will
 .I not
 be added again to the list.
 
+Example:
+
 .ES
 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
 .EE
@@ -2341,6 +2351,8 @@ is intended to be passed to the
 .B SourceCode
 function.
 
+Example:
+
 .ES
 env.SourceCode('.', env.BitKeeper())
 .EE
@@ -2666,6 +2678,7 @@ or by a
 .B \-
 (hyphen)
 to ignore the exit status of the external command.
+
 Examples:
 
 .ES
@@ -2700,7 +2713,9 @@ by using the
 .BR Dir ()
 or
 .BR env.Dir ()
-functions:
+functions.
+
+Examples:
 
 .ES
 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
@@ -2733,6 +2748,8 @@ they are added to the returned copy,
 overwriting any existing values
 for the keywords.
 
+Example:
+
 .ES
 env2 = env.Clone()
 env3 = env.Clone(CCFLAGS = '-g')
@@ -2750,7 +2767,7 @@ env4 = env.Clone(tools = ['msvc', MyTool])
 .TP
 .RI env.Copy([ key = val ", ...])"
 A synonym for
-env.Clone().
+.BR env.Clone() .
 (This will probably be officially deprecated some day.)
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -2777,7 +2794,9 @@ from the repository path names,
 so that you only have to
 replicate part of the repository
 directory hierarchy in your
-local build directory:
+local build directory.
+
+Examples:
 
 .ES
 # Will fetch foo/bar/src.c
@@ -2795,6 +2814,163 @@ env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP 
+.RI Decider( function )
+.TP
+.RI env.Decider( function )
+Specifies that all up-to-date decisions for
+targets built through this construction environment
+will be handled by the specified
+.IR function .
+The
+.I function
+can be one of the following strings
+that specify the type of decision function
+to be performed:
+
+.RS 10
+.B timestamp-newer
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is newer than the target file's timestamp.
+This is the behavior of the classic Make utility,
+and
+.B make
+can be used a synonym for
+.BR timestamp-newer .
+
+.HP 6
+.B timestamp-match
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is different than the
+timestamp recorded the last time the target was built.
+This provides behavior very similar to the classic Make utility
+(in particular, files are not opened up so that their
+contents can be checksummed)
+except that the target will also be rebuilt if a
+dependency file has been restored to a version with an
+.I earlier
+timestamp, such as can happen when restoring files from backup archives.
+
+.HP 6
+.B MD5
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's content has changed sine the last time
+the target was built,
+as determined be performing an MD5 checksum
+on the dependency's contents
+and comparing it to the checksum recorded the
+last time the target was built.
+.B content
+can be used as a synonym for
+.BR MD5 .
+
+.HP 6
+.B MD5-timestamp
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's content has changed sine the last time
+the target was built,
+except that dependencies with a timestamp that matches
+the last time the target was rebuilt will be
+assumed to be up-to-date and
+.I not
+rebuilt.
+This provides behavior very similar
+to the
+.B MD5
+behavior of always checksumming file contents,
+with an optimization of not checking
+the contents of files whose timestamps haven't changed.
+The drawback is that SCons will
+.I not
+detect if a file's content has changed
+but its timestamp is the same,
+as might happen in an automated script
+that runs a build,
+updates a file,
+and runs the build again,
+all within a single second.
+.RE
+
+Examples:
+
+.ES
+# Use exact timestamp matches by default.
+Decider('timestamp-match')
+
+# Use MD5 content signatures for any targets built
+# with the attached construction environment.
+env.Decider('content')
+.EE
+
+In addition to the above already-available functions,
+the
+.I function
+argument may be an actual Python function
+that takes the following three arguments:
+
+.IP dependency
+The Node (file) which
+should cause the
+.I target
+to be rebuilt
+if it has "changed" since the last tme
+.I target was built.
+
+.IP target
+The Node (file) being built.
+In the normal case,
+this is what should get rebuilt
+if the
+.I dependency
+has "changed."
+
+.IP prev_ni
+Stored information about the state of the
+.I dependency
+the last time the
+.I target
+was built.
+This can be consulted to match various
+file characteristics
+such as the timestamp,
+size, or content signature.
+
+The
+.I function
+should return a
+.B True
+(non-zero)
+value if the
+.I dependency
+has "changed" since the last time
+the
+.I target
+was built
+(indicating that the target
+.I should
+be rebuilt),
+and
+.B False
+(zero)
+otherwise
+(indicating that the target should
+.I not
+be rebuilt).
+Note that the decision can be made
+using whatever criteria are appopriate.
+Ignoring some or all of the function arguments
+is perfectly normal.
+
+Example:
+
+.ES
+def my_decider(dependency, target, prev_ni):
+    return not os.path.exists(str(target))
+
+env.Decider(my_decider)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
 .RI Default( targets )
 .TP
 .RI env.Default( targets )
@@ -2815,6 +2991,7 @@ method, or as a list.
 will also accept the Node returned by any
 of a construction environment's
 builder methods.
+
 Examples:
 
 .ES
@@ -2863,6 +3040,8 @@ for cases where the dependency
 is not caught by a Scanner
 for the file.
 
+Example:
+
 .ES
 env.Depends('foo', 'other-input-file-for-foo')
 .EE
@@ -2877,6 +3056,8 @@ If there are any variable names specified,
 only the specified construction
 variables are returned in the dictionary.
 
+Example:
+
 .ES
 dict = env.Dictionary()
 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
@@ -2952,6 +3133,8 @@ This function will
 print out an error message and exit SCons with a non-zero exit code if the
 actual Python version is not late enough.
 
+Example:
+
 .ES
 EnsurePythonVersion(2,2)
 .EE
@@ -2972,6 +3155,8 @@ This function will
 print out an error message and exit SCons with a non-zero exit code if the
 actual SCons version is not late enough.
 
+Examples:
+
 .ES
 EnsureSConsVersion(0,14)
 
@@ -3042,6 +3227,7 @@ Multiple variable names can be passed to
 as separate arguments or as a list. A dictionary can be used to map
 variables to a different name when exported. Both local variables and
 global variables can be exported.
+
 Examples:
 
 .ES
@@ -3106,12 +3292,78 @@ may be a list of file names or a single file name. In addition to searching
 for files that exist in the filesytem, this function also searches for
 derived files that have not yet been built.
 
+Example:
+
 .ES
 foo = env.FindFile('foo', ['dir1', 'dir2'])
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI FindInstalledFiles( )
+.TP
+.RI env.FindInstalledFiles( )
+Returns the list of targets setup by the
+.B Install()
+or
+.B InstallAs()
+builders.
+
+This function serves as a convenient method to select the contents of
+a Binary Package.
+
+Example:
+
+.ES
+Install( '/bin', [ 'executable_a', 'executable_b' ] )
+
+# will return the file node list
+# [ '/bin/executable_a', '/bin/executable_b' ]
+FindInstalledFiles()
+
+Install( '/lib', [ 'some_library' ] )
+
+# will return the file node list
+# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
+FindInstalledFiles()
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI FindSourceFiles( node = '"."' )
+.TP
+.RI env.FindSourceFiles( node = '"."' )
+
+Returns the list of nodes which serve as the source of the built files.
+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
+.B node.
+These are all children which have no further children.
+
+This function is a convenient method to select the contents of a Source
+Package.
+
+Example:
+
+.ES
+Program( 'src/main_a.c' )
+Program( 'src/main_b.c' )
+Program( 'main_c.c' )
+
+# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
+FindSourceFiles()
+
+# returns ['src/main_b.c', 'src/main_a.c' ]
+FindSourceFiles( 'src' )
+.EE
+
+As you can see build support files (SConstruct in the above example)
+will also be returned by this function.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 .RI FindPathDirs( variable )
 Returns a function
 (actually a callable Python object)
@@ -3178,7 +3430,9 @@ the lists returned by calls to Builders;
 other Builders will automatically
 flatten lists specified as input,
 but direct Python manipulation of
-these lists does not:
+these lists does not.
+
+Examples:
 
 .ES
 foo = Object('foo.c')
@@ -3288,6 +3542,8 @@ The specified dependency file(s)
 will be ignored when deciding if
 the target file(s) need to be rebuilt.
 
+Examples:
+
 .ES
 env.Ignore('foo', 'foo.c')
 env.Ignore('bar', ['bar1.h', 'bar2.h'])
@@ -3314,6 +3570,7 @@ Multiple variable names can be passed to
 .BR Import ()
 as separate arguments or as a list. The variable "*" can be used
 to import all variables.
+
 Examples:
 
 .ES
@@ -3644,7 +3901,9 @@ from the Perforce source code management system.
 The returned Builder
 is intended to be passed to the
 .B SourceCode
-function:
+function.
+
+Example:
 
 .ES
 env.SourceCode('.', env.Perforce())
@@ -3673,7 +3932,9 @@ USERNAME.
 Returns a callable object
 that can be used to initialize
 a construction environment using the
-platform keyword of the Environment() method:
+platform keyword of the Environment() method.
+
+Example:
 
 .ES
 env = Environment(platform = Platform('win32'))
@@ -3707,6 +3968,124 @@ will work on Windows systems.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI Progress( callable ", [" interval ])
+.TP
+.RI Progress( string ", [" interval ", " file ", " overwrite ])
+.TP
+.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
+Allows SCons to show progress made during the build
+by displaying a string or calling a function while
+evaluating Nodes (e.g. files).
+
+If the first specified argument is a Python callable
+(a function or an object that has a
+.BR __call__ ()
+method),
+the function will be called
+once every
+.I interval
+times a Node is evaluated.
+The callable will be passed the evaluated Node
+as its only argument.
+(For future compatibility,
+it's a good idea to also add
+.B *args
+and
+.B **kw
+as arguments to your function or method.
+This will prevent the code from breaking
+if SCons ever changes the interface
+to call the function with additional arguments in the future.)
+
+An example of a simple custom progress function
+that prints a string containing the Node name
+every 10 Nodes:
+
+.ES
+def my_progress_function(node, *args, **kw):
+    print 'Evaluating node %s!' % node
+Progress(my_progress_function, interval=10)
+.EE
+.IP
+A more complicated example of a custom progress display object
+that prints a string containing a count
+every 100 evaluated Nodes.
+Note the use of
+.B \\\\r
+(a carriage return)
+at the end so that the string
+will overwrite itself on a display:
+
+.ES
+import sys
+class ProgressCounter:
+    count = 0
+    def __call__(self, node, *args, **kw):
+        self.count += 100
+        sys.stderr.write('Evaluated %s nodes\\r' % self.count)
+Progress(ProgressCounter(), interval=100)
+.EE
+.IP
+If the first argument
+.BR Progress ()
+is a string,
+the string will be displayed
+every
+.I interval
+evaluated Nodes.
+The default is to print the string on standard output;
+an alternate output stream
+may be specified with the
+.B file=
+argument.
+The following will print a series of dots
+on the error output,
+one dot for every 100 evaluated Nodes:
+
+.ES
+import sys
+Progress('.', interval=100, file=sys.stderr)
+.EE
+.IP
+If the string contains the verbatim substring
+.B $TARGET,
+it will be replaced with the Node.
+Note that, for performance reasons, this is
+.I not
+a regular SCons variable substition,
+so you can not use other variables
+or use curly braces.
+The following example will print the name of
+every evaluated Node,
+using a
+.B \\\\r
+(carriage return) to cause each line to overwritten by the next line,
+and the
+.B overwrite=
+keyword argument to make sure the previously-printed
+file name is overwritten with blank spaces:
+
+.ES
+import sys
+Progress('$TARGET\\r', overwrite=True)
+.EE
+.IP
+If the first argument to
+.BR Progress ()
+is a list of strings,
+then each string in the list will be displayed
+in rotating fashion every
+.I interval
+evaluated Nodes.
+This can be used to implement a "spinner"
+on the user's screen as follows:
+
+.ES
+Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 .RI Precious( target ", ...)"
 .TP
 .RI env.Precious( target ", ...)"
@@ -3735,6 +4114,8 @@ are both coerced to lists,
 and the lists are added together.
 (See also the Append method, above.)
 
+Example:
+
 .ES
 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
 .EE
@@ -3757,6 +4138,7 @@ and
 This can also handle the
 case where the given old path variable is a list instead of a
 string, in which case a list will be returned instead of a string.
+
 Example:
 
 .ES
@@ -3764,8 +4146,11 @@ print 'before:',env['ENV']['INCLUDE']
 include_path = '/foo/bar:/foo'
 env.PrependENVPath('INCLUDE', include_path)
 print 'after:',env['ENV']['INCLUDE']
+.EE
 
-yields:
+The above exmaple will print:
+
+.ES
 before: /biz:/foo
 after: /foo/bar:/foo:/biz
 .EE
@@ -3784,6 +4169,8 @@ construction variable will
 .I not
 be added again to the list.
 
+Example:
+
 .ES
 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
 .EE
@@ -3800,6 +4187,8 @@ is intended to be passed to the
 .B SourceCode
 function:
 
+Examples:
+
 .ES
 env.SourceCode('.', env.RCS())
 .EE
@@ -3824,6 +4213,8 @@ for a specific subdirectory.
 Replaces construction variables in the Environment
 with the specified keyword arguments.
 
+Example:
+
 .ES
 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
 .EE
@@ -3876,20 +4267,46 @@ method.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI Return( vars )
-This tells
-.B scons
-what variable(s) to use as the return value(s) of the current SConscript
-file. These variables will be returned to the "calling" SConscript file
-as the return value(s) of 
-.BR SConscript ().
-Multiple variable names should be passed to 
+.RI Return([ vars "... , " stop= ])
+By default,
+this stops processing the current SConscript
+file and returns to the calling SConscript file
+the values of the variables named in the
+.I vars
+string arguments.
+Multiple strings contaning variable names may be passed to
+.BR Return ().
+Any strings that contain white space
+
+The optional
+.B stop=
+keyword argument may be set to a false value
+to continue processing the rest of the SConscript
+file after the
 .BR Return ()
-as a list. Example:
+call.
+This was the default behavior prior to SCons 0.98.
+However, the values returned
+are still the values of the variables in the named
+.I vars
+at the point
+.BR Return ()
+is called.
+
+Examples:
 
 .ES
+# Returns without returning a value.
+Return()
+
+# Returns the value of the 'foo' Python variable.
 Return("foo")
-Return(["foo", "bar"])
+
+# Returns the values of the Python variables 'foo' and 'bar'.
+Return("foo", "bar")
+
+# Returns the values of Python variables 'val1' and 'val2'.
+Return('val1 val2')
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -3913,7 +4330,9 @@ from SCCS.
 The returned Builder
 is intended to be passed to the
 .B SourceCode
-function:
+function.
+
+Example:
 
 .ES
 env.SourceCode('.', env.SCCS())
@@ -4090,11 +4509,12 @@ while reading all SConscript files.
 (This may be necessary when building from repositories,
 when all the directories in which SConscript files may be found
 don't necessarily exist locally.)
-
 You may enable and disable
 this ability by calling
 SConscriptChdir()
-multiple times:
+multiple times.
+
+Example:
 
 .ES
 env = Environment()
@@ -4212,7 +4632,9 @@ which corresponds to -j and --jobs.
 which corresponds to --random.
 See the documentation for the
 corresponding command line object for information about each specific
-option. Example:
+option.
+
+Example:
 
 .ES
 SetOption('max_drift', 1)
@@ -4393,6 +4815,8 @@ you can use the Python
 idiom to pass in an unnamed function
 that simply returns its unconverted argument.
 
+Example:
+
 .ES
 print env.subst("The C compiler is: $CC")
 
@@ -4428,7 +4852,9 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST',
 '\"so that you only have to
 '\"replicate part of the repository
 '\"directory hierarchy in your
-'\"local build directory:
+'\"local build directory.
+'\"
+'\"Example:
 '\"
 '\".ES
 '\"# Will fetch foo/bar/src.c
@@ -4449,10 +4875,17 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST',
 .RI SourceSignatures( type )
 .TP
 .RI env.SourceSignatures( type )
-This function tells SCons what type of signature to use for source files:
+This function tells
+.B scons
+how to decide if a source file
+(a file that is not built from any other files)
+has changed since the last time it
+was used to build a particular target file.
+Legal values are
 .B "MD5"
 or
 .BR "timestamp" .
+
 If the environment method is used,
 the specified type of source signature
 is only used when deciding whether targets
@@ -4462,17 +4895,48 @@ the specified type of source signature becomes the default
 used for all decisions
 about whether targets are up-to-date.
 
-"MD5" means the signature of a source file
-is the MD5 checksum of its contents.
-"timestamp" means the signature of a source file
-is its timestamp (modification time).
+.B "MD5"
+means
+.B scons
+decides that a source file has changed
+if the MD5 checksum of its contents has changed since
+the last time it was used to rebuild a particular target file.
+
+.B "timestamp"
+means
+.B scons
+decides that a source file has changed
+if its timestamp (modification time) is newer than
+the last time it was used to rebuild a particular target file.
+
 There is no different between the two behaviors
 for Python
 .BR Value ()
 node objects.
-"MD5" signatures take longer to compute,
-but are more accurate than "timestamp" signatures.
-The default is "MD5".
+
+.B "MD5"
+signatures take longer to compute,
+but are more accurate than
+.B "timestamp"
+signatures.
+The default value is
+.BR "MD5" .
+
+Note that the default
+.BR TargetSignatures ()
+setting (see below)
+is to use this
+.BR SourceSignatures ()
+setting for any target files that are used
+to build other target files.
+Consequently, changing the value of
+.BR SourceSignatures ()
+will, by default,
+affect the up-to-date decision for all files in the build
+(or all files built with a specific construction environment
+when
+.BR env.SourceSignatures ()
+is used).
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
@@ -4490,6 +4954,8 @@ If arg is any other type of object,
 it will be returned as a list
 containing just the object.
 
+Example:
+
 .ES
 files = Split("f1.c f2.c f3.c")
 files = env.Split("f4.c f5.c f6.c")
@@ -4509,6 +4975,8 @@ information about how the
 Builder should package those files or directories.
 All tags are optional.
 
+Examples:
+
 .ES
 # makes sure the built library will be installed with 0644 file
 # access mode
@@ -4525,13 +4993,25 @@ Tag( 'file2.txt', DOC )
 .RI TargetSignatures( type )
 .TP
 .RI env.TargetSignatures( type )
-This function tells SCons what type of signatures to use
-for target files:
-.B "build"
+This function tells
+.B scons
+how to decide if a target file
+(a file that
+.I is
+built from any other files)
+has changed since the last time it
+was used to build some other target file.
+Legal values are
+.BR "build" ;
+.BR "content"
+(or its synonym
+.BR "MD5" );
+.BR "timestamp" ;
 or
-.BR "content" .
+.BR "source" .
+
 If the environment method is used,
-the specified type of signature is only used
+the specified type of target signature is only used
 for targets built with that environment.
 If the global function is used,
 the specified type of signature becomes the default
@@ -4539,16 +5019,94 @@ used for all target files that
 don't have an explicit target signature type
 specified for their environments.
 
-"build" means the signature of a target file
-is made by concatenating all of the
-signatures of all its source files.
-"content" means the signature of a target
-file is an MD5 checksum of its contents.
-"build" signatures are usually faster to compute,
-but "content" signatures can prevent unnecessary rebuilds
+.B "content"
+(or its synonym
+.BR "MD5" )
+means
+.B scons
+decides that a target file has changed
+if the MD5 checksum of its contents has changed since
+the last time it was used to rebuild some other target file.
+This means
+.B scons
+will open up
+MD5 sum the contents
+of target files after they're built,
+and may decide that it does not need to rebuild
+"downstream" target files if a file was
+rebuilt with exactly the same contents as the last time.
+
+.B "timestamp"
+means
+.B scons
+decides that a target file has changed
+if its timestamp (modification time) is newer than
+the last time it was used to rebuild some other target file.
+
+.B "source"
+means
+.B scons
+decides that a target file has changed
+as specified by the corresponding
+.BR SourceSignatures ()
+setting
+.BR "" ( "MD5"
+or
+.BR "timestamp" ).
+This means that
+.B scons
+will treat all input files to a target the same way,
+regardless of whether they are source files
+or have been built from other files.
+
+.B "build"
+means
+.B scons
+decides that a target file has changed
+if it has been rebuilt in this invocation
+or if its content or timestamp have changed
+as specified by the corresponding
+.BR SourceSignatures ()
+setting.
+This "propagates" the status of a rebuilt file
+so that other "downstream" target files
+will always be rebuilt,
+even if the contents or the timestamp
+have not changed.
+
+.B "build"
+signatures are fastest because
+.B "content"
+(or
+.BR "MD5" )
+signatures take longer to compute,
+but are more accurate than
+.B "timestamp"
+signatures,
+and can prevent unnecessary "downstream" rebuilds
 when a target file is rebuilt to the exact same contents
 as the previous build.
-The default is "build".
+The
+.B "source"
+setting provides the most consistent behavior
+when other target files may be rebuilt from
+both source and target input files.
+The default value is
+.BR "source" .
+
+Because the default setting is
+.BR "source" ,
+using
+.BR SourceSignatures ()
+is generally preferable to
+.BR TargetSignatures () ,
+so that the up-to-date decision
+will be consistent for all files
+(or all files built with a specific construction environment).
+Use of
+.BR TargetSignatures ()
+provides specific control for how built target files
+affect their "downstream" dependencies.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
@@ -4570,6 +5128,8 @@ Additional keyword arguments are passed to the tool's
 .B generate()
 method.
 
+Examples:
+
 .ES
 env = Environment(tools = [ Tool('msvc') ])
 
@@ -4605,7 +5165,10 @@ calling
 .BR str( value )
 changes between SCons runs, any targets depending on
 .BR Value( value )
-will be rebuilt.  When using timestamp source signatures, Value Nodes'
+will be rebuilt.
+(This is true even when using timestamps to decide if
+files are up-to-date.)
+When using timestamp source signatures, Value Nodes'
 timestamps are equal to the system time when the Node is created.
 
 The returned Value Node object has a
@@ -4622,22 +5185,38 @@ There is a corresponding
 .BR read ()
 method that will return the built value of the Node.
 
+Examples:
+
 .ES
+env = Environment()
+
 def create(target, source, env):
+    # A function that will write a 'prefix=$SOURCE'
+    # string into the file name specified as the
+    # $TARGET.
     f = open(str(target[0]), 'wb')
     f.write('prefix=' + source[0].get_contents())
     
+# Fetch the prefix= argument, if any, from the command
+# line, and use /usr/local as the default.
 prefix = ARGUMENTS.get('prefix', '/usr/local')
-env = Environment()
+
+# Attach a .Config() builder for the above function action
+# to the construction environment.
 env['BUILDERS']['Config'] = Builder(action = create)
 env.Config(target = 'package-config', source = Value(prefix))
 
 def build_value(target, source, env):
+    # A function that "builds" a Python Value by updating
+    # the the Python value with the contents of the file
+    # specified as the source of the Builder call ($SOURCE).
     target[0].write(source[0].get_contents())
 
 output = env.Value('before')
 input = env.Value('after')
 
+# Attach a .UpdateValue() builder for the above function
+# action to the construction environment.
 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
 env.UpdateValue(target = Value(output), source = Value(input))
 .EE
@@ -4711,6 +5290,8 @@ and
 .B [1]
 of the tuple, respectively.
 
+Example:
+
 .ES
 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
@@ -4735,6 +5316,8 @@ the one in the
 .B ARGUMENTS
 dictionary.
 
+Example:
+
 .ES
 if ARGUMENTS.get('debug', 0):
     env = Environment(CCFLAGS = '-g')
@@ -4771,6 +5354,8 @@ See the
 list, below,
 for additional information.
 
+Example:
+
 .ES
 if 'foo' in BUILD_TARGETS:
     print "Don't forget to test the `foo' program!"
@@ -4800,7 +5385,9 @@ the list is empty.
 This can be used, for example,
 to take specific actions only
 when a certain target or targets
-is explicitly being built:
+is explicitly being built.
+
+Example:
 
 .ES
 if 'foo' in COMMAND_LINE_TARGETS:
@@ -4822,6 +5409,8 @@ so you need to run them through the Python
 .B str
 function to get at the path name for each Node.
 
+Example:
+
 .ES
 print str(DEFAULT_TARGETS[0])
 if 'foo' in map(str, DEFAULT_TARGETS):
@@ -6007,6 +6596,33 @@ b = Builder("build_it < $SOURCE > $TARGET",
                        "$SRC_SFX_A": gen_suffix })
 .EE
 
+.IP ensure_suffix
+When set to any true value, causes 
+.B scons
+to add the target suffix specified by the
+.I suffix
+keyword to any target strings
+that have a different suffix.
+(The default behavior is to leave untouched
+any target file name that looks like it already has any suffix.)
+
+.ES
+b1 = Builder("build_it < $SOURCE > $TARGET"
+             suffix = ".out")
+b2 = Builder("build_it < $SOURCE > $TARGET"
+             suffix = ".out",
+             ensure_suffix)
+env = Environment()
+env['BUILDERS']['B1'] = b1
+env['BUILDERS']['B2'] = b2
+
+# Builds "foo.txt" because ensure_suffix is not set.
+env.B1('foo.txt', 'foo.in')
+
+# Builds "bar.txt.out" because ensure_suffix is set.
+env.B2('bar.txt', 'bar.in')
+.EE
+
 .IP src_suffix
 The expected source file name suffix.  This may be a string or a list
 of strings.
diff --git a/doc/man/sconsign.1 b/doc/man/sconsign.1
index 3d01cf4..7c80327 100644
--- a/doc/man/sconsign.1
+++ b/doc/man/sconsign.1
@@ -56,14 +56,19 @@ dumps the entire contents of the
 specified file(s).
 Each entry is printed in the following format:
 
-    file: timestamp bsig csig
-            implicit_dependency_1
-            implicit_dependency_2
+    file: signature timestamp length
+            implicit_dependency_1: signature timestamp length
+            implicit_dependency_2: signature timestamp length
+            action_signature [action string]
 
-If the entry has no timestamp, bsig, or csig, a dash
 .B None
-is printed.
+is printed
+in place of any missing timestamp, bsig, or csig
+values for
+any entry
+or any of its dependencies.
 If the entry has no implicit dependencies,
+or no build action,
 the lines are simply omitted.
 
 By default,
@@ -100,8 +105,8 @@ Various options control what information is printed
 and the format:
 
 .TP
--b, --bsig
-Prints the build signature (bsig) information
+-a, --act, --action
+Prints the build action information
 for all entries or the specified entries.
 
 .TP
@@ -165,7 +170,9 @@ for all entries or the the specified entries.
 --raw
 Prints a pretty-printed representation
 of the raw Python dictionary that holds
-build information about an entry.
+build information about individual entry
+(both the entry itself or its implicit dependencies).
+An entry's build action is still printed in its usual format.
 
 .TP
 -r, --readable