Merged revisions 2647-2719 via svnmerge from

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

........
  r2649 | stevenknight | 2008-02-08 06:43:30 -0800 (Fri, 08 Feb 2008) | 3 lines

  Make the "bootstrap" copy directory relative to the script location
  regardless of where the user is when executing.
........
  r2650 | stevenknight | 2008-02-09 09:26:40 -0800 (Sat, 09 Feb 2008) | 3 lines

  Chdir back to the original directory before removing our temporary
  directory, to avoid "Permission denied" errors on Windows.
........
  r2651 | stevenknight | 2008-02-09 10:02:09 -0800 (Sat, 09 Feb 2008) | 3 lines

  Fix floating-point numbers confusing our notion of the .class
  files that will be generated in certain configurations.
........
  r2652 | stevenknight | 2008-02-09 10:26:48 -0800 (Sat, 09 Feb 2008) | 4 lines

  Issue 1868:  change the RootDir "lookup path" from '/' to '' so that
  looking up '/foo' returns the same node as looking up 'foo' when the
  current directory is the root.
........
  r2653 | stevenknight | 2008-02-09 11:16:17 -0800 (Sat, 09 Feb 2008) | 3 lines

  Issue 1902:  Document all the values that can now be fetched with GetOption.
  Additional formatting cleanups.
........
  r2654 | stevenknight | 2008-02-09 11:37:50 -0800 (Sat, 09 Feb 2008) | 3 lines

  Fix handling file names that contain substrings of multiple spaces
  when using ActionFactory instances like Copy() and Move().
........
  r2655 | stevenknight | 2008-02-09 13:36:14 -0800 (Sat, 09 Feb 2008) | 3 lines

  Issue 1898:  Fix use of a variable expansion in a source file name
  (like foo$OBJSUFFIX) when trying to match source builder suffixes.
........
  r2656 | stevenknight | 2008-02-09 20:58:32 -0800 (Sat, 09 Feb 2008) | 3 lines

  Issue 1903:  don't allow Java generics syntax to interfere with
  identifying an anonymous inner class.
........
  r2657 | stevenknight | 2008-02-09 21:02:37 -0800 (Sat, 09 Feb 2008) | 3 lines

  Left out the \w from the regular expression that matches generics,
  so we wouldn't match alphanumerics, only alphabetics.
........
  r2658 | stevenknight | 2008-02-09 23:33:03 -0800 (Sat, 09 Feb 2008) | 3 lines

  Issue 1899:  Enhance Chmod(), Delete(), Mkdir() and Touch() to take
  lists of Nodes or strings.
........
  r2659 | stevenknight | 2008-02-10 00:15:24 -0800 (Sun, 10 Feb 2008) | 4 lines

  Issue 1878:  Add comment lines to the generated config.h file describing
  the intent of the various #define/#undef lines.
  (David Cournapeau)
........
  r2660 | stevenknight | 2008-02-11 18:15:27 -0800 (Mon, 11 Feb 2008) | 3 lines

  Issue 1682:  Fix the ability to save and restore the ListOption value
  'all' in newer Python versions that have an all() built-in function.
........
  r2661 | stevenknight | 2008-02-27 07:25:18 -0800 (Wed, 27 Feb 2008) | 3 lines

  Issue 1919:  Optimize the SCons.Util.is_*() and SCons.Util.flatten()
  functions.  More efficient suffix selection in Selector.__call__() method.
........
  r2662 | stevenknight | 2008-02-28 06:43:29 -0800 (Thu, 28 Feb 2008) | 3 lines

  Fix SCons.Util.is_List() method to use the passed-in ListTypes variable.
  (Daniel Svensson)
........
  r2663 | stevenknight | 2008-02-28 06:57:44 -0800 (Thu, 28 Feb 2008) | 4 lines

  Issue 1884:  avoid an infinite loop when trying to use saved copies of
  the ToolInitializer objects that we use to initialize the env.Install()
  and env.InstallAs() methods.
........
  r2664 | garyo | 2008-02-28 07:25:25 -0800 (Thu, 28 Feb 2008) | 1 line

  Fix long-style command-line args in runtest.py (they were missing from getopt call).
........
  r2665 | garyo | 2008-02-28 09:31:42 -0800 (Thu, 28 Feb 2008) | 1 line

  runtest.py: Use qmtest instead of qmtest.py; newer QMTest releases may only have qmtest in /usr/bin.
........
  r2666 | stevenknight | 2008-02-28 12:10:02 -0800 (Thu, 28 Feb 2008) | 3 lines

  Remove dead code that was at one time apparently intended to grab the
  external environment's %INCLUDE% values.
........
  r2667 | stevenknight | 2008-02-28 12:16:40 -0800 (Thu, 28 Feb 2008) | 3 lines

  Move the regular expression and function that check for whether a
  construction variable name is legal from Util.py to Environment.py.
........
  r2668 | stevenknight | 2008-02-28 20:24:36 -0800 (Thu, 28 Feb 2008) | 2 lines

  Fix qmtest.py references (replace with qmtest) in tests and infrastructure.
........
  r2669 | stevenknight | 2008-02-28 20:27:05 -0800 (Thu, 28 Feb 2008) | 7 lines

  Speed up the SubstitionEnvironment.__setitem__() method by: 1) avoiding
  checking for whether the variable name is legal if it already exists; 2)
  use the regular expression directly when checking the form for illegality;
  3) more efficient check for whether a variable name is special.  Add a
  timing script so we can document why we implemented it as we did and
  revisit it in the future if need be.
........
  r2670 | stevenknight | 2008-02-28 20:51:44 -0800 (Thu, 28 Feb 2008) | 2 lines

  Add a shell script that generates context-diff output for review.
........
  r2671 | GregNoel | 2008-03-01 00:40:16 -0800 (Sat, 01 Mar 2008) | 1 line

  add test to env.__setitem__ benchmark
........
  r2672 | GregNoel | 2008-03-01 02:00:12 -0800 (Sat, 01 Mar 2008) | 1 line

  compatibility changes for env.__setitem__ benchmark
........
  r2673 | stevenknight | 2008-03-01 09:56:57 -0800 (Sat, 01 Mar 2008) | 3 lines

  Capture a vanilla copy of the Python 2.[45] timeit.py module, as a
  basis for being able to use this to time Python 2.2 (and earlier).
........
  r2674 | stevenknight | 2008-03-01 10:04:11 -0800 (Sat, 01 Mar 2008) | 3 lines

  Work around a race in the order in which we detect and report the build
  failures by letting the error messages show up in either order on stdout.
........
  r2675 | stevenknight | 2008-03-01 10:05:24 -0800 (Sat, 01 Mar 2008) | 3 lines

  Back-port the captured timeit.py module, and the env.__setitem__.py
  script itself, to Python versions before 2.3.
........
  r2676 | GregNoel | 2008-03-01 14:01:03 -0800 (Sat, 01 Mar 2008) | 1 line

  add banner information, remove inadvertent tabs
........
  r2677 | stevenknight | 2008-03-02 05:04:52 -0800 (Sun, 02 Mar 2008) | 3 lines

  Don't look for a Copyright string in the source-packaged bench/timeit.py
  module that we captured.
........
  r2678 | stevenknight | 2008-03-02 14:59:39 -0800 (Sun, 02 Mar 2008) | 6 lines

  Issue 1884:  Allow env.{Install,InstallAs}() to be replaced by user-
  supplied wrappers that call the underlying builder.

  Fix how environment cloning so it only clones dynamically-added method
  attributes that the user hasn't also overwritten explicity.
........
  r2679 | stevenknight | 2008-03-04 07:48:53 -0800 (Tue, 04 Mar 2008) | 3 lines

  Fix env.{Dir,Entry,File}() when the input is a list, broken last December
  when env.subst() was modified to return lists as-is.
........
  r2680 | stevenknight | 2008-03-04 08:24:06 -0800 (Tue, 04 Mar 2008) | 2 lines

  Fix printing Python Value Nodes in --debug=explain output.  (Jim Randall)
........
  r2681 | garyo | 2008-03-04 12:37:39 -0800 (Tue, 04 Mar 2008) | 1 line

  Make File(), Dir() and Entry() return lists when passed a sequence.
........
  r2682 | garyo | 2008-03-05 15:24:00 -0800 (Wed, 05 Mar 2008) | 1 line

  InstallBuilderWrapper and InstallBuilderWrapper should accept keyword args and pass them to the base builder, like other builders.
........
  r2683 | stevenknight | 2008-03-06 06:32:13 -0800 (Thu, 06 Mar 2008) | 2 lines

  Python 1.5.2 compatibility:  use apply() instead of **kw.
........
  r2684 | garyo | 2008-03-14 13:07:09 -0700 (Fri, 14 Mar 2008) | 1 line

  Fix QMTest problem with $TERM variable in user's environment causing test failures.
........
  r2685 | bdbaddog | 2008-03-14 13:16:20 -0700 (Fri, 14 Mar 2008) | 13 lines

  * Added java_where_includes - gets path list for java JDK's include dirs
  * Added java_where_java_home - gets  JAVA_HOME  path
  * Added path's to find java for sun's JDK rpm install to java_where_jar
  * moved paths() to be outside of java_ENV() routine and available for other routines to use as well as tests
  * set TERM to be dumb to fix broken readline causing massive failures on FC8 (only updated Gary's comments to include note about broken FC8 readline, as Gary committed the TERM just prior to my checkin)
  * Modified the following tests to use the above changes:
     * test/SWIG/SWIGOUTDIR.py
     * test/Java/swig-dependencies.py
     * test/Java/multi-step.py
     * test/Repository/Java.py
     * test/runtest/fallback.py  [ This test also has been changed to remove more than one qmtest in your PATH, previously it would only remove one path which had qmtest, my system had a local and a system version ]
........
  r2686 | stevenknight | 2008-03-15 20:50:07 -0700 (Sat, 15 Mar 2008) | 4 lines

  Add a warning about deprecating support for Python versions 1.5, 2.0
  and 2.1.  Fix the ability to SetOption('warn') so people can disable
  the warning by adding something to a SConscript file.
........
  r2687 | stevenknight | 2008-03-15 21:48:26 -0700 (Sat, 15 Mar 2008) | 3 lines

  Issue 1942:  Document the Dir(), File() and Entry() methods of Dir
  and File Nodes.  (Greg Noel)
........
  r2688 | GregNoel | 2008-03-16 00:05:04 -0700 (Sun, 16 Mar 2008) | 1 line

  Add parse_flags keyword option
........
  r2689 | stevenknight | 2008-03-16 00:32:33 -0700 (Sun, 16 Mar 2008) | 3 lines

  Print a message if we're skipping the build of a package because the
  necessary underlying tool doesn't exist.
........
  r2690 | stevenknight | 2008-03-16 00:40:28 -0700 (Sun, 16 Mar 2008) | 7 lines

  Add --warn=no-python-version to the $SCONSFLAGS variable when running
  tests under deprecated Python versions, so the warning doesn't interfere
  with running normal tests under those version.

  Have the test/python-version.py remove --warn=no-python-version from the
  $SCONSFLAGS variable, since it's explicitly testing that behavior.
........
  r2691 | stevenknight | 2008-03-16 08:20:54 -0700 (Sun, 16 Mar 2008) | 4 lines

  Handle ripple effects from setting $SCONSFLAGS to suppress the deprecation
  under older Python versions by commonizing and moving much of the logic
  in QMTest/TestSCons.py.
........
  r2692 | stevenknight | 2008-03-16 08:47:52 -0700 (Sun, 16 Mar 2008) | 5 lines

  Update the warning message for running under a deprecated Python
  version (text courtesy Greg Noel).  Make that warning a subclass of the
  DeprecatedWarning class, so the message can also be disabled by setting
  --warn=no-deprecated.
........
  r2693 | stevenknight | 2008-03-16 11:19:52 -0700 (Sun, 16 Mar 2008) | 4 lines

  Shorten the deprecated-python-version warning.
  Use sys.version_info to check, instead of hard-coded string comparisons.
  Edit the release note.
........
  r2694 | stevenknight | 2008-03-16 11:29:10 -0700 (Sun, 16 Mar 2008) | 3 lines

  Have the warning mention both that 2.2 is the base un-deprecated version
  and the version they're running without getting too wordy.
........
  r2695 | stevenknight | 2008-03-16 12:00:22 -0700 (Sun, 16 Mar 2008) | 2 lines

  Skip test/SWIG/SWIGOUTDIR.py if no installed jni.h files are found.
........
  r2696 | stevenknight | 2008-03-18 18:01:46 -0700 (Tue, 18 Mar 2008) | 2 lines

  Remove old, commented-out deprecation test code.
........
  r2697 | stevenknight | 2008-03-19 17:54:55 -0700 (Wed, 19 Mar 2008) | 2 lines

  Deprecate env.Copy() with a suppressable message.
........
  r2699 | stevenknight | 2008-03-20 08:20:22 -0700 (Thu, 20 Mar 2008) | 2 lines

  Move the debug-nomemoizer.py test to the test/Deprecated subdirectory.
........
  r2700 | stevenknight | 2008-03-20 08:37:51 -0700 (Thu, 20 Mar 2008) | 2 lines

  Issue 1954:  Adds deprecation warnings for --debug={dtree,stree,tree}.
........
  r2701 | stevenknight | 2008-03-23 00:33:25 -0700 (Sun, 23 Mar 2008) | 7 lines

  Add VariantDir() as a replacement for BuildDir().
  Change "build directory" references in text (comments and
  documentation) to "variant directory."
  Move and rename tests that named BuildDir in their path.
  Add a release note about the forthcoming deprecation of BuildDir().
  Add a test/Deprecated/BuildDir.py to track backwards compatibility.
........
  r2702 | stevenknight | 2008-03-24 11:23:39 -0700 (Mon, 24 Mar 2008) | 4 lines

  Change the VariantDir() and SConscrip "build_dir" keyword to "variant_dir."
  Still support "build_dir" for (you guessed it) backwards compatibility.
  Add documentation update and release note.
........
  r2703 | garyo | 2008-03-25 07:57:01 -0700 (Tue, 25 Mar 2008) | 1 line

  Improve Install error message when target and source list lengths don't match.
........
  r2704 | garyo | 2008-03-25 08:10:24 -0700 (Tue, 25 Mar 2008) | 1 line

  Allow executing main scons.py script without running scons, using standard if __name__==__main__ idiom.
........
  r2705 | stevenknight | 2008-03-26 08:51:58 -0700 (Wed, 26 Mar 2008) | 3 lines

  Update scripts that use {Source,Target}Signatures() to use Decider()
  or the default behavior.  Update test condition checks as necessary.
........
  r2706 | stevenknight | 2008-03-27 14:13:50 -0700 (Thu, 27 Mar 2008) | 2 lines

  Update some leftover uses of env.Copy() in some test scripts to env.Clone().
........
  r2707 | stevenknight | 2008-03-27 14:20:33 -0700 (Thu, 27 Mar 2008) | 6 lines

  Fix use of SetOption('warn') to disable warning messages.
  Refactor the Script.Main._setup_warn() function into
  Warnings.process_warn_strings().
  Split test/option--warn.py into separate test/option/warn-*.py scripts
  for the individual subtests it contained.
........
  r2708 | stevenknight | 2008-03-27 15:17:44 -0700 (Thu, 27 Mar 2008) | 5 lines

  Deprecate the {Target,Source}Signatures() functions and methods.
  Move the test scripts underneath the test/Deprecated directory.
  Update man page with the new --warn=* options (and some that
  were overlooked on previous checkins).  Add a release note.
........
  r2709 | stevenknight | 2008-03-27 23:22:38 -0700 (Thu, 27 Mar 2008) | 2 lines

  More conversion of env.Copy() calls to env.Clone().
........
  r2710 | stevenknight | 2008-03-28 00:09:40 -0700 (Fri, 28 Mar 2008) | 3 lines

  Test updates for old Python versions (1.5.2) now that we generate a
  warning message about the deprecation.
........
  r2711 | stevenknight | 2008-03-28 22:11:03 -0700 (Fri, 28 Mar 2008) | 3 lines

  Chmod the built packages in build/dist to 0644 so they're publicy readable
  when they're copied over to the snapshot system.
........
  r2712 | stevenknight | 2008-03-28 22:11:54 -0700 (Fri, 28 Mar 2008) | 3 lines

  Issue 1951:  have Copy() preserve file times and mode when copying
  over individual files.  (Leanid Nazdrynau)
........
  r2713 | stevenknight | 2008-03-29 06:49:27 -0700 (Sat, 29 Mar 2008) | 3 lines

  Don't bother checking for equivalent file access times.  Under system
  load it can vary because we do actually access the file.
........
  r2714 | GregNoel | 2008-03-29 17:24:25 -0700 (Sat, 29 Mar 2008) | 1 line

  Fix regression test using Python 1.5.2 on OS X
........
  r2715 | GregNoel | 2008-03-29 20:44:19 -0700 (Sat, 29 Mar 2008) | 1 line

  'Copy' conflicts with 'copy' on case-insensitive file systems
........
  r2716 | stevenknight | 2008-03-29 21:00:13 -0700 (Sat, 29 Mar 2008) | 3 lines

  Capture scripts for downloading and installing different versions of
  Python and SCons.
........
  r2717 | stevenknight | 2008-03-30 08:48:28 -0700 (Sun, 30 Mar 2008) | 3 lines

  Fix a regression in how subst_path() handles lists (like a ListOption)
  in expansions of things like $CPPDEFINES and $CPPPATH.
........
  r2718 | stevenknight | 2008-03-30 10:02:21 -0700 (Sun, 30 Mar 2008) | 6 lines

  User's Guide updates:
  --  Paragraph about deprecated BuildDir().
  --  Updated output using the jar -C option.
  --  Updated default environment Dump().
  --  Updated --debug=stacktrace output.
........
  r2719 | stevenknight | 2008-03-31 00:50:08 -0700 (Mon, 31 Mar 2008) | 2 lines

  Update the branch for 0.98.
........

9 files changed, 573 insertions, 201 deletions

diff --git a/doc/SConscript b/doc/SConscript
index 8e13294..0c8f070 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -33,8 +33,6 @@ Import('build_dir', 'env', 'whereis')
 
 env = env.Clone()
 
-env.TargetSignatures('content')
-
 build = os.path.join(build_dir, 'doc')
 
 #
@@ -123,7 +121,9 @@ manifest_xml_in = File('#src/engine/MANIFEST-xml.in').rstr()
 scons_doc_files = map(chop, open(manifest_xml_in).readlines())
 scons_doc_files = map(lambda x: File('#src/engine/'+x).rstr(), scons_doc_files)
 
-if jw:
+if not jw:
+    print "jw not found, skipping building User Guide."
+else:
     #
     # Always create a version.xml file containing the version information
     # for this run.  Ignore it for dependency purposes so we don't
@@ -461,7 +461,9 @@ for man_1 in man_page_list:
         tar_deps.append(html)
         tar_list.append(html)
 
-if epydoc:
+if not epydoc:
+    print "epydoc not found, skipping building API documentation."
+else:
     # XXX Should be in common with reading the same thing in
     # the SConstruct file.
     e = os.path.join('#src', 'engine')
@@ -520,6 +522,7 @@ if tar_deps:
                            tar_list))
     t = env.Command(dist_doc_tar_gz, tar_deps,
                 "tar cf${TAR_HFLAG} - -C %s %s | gzip > $TARGET" % (build, tar_list))
+    AddPostAction(dist_doc_tar_gz, Chmod(dist_doc_tar_gz, 0644))
     Local(t)
     Alias('doc', t)
 else:
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index ae25274..98e12e6 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -980,6 +980,7 @@ are synonyms.
 Prints SCons version information.
 .RE
 
+.IP
 An empty line repeats the last typed command.
 Command-line editing can be used if the
 .B readline
@@ -1328,8 +1329,30 @@ These warnings are disabled by default.
 
 .TP
 --warn=deprecated, --warn=no-deprecated
-Enables or disables warnings about use of deprecated features.
+Enables or disables all warnings about use of deprecated features.
 These warnings are enabled by default.
+Warnings for some specific deprecated features
+may be enabled or disabled individually;
+see below.
+
+--warn=deprecated-copy, --warn=no-deprecated-copy
+Enables or disables warnings about use of the deprecated
+.B env.Copy()
+method.
+
+--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
+Enables or disables warnings about use of the deprecated
+SourceSignatures() function
+or
+.B env.SourceSignatures()
+method.
+
+--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
+Enables or disables warnings about use of the deprecated
+TargetSignatures() function
+or
+.B env.TargetSignatures()
+method.
 
 .TP
 --warn=duplicate-environment, --warn=no-duplicate-environment
@@ -1372,6 +1395,16 @@ option is used.
 These warnings are enabled by default.
 
 .TP
+--warn=no-object-count, --warn=no-no-object-count
+Enables or disables warnings about the
+.B --debug=object
+feature not working when
+.B scons
+is run with the python
+.B \-O
+option or from optimized Python (.pyo) modules.
+
+.TP
 --warn=no-parallel-support, --warn=no-no-parallel-support
 Enables or disables warnings about the version of Python
 not being able to support parallel builds when the
@@ -1380,6 +1413,12 @@ option is used.
 These warnings are enabled by default.
 
 .TP
+--warn=python-version, --warn=no-python-version
+Enables or disables the warning about running
+SCons with a deprecated version of Python.
+These warnings are enabled by default.
+
+.TP
 --warn=reserved-variable, --warn=no-reserved-variable
 Enables or disables warnings about attempts to set the
 reserved construction variable names
@@ -1441,6 +1480,40 @@ function:
 env = Environment()
 .EE
 
+Variables, called
+.I construction
+.IR variables ,
+may be set in a construction environment
+either by specifyng them as keywords when the object is created
+or by assigning them a value after the object is created:
+
+.ES
+env = Environment(FOO = 'foo')
+env['BAR'] = 'bar'
+.EE
+
+As a convenience,
+construction variables may also be set or modified by the
+.I parse_flags
+keyword argument, which applies the
+.B ParseFlags
+method (described below) to the argument value
+after all other processing is completed.
+This is useful either if the exact content of the flags is unknown
+(for example, read from a control file)
+or if the flags are distributed to a number of construction variables.
+
+.ES
+env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
+.EE
+
+This example adds 'include' to
+.BR CPPPATH ,
+\'EBUG' to
+.BR CPPDEFINES ,
+and 'm' to
+.BR LIBS .
+
 By default, a new construction environment is
 initialized with a set of builder methods
 and construction variables that are appropriate
@@ -1846,6 +1919,21 @@ if you want SCons to search automatically
 for dependencies on the non-standard library names;
 see the descriptions of these variables, below, for more information.)
 
+It is also possible to use the
+.I parse_flags
+keyword argument in an override:
+
+.ES
+env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
+.EE
+
+This example adds 'include' to
+.BR CPPPATH ,
+\'EBUG' to
+.BR CPPDEFINES ,
+and 'm' to
+.BR LIBS .
+
 Although the builder methods defined by
 .B scons
 are, in fact,
@@ -2168,11 +2256,14 @@ calling the functionality through a construction environment will
 substitute construction variables into
 any supplied strings.
 For example:
+
 .ES
 env = Environment(FOO = 'foo')
 Default('$FOO')
 env.Default('$FOO')
 .EE
+
+In the above example,
 the first call to the global
 .B Default()
 function will actually add a target named
@@ -2604,97 +2695,19 @@ env.SourceCode('.', env.BitKeeper())
 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
 .TP
 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
-This specifies a build directory
-.I build_dir
-in which to build all derived files
-that would normally be built under
-.IR src_dir .
-Multiple build directories can be set up for multiple build variants, for
-example. 
-.I src_dir
-must be underneath the SConstruct file's directory,
+Synonyms for
+.B VariantDir()
 and
+.BR env.VariantDir() .
+The
 .I build_dir
-may not be underneath the
-.I src_dir .
-
-The default behavior is for
-.B scons
-to duplicate all of the files in the tree underneath
-.I src_dir
-into
-.IR build_dir ,
-and then build the derived files within the copied tree.
-(The duplication is performed by
-linking or copying,
-depending on the platform; see also the
-.IR --duplicate
-option.)
-This guarantees correct builds
-regardless of whether intermediate source files
-are generated during the build,
-where preprocessors or other scanners search
-for included files,
-or whether individual compilers or other invoked tools
-are hard-coded to put derived files in the same directory as source files.
-
-This behavior of making a complete copy of the source tree
-may be disabled by setting
-.I duplicate
-to 0.
-This will cause
-.B scons
-to invoke Builders using the
-path names of source files in
-.I src_dir
-and the path names of derived files within
-.IR build_dir .
-This is always more efficient than
-.IR duplicate =1,
-and is usually safe for most builds.
-Specifying
-.IR duplicate =0,
-however,
-may cause build problems
-if source files are generated during the build,
-if any invoked tools are hard-coded to
-put derived files in the same directory as the source files.
-
-Note that specifying a
-.B BuildDir
-works most naturally
-with a subsidiary SConscript file
-in the source directory.
-However,
-you would then call the subsidiary SConscript file
-not in the source directory,
-but in the
-.I build_dir ,
-as if
-.B scons
-had made a virtual copy of the source tree
-regardless of the value of 
-.IR duplicate .
-This is how you tell
-.B scons
-which variant of a source tree to build.
-For example:
-
-.ES
-BuildDir('build-variant1', 'src')
-SConscript('build-variant1/SConscript')
-BuildDir('build-variant2', 'src')
-SConscript('build-variant2/SConscript')
-.EE
-
-.IP
-See also the
-.BR SConscript ()
-function, described below,
-for another way to 
-specify a build directory
-in conjunction with calling a subsidiary
-SConscript file.)
+argument bedomes the
+.I variant_dir
+argument of
+.B VariantDir()
+or
+.BR env.VariantDir() .
+(This will be officially deprecated some day.)
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP 
@@ -3005,12 +3018,20 @@ def MyTool(env): env['FOO'] = 'bar'
 env4 = env.Clone(tools = ['msvc', MyTool])
 .EE
 
+The
+.I parse_flags
+keyword argument is also recognized:
+
+.ES
+# create an environment for compiling programs that use wxWidgets
+wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
+.EE
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI env.Copy([ key = val ", ...])"
-A synonym for
+A now-deprecated synonym for
 .BR env.Clone() .
-(This will probably be officially deprecated some day.)
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
@@ -3133,6 +3154,7 @@ and runs the build again,
 all within a single second.
 .RE
 
+.IP
 Examples:
 
 .ES
@@ -3144,12 +3166,14 @@ Decider('timestamp-match')
 env.Decider('content')
 .EE
 
+.IP
 In addition to the above already-available functions,
 the
 .I function
 argument may be an actual Python function
 that takes the following three arguments:
 
+.RS 10
 .IP dependency
 The Node (file) which
 should cause the
@@ -3176,7 +3200,9 @@ This can be consulted to match various
 file characteristics
 such as the timestamp,
 size, or content signature.
+.RE
 
+.IP
 The
 .I function
 should return a
@@ -3322,6 +3348,12 @@ If no
 .I directory
 is specified, the current script's directory is used as the parent.
 
+If 
+.I name
+is a list, SCons returns a list of Dir nodes.
+Construction variables are expanded in
+.IR name .
+
 Directory Nodes can be used anywhere you
 would supply a string as a directory name
 to a Builder method or function.
@@ -3514,6 +3546,12 @@ can be a relative or absolute path.
 .I directory
 is an optional directory that will be used as the parent directory. 
 
+If 
+.I name
+is a list, SCons returns a list of File nodes.
+Construction variables are expanded in
+.IR name .
+
 File Nodes can be used anywhere you
 would supply a string as a file name
 to a Builder method or function.
@@ -3602,6 +3640,7 @@ FindSourceFiles()
 FindSourceFiles( 'src' )
 .EE
 
+.IP
 As you can see build support files (SConstruct in the above example)
 will also be returned by this function.
 
@@ -3632,7 +3671,7 @@ for the following reasons:
 1) The returned list will contain all appropriate directories
 found in source trees
 (when
-.BR BuildDir ()
+.BR VariantDir ()
 is used)
 or in code repositories
 (when
@@ -3841,12 +3880,113 @@ file is found.
 .RI GetOption( name )
 .TP
 .RI env.GetOption( name )
-This function provides a way to query a select subset of the scons command line
-options from a SConscript file. See 
+This function provides a way to query the value of
+SCons options set on scons command line
+(or set using the
 .IR SetOption () 
-for a description of the options available.
+function).
+The options supported are:
 
-""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.RS 10
+.TP 6
+.B cache_debug
+.TP 6
+which corresponds to --cache_debug;
+.TP 6
+.B cache_disable
+which corresponds to --cache_disable;
+.TP 6
+.B cache_force
+which corresponds to --cache_force;
+.TP 6
+.B cache_show
+which corresponds to --cache_show;
+.TP 6
+.B clean
+which corresponds to -c, --clean and --remove;
+.TP 6
+.B config
+which corresponds to --config;
+.TP 6
+.B directory
+which corresponds to -C and --directory;
+.TP 6
+.B diskcheck
+which corresponds to --diskcheck
+.TP 6
+.B duplicate
+which corresponds to --duplicate;
+.TP 6
+.B file
+which corresponds to -f, --file, --makefile and --sconstruct;
+.TP 6
+.B help
+which corresponds to -h and --help;
+.TP 6
+.B ignore_errors
+which corresponds to --ignore-errors;
+.TP 6
+.B implicit_cache
+which corresponds to --implicit-cache;
+.TP 6
+.B implicit_deps_changed
+which corresponds to --implicit-deps-changed;
+.TP 6
+.B implicit_deps_unchanged
+which corresponds to --implicit-deps-unchanged;
+.TP 6
+.B interactive
+which corresponds to --interact and --interactive;
+.TP 6
+.B keep_going
+which corresponds to -k and --keep-going;
+.TP 6
+.B max_drift
+which corresponds to --max-drift;
+.TP 6
+.B no_exec
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+.TP 6
+.B no_site_dir
+which corresponds to --no-site-dir;
+.TP 6
+.B num_jobs
+which corresponds to -j and --jobs;
+.TP 6
+.B profile_file
+which corresponds to --profile;
+.TP 6
+.B question
+which corresponds to -q and --question;
+.TP 6
+.B random
+which corresponds to --random;
+.TP 6
+.B repository
+which corresponds to -Y, --repository and --srcdir;
+.TP 6
+.B silent
+which corresponds to -s, --silent and --quiet;
+.TP 6
+.B site_dir
+which corresponds to --site-dir;
+.TP 6
+.B stack_size
+which corresponds to --stack-size;
+.TP 6
+.B taskmastertrace_file
+which corresponds to --taskmastertrace; and
+.TP 6
+.B warn
+which corresponds to --warn and --warning.
+.RE
+
+.IP
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
 .TP
@@ -3874,6 +4014,7 @@ uses Unix shell style metacharacters for matching:
   [!seq]  matches any char not in seq
 .EE
 
+.IP
 Character matches do
 .I not
 span directory separators.
@@ -3887,7 +4028,7 @@ repositories
 function)
 and source directories
 (see the
-.BR BuildDir ()
+.BR VariantDir ()
 function)
 and
 returns a Node (or string, if so configured)
@@ -3915,7 +4056,7 @@ argument may be set to
 (or any equivalent value)
 to specify that,
 when the local directory is a
-.BR BuildDir (),
+.BR VariantDir (),
 the returned Nodes should be from the
 corresponding source directory,
 not the local directory.
@@ -4100,6 +4241,8 @@ env.MergeFlags('-O3')
 # flag and merge the result into the construction variables.
 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
 
+# Combine an optimization flag with the flags returned from running pkg-config
+# twice and merge the result into the construction variables.
 env.MergeFlags(['-O3',
                '!pkg-config gtk+-2.0 --cflags --libs',
                '!pkg-config libpng12 --cflags --libs'])
@@ -4830,13 +4973,13 @@ for a specific subdirectory.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
 .TP
-.RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
 .TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
 .TP
-.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
 This tells
 .B scons
 to execute
@@ -4895,15 +5038,15 @@ must use the
 function to import the variables.
 
 The optional
-.I build_dir
+.I variant_dir
 argument specifies that all of the target files
 (for example, object files and executables)
 that would normally be built in the subdirectory in which
 .I script
 resides should actually
 be built in
-.IR build_dir .
-.I build_dir
+.IR variant_dir .
+.I variant_dir
 is interpreted relative to the directory
 of the calling SConscript file.
 
@@ -4921,7 +5064,7 @@ of the calling SConscript file.
 By default,
 .B scons
 will link or copy (depending on the platform)
-all the source files into the build directory.
+all the source files into the variant directory tree.
 This behavior may be disabled by
 setting the optional
 .I duplicate
@@ -4954,7 +5097,7 @@ Examples:
 SConscript('subdir/SConscript')
 foo = SConscript('sub/SConscript', exports='env')
 SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript('src/SConscript', build_dir='build', duplicate=0)
+SConscript('src/SConscript', variant_dir='build', duplicate=0)
 SConscript('bld/SConscript', src_dir='src', exports='env variable')
 SConscript(dirs=['sub1', 'sub2'])
 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
@@ -5090,24 +5233,38 @@ if not env.has_key('FOO'): env['FOO'] = 'foo'
 .RI env.SetOption( name ", " value )
 This function provides a way to set a select subset of the scons command
 line options from a SConscript file. The options supported are:
+
+.RS 10
+.TP 6
 .B clean
 which corresponds to -c, --clean and --remove;
+.TP 6
 .B duplicate
 which corresponds to --duplicate;
+.TP 6
 .B help
 which corresponds to -h and --help;
+.TP 6
 .B implicit_cache
 which corresponds to --implicit-cache;
+.TP 6
 .B max_drift
 which corresponds to --max-drift;
+.TP 6
 .B no_exec
 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+.TP 6
 .B num_jobs
 which corresponds to -j and --jobs;
+.TP 6
 .B random
 which corresponds to --random; and
+.TP 6
 .B stack_size
 which corresponds to --stack-size.
+.RE
+
+.IP
 See the documentation for the
 corresponding command line object for information about each specific
 option.
@@ -5733,6 +5890,103 @@ env.UpdateValue(target = Value(output), source = Value(input))
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
+.TP
+.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
+This specifies a variant directory tree
+.I variant_dir
+in which to build all derived files
+that would normally be built under
+.IR src_dir .
+Multiple directory trees
+can be set up for multiple build variants.
+.I src_dir
+must be underneath the SConstruct file's directory,
+and
+.I variant_dir
+may not be underneath the
+.I src_dir .
+
+The default behavior is for
+.B scons
+to duplicate all of the files in the tree underneath
+.I src_dir
+into
+.IR variant_dir ,
+and then build the derived files within the copied tree.
+(The duplication is performed by
+linking or copying,
+depending on the platform; see also the
+.IR --duplicate
+option.)
+This guarantees correct builds
+regardless of whether intermediate source files
+are generated during the build,
+where preprocessors or other scanners search
+for included files,
+or whether individual compilers or other invoked tools
+are hard-coded to put derived files in the same directory as source files.
+
+This behavior of making a complete copy of the source tree
+may be disabled by setting
+.I duplicate
+to 0.
+This will cause
+.B scons
+to invoke Builders using the
+path names of source files in
+.I src_dir
+and the path names of derived files within
+.IR variant_dir .
+This is always more efficient than
+.IR duplicate =1,
+and is usually safe for most builds.
+Specifying
+.IR duplicate =0,
+however,
+may cause build problems
+if source files are generated during the build,
+or if any invoked tools are hard-coded to
+put derived files in the same directory as the source files.
+
+Note that specifying a
+.B VariantDir
+works most naturally
+with a subsidiary SConscript file
+in the source directory.
+However,
+you would then call the subsidiary SConscript file
+not in the source directory,
+but in the
+.I variant_dir ,
+as if
+.B scons
+had made a virtual copy of the source tree
+regardless of the value of 
+.IR duplicate .
+This is how you tell
+.B scons
+which variant of a source tree to build.
+For example:
+
+.ES
+VariantDir('build-variant1', 'src')
+SConscript('build-variant1/SConscript')
+VariantDir('build-variant2', 'src')
+SConscript('build-variant2/SConscript')
+.EE
+
+.IP
+See also the
+.BR SConscript ()
+function, described below,
+for another way to 
+specify a variant directory
+in conjunction with calling a subsidiary
+SConscript file.)
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 .RI WhereIs( program ", [" path  ", " pathext ", " reject ])
 .TP
 .RI env.WhereIs( program ", [" path  ", " pathext ", " reject ])
@@ -6086,9 +6340,9 @@ specifies a file which collects the output from commands
 that are executed to check for the existence of header files, libraries, etc.
 The default is the file #/config.log.
 If you are using the
-.B BuildDir
+.B VariantDir
 method,
-you may want to specify a subdirectory under your build directory.
+you may want to specify a subdirectory under your variant directory.
 .I config_h
 specifies a C header file where the results of tests 
 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc. 
@@ -7116,7 +7370,7 @@ This path is relative to the top-level directory
 .B SConstruct
 file is found).
 The build path is the same as the source path if
-.I build_dir
+.I variant_dir
 is not being used.
 
 .IP abspath
@@ -7152,6 +7406,95 @@ foo = env.Program('foo.c')
 print "foo will be built in %s"%foo.path
 .EE
 
+A
+.I Dir
+Node or
+.I File
+Node can also be used to create
+file and subdirectory Nodes relative to the generating Node.
+A
+.I Dir
+Node will place the new Nodes within the directory it represents.
+A
+.I File
+node will place the new Nodes within its parent directory
+(that is, "beside" the file in question).
+If
+.I d
+is a
+.I Dir
+(directory) Node and
+.I f
+is a
+.I File
+(file) Node,
+then these methods are available:
+
+.TP
+.IR d .Dir( name )
+Returns a directory Node for a subdirectory of
+.I d
+named
+.IR name .
+
+.TP
+.IR d .File( name )
+Returns a file Node for a file within
+.I d
+named
+.IR name .
+
+.TP
+.IR d .Entry( name )
+Returns an unresolved Node within
+.I d
+named
+.IR name .
+
+.TP
+.IR f .Dir( name )
+Returns a directory named
+.I name
+within the parent directory of
+.IR f .
+
+.TP
+.IR f .File( name )
+Returns a file named
+.I name
+within the parent directory of
+.IR f .
+
+.TP
+.IR f .Entry( name )
+Returns an unresolved Node named
+.I name
+within the parent directory of
+.IR f .
+
+.RE
+For example:
+
+.ES
+# Get a Node for a file within a directory
+incl = Dir('include')
+f = incl.File('header.h')
+
+# Get a Node for a subdirectory within a directory
+dist = Dir('project-3.2.1)
+src = dist.Dir('src')
+
+# Get a Node for a file in the same directory
+cfile = File('sample.c')
+hfile = cfile.File('sample.h')
+
+# Combined example
+docs = Dir('docs')
+html = docs.Dir('html')
+index = html.File('index.html')
+css = index.File('app.css')
+.EE
+
 .SH EXTENDING SCONS
 .SS Builder Objects
 .B scons
@@ -8245,24 +8588,24 @@ when a path references a file on other (POSIX) systems.
 
 .IP srcpath
 The directory and file name to the source file linked to this file
-through BuildDir.  If this file isn't linked, it just returns the
+through VariantDir.  If this file isn't linked, it just returns the
 directory and filename unchanged.
 
 .IP srcdir
 The directory containing the source file linked to this file
-through BuildDir.  If this file isn't linked, it just returns the
+through VariantDir.  If this file isn't linked, it just returns the
 directory part of the filename.
 
 .IP rsrcpath
 The directory and file name to the source file linked to this file
-through BuildDir.  If the file does not exist locally but exists in
+through VariantDir.  If the file does not exist locally but exists in
 a Repository, the path in the Repository is returned.
 If this file isn't linked, it just returns the
 directory and filename unchanged.
 
 .IP rsrcdir
 The Repository directory containing the source file linked to this file
-through BuildDir.  If this file isn't linked, it just returns the
+through VariantDir.  If this file isn't linked, it just returns the
 directory part of the filename.
 
 .LP
@@ -8278,7 +8621,7 @@ ${TARGET.filebase}   => file
 ${TARGET.suffix}     => .x
 ${TARGET.abspath}    => /top/dir/sub/dir/file.x
 
-SConscript('src/SConscript', build_dir='sub/dir')
+SConscript('src/SConscript', variant_dir='sub/dir')
 $SOURCE              => sub/dir/file.x
 ${SOURCE.srcpath}    => src/file.x
 ${SOURCE.srcdir}     => src
@@ -9046,21 +9389,21 @@ subdirectory/SConscript:
 
 .SS Building Multiple Variants From the Same Source
 
-Use the build_dir keyword argument to
+Use the variant_dir keyword argument to
 the SConscript function to establish
-one or more separate build directories for
-a given source directory:
+one or more separate variant build directory trees
+for a given source directory:
 
 .ES
 SConstruct:
 
     cppdefines = ['FOO']
     Export("cppdefines")
-    SConscript('src/SConscript', build_dir='foo')
+    SConscript('src/SConscript', variant_dir='foo')
 
     cppdefines = ['BAR']
     Export("cppdefines")
-    SConscript('src/SConscript', build_dir='bar')
+    SConscript('src/SConscript', variant_dir='bar')
 
 src/SConscript:
 
diff --git a/doc/scons.mod b/doc/scons.mod
index e590368..739be58 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -311,6 +311,7 @@
 <!ENTITY exports "<varname>exports</varname>">
 <!ENTITY source "<varname>source</varname>">
 <!ENTITY target "<varname>target</varname>">
+<!ENTITY variant_dir "<varname>variant_dir</varname>">
 
 
 
@@ -351,6 +352,7 @@
 <!ENTITY StaticLibrary "<function>StaticLibrary</function>">
 <!ENTITY StaticObject "<function>StaticObject</function>">
 <!ENTITY Tar "<function>Tar</function>">
+<!ENTITY VariantDir "<function>VariantDir</function>">
 <!ENTITY Zip "<function>Zip</function>">
 
 <!-- Obsolete, but referenced in old documents.  -->
diff --git a/doc/user/java.xml b/doc/user/java.xml
index 1876916..402d037 100644
--- a/doc/user/java.xml
+++ b/doc/user/java.xml
@@ -231,8 +231,8 @@
       % <userinput>scons -Q</userinput>
       javac -d classes -sourcepath prog1 prog1/Example1.java prog1/Example2.java
       javac -d classes -sourcepath prog2 prog2/Example3.java prog2/Example4.java
-      jar cf prog1.jar classes/Example1.class classes/Example2.class
-      jar cf prog2.jar classes/Example3.class classes/Example4.class
+      jar cf prog1.jar -C classes Example1.class -C classes Example2.class
+      jar cf prog2.jar -C classes Example3.class -C classes Example4.class
     </screen>
 
   </section>
diff --git a/doc/user/separate.in b/doc/user/separate.in
index 08bb986..be7e6c5 100644
--- a/doc/user/separate.in
+++ b/doc/user/separate.in
@@ -114,34 +114,46 @@ program using the F<build/foo.c> path name.
 
   It's often useful to keep any built files completely
   separate from the source files.
-  This is usually done by creating one or more separate
-  <emphasis>build directories</emphasis>
+  In &SCons;, this is usually done by creating one or more separate
+  <emphasis>variant directory trees</emphasis>
   that are used to hold the built objects files, libraries,
   and executable programs, etc.
-  for a specific flavor of build.
+  for a specific flavor, or variant, of build.
   &SCons; provides two ways to do this,
   one through the &SConscript; function that we've already seen,
-  and the second through a more flexible &BuildDir; function.
+  and the second through a more flexible &VariantDir; function.
+
+  </para>
+
+  <para>
+
+  One historical note:  the &VariantDir; function
+  used to be called &BuildDir;.
+  That name is still supported
+  but has been deprecated
+  because the &SCons; functionality
+  differs from the model of a "build directory"
+  implemented by other build systems like the GNU Autotools.
 
   </para>
 
   <section>
-  <title>Specifying a Build Directory as Part of an &SConscript; Call</title>
+  <title>Specifying a Variant Directory Tree as Part of an &SConscript; Call</title>
 
     <para>
 
-    The most straightforward way to establish a build directory
+    The most straightforward way to establish a variant directory tree
     uses the fact that the usual way to
     set up a build hierarchy is to have an
     &SConscript; file in the source subdirectory.
-    If you then pass a &build_dir; argument to the
+    If you then pass a &variant_dir; argument to the
     &SConscript; function call:
 
     </para>
 
     <scons_example name="ex1">
       <file name="SConstruct" printme="1">
-      SConscript('src/SConscript', build_dir='build')
+      SConscript('src/SConscript', variant_dir='build')
       </file>
       <file name="src/SConscript">
       env = Environment()
@@ -192,11 +204,11 @@ program using the F<build/foo.c> path name.
   </section>
 
   <section>
-  <title>Why &SCons; Duplicates Source Files in a Build Directory</title>
+  <title>Why &SCons; Duplicates Source Files in a Variant Directory Tree</title>
 
     <para>
 
-    &SCons; duplicates source files in build directories
+    &SCons; duplicates source files in variant directory trees
     because it's the most straightforward way to guarantee a correct build
     <emphasis>regardless of include-file directory paths,
     relative references between files,
@@ -209,14 +221,14 @@ program using the F<build/foo.c> path name.
     <para>
 
     The most direct reason to duplicate source files
-    in build directories
+    in variant directories
     is simply that some tools (mostly older vesions)
     are written to only build their output files
     in the same directory as the source files.
     In this case, the choices are either
     to build the output file in the source directory
-    and move it to the build directory,
-    or to duplicate the source files in the build directory.
+    and move it to the variant directory,
+    or to duplicate the source files in the variant directory.
 
     </para>
 
@@ -226,7 +238,7 @@ program using the F<build/foo.c> path name.
     relative references between files
     can cause problems if we don't
     just duplicate the hierarchy of source files
-    in the build directory.
+    in the variant directory.
     You can see this at work in
     use of the C preprocessor <literal>#include</literal>
     mechanism with double quotes, not angle brackets:
@@ -251,7 +263,7 @@ program using the F<build/foo.c> path name.
     will be found in the same directory hierarchy,
     and the simplest way to make sure
     that the right include file is found
-    is to duplicate the source files into the build directory,
+    is to duplicate the source files into the variant directory,
     which provides a correct build
     regardless of the original location(s) of the source files.
 
@@ -264,14 +276,14 @@ program using the F<build/foo.c> path name.
     it <emphasis>can</emphasis> usually be safely disabled.
     The next section describes
     how you can disable the duplication of source files
-    in the build directory.
+    in the variant directory.
 
     </para>
 
   </section>
 
   <section>
-  <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title>
+  <title>Telling &SCons; to Not Duplicate Source Files in the Variant Directory Tree</title>
 
     <para>
 
@@ -287,15 +299,15 @@ program using the F<build/foo.c> path name.
     </para>
 
     <sconstruct>
-      SConscript('src/SConscript', build_dir='build', duplicate=0)
+      SConscript('src/SConscript', variant_dir='build', duplicate=0)
     </sconstruct>
 
     <para>
 
     When this flag is specified,
-    &SCons; uses the build directory
+    &SCons; uses the variant directory
     like most people expect--that is,
-    the output files are placed in the build directory
+    the output files are placed in the variant directory
     while the source files stay in the source directory:
 
     </para>
@@ -315,11 +327,11 @@ program using the F<build/foo.c> path name.
   </section>
 
   <section>
-  <title>The &BuildDir; Function</title>
+  <title>The &VariantDir; Function</title>
 
     <para>
 
-    Use the &BuildDir; function to establish that target
+    Use the &VariantDir; function to establish that target
     files should be built in a separate directory
     from the source files:
 
@@ -327,7 +339,7 @@ program using the F<build/foo.c> path name.
 
     <scons_example name="ex_builddir">
       <file name="SConstruct" printme="1">
-      BuildDir('build', 'src')
+      VariantDir('build', 'src')
       env = Environment()
       env.Program('build/hello.c')
       </file>
@@ -350,9 +362,9 @@ program using the F<build/foo.c> path name.
 
     <para>
 
-    When using the &BuildDir; function directly,
+    When using the &VariantDir; function directly,
     &SCons; still duplicates the source files
-    in the build directory by default:
+    in the variant directory by default:
 
     </para>
 
@@ -371,7 +383,7 @@ program using the F<build/foo.c> path name.
 
     <scons_example name="ex_duplicate_0">
       <file name="SConstruct" printme="1">
-      BuildDir('build', 'src', duplicate=0)
+      VariantDir('build', 'src', duplicate=0)
       env = Environment()
       env.Program('build/hello.c')
       </file>
@@ -396,11 +408,11 @@ program using the F<build/foo.c> path name.
   </section>
 
   <section>
-  <title>Using &BuildDir; With an &SConscript; File</title>
+  <title>Using &VariantDir; With an &SConscript; File</title>
 
     <para>
 
-    Even when using the &BuildDir; function,
+    Even when using the &VariantDir; function,
     it's much more natural to use it with
     a subsidiary &SConscript; file.
     For example, if the
@@ -411,7 +423,7 @@ program using the F<build/foo.c> path name.
 
     <scons_example name="example_builddir_sconscript">
       <file name="SConstruct">
-      BuildDir('build', 'src')
+      VariantDir('build', 'src')
       SConscript('build/SConscript')
       </file>
       <file name="src/SConscript" printme="1">
@@ -457,11 +469,11 @@ program using the F<build/foo.c> path name.
   <!--
 
   <section>
-  <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title>
+  <title>Why You'd Want to Call &VariantDir; Instead of &SConscript;</title>
 
     <para>
 
-    XXX why call BuildDir() instead of SConscript(build_dir=)
+    XXX why call VariantDir() instead of SConscript(variant_dir=)
 
     </para>
 
diff --git a/doc/user/separate.xml b/doc/user/separate.xml
index 57acd48..57ade04 100644
--- a/doc/user/separate.xml
+++ b/doc/user/separate.xml
@@ -114,33 +114,45 @@ program using the F<build/foo.c> path name.
 
   It's often useful to keep any built files completely
   separate from the source files.
-  This is usually done by creating one or more separate
-  <emphasis>build directories</emphasis>
+  In &SCons;, this is usually done by creating one or more separate
+  <emphasis>variant directory trees</emphasis>
   that are used to hold the built objects files, libraries,
   and executable programs, etc.
-  for a specific flavor of build.
+  for a specific flavor, or variant, of build.
   &SCons; provides two ways to do this,
   one through the &SConscript; function that we've already seen,
-  and the second through a more flexible &BuildDir; function.
+  and the second through a more flexible &VariantDir; function.
+
+  </para>
+
+  <para>
+
+  One historical note:  the &VariantDir; function
+  used to be called &BuildDir;.
+  That name is still supported
+  but has been deprecated
+  because the &SCons; functionality
+  differs from the model of a "build directory"
+  implemented by other build systems like the GNU Autotools.
 
   </para>
 
   <section>
-  <title>Specifying a Build Directory as Part of an &SConscript; Call</title>
+  <title>Specifying a Variant Directory Tree as Part of an &SConscript; Call</title>
 
     <para>
 
-    The most straightforward way to establish a build directory
+    The most straightforward way to establish a variant directory tree
     uses the fact that the usual way to
     set up a build hierarchy is to have an
     &SConscript; file in the source subdirectory.
-    If you then pass a &build_dir; argument to the
+    If you then pass a &variant_dir; argument to the
     &SConscript; function call:
 
     </para>
 
     <programlisting>
-      SConscript('src/SConscript', build_dir='build')
+      SConscript('src/SConscript', variant_dir='build')
     </programlisting>
 
     <para>
@@ -187,11 +199,11 @@ program using the F<build/foo.c> path name.
   </section>
 
   <section>
-  <title>Why &SCons; Duplicates Source Files in a Build Directory</title>
+  <title>Why &SCons; Duplicates Source Files in a Variant Directory Tree</title>
 
     <para>
 
-    &SCons; duplicates source files in build directories
+    &SCons; duplicates source files in variant directory trees
     because it's the most straightforward way to guarantee a correct build
     <emphasis>regardless of include-file directory paths,
     relative references between files,
@@ -204,14 +216,14 @@ program using the F<build/foo.c> path name.
     <para>
 
     The most direct reason to duplicate source files
-    in build directories
+    in variant directories
     is simply that some tools (mostly older vesions)
     are written to only build their output files
     in the same directory as the source files.
     In this case, the choices are either
     to build the output file in the source directory
-    and move it to the build directory,
-    or to duplicate the source files in the build directory.
+    and move it to the variant directory,
+    or to duplicate the source files in the variant directory.
 
     </para>
 
@@ -221,7 +233,7 @@ program using the F<build/foo.c> path name.
     relative references between files
     can cause problems if we don't
     just duplicate the hierarchy of source files
-    in the build directory.
+    in the variant directory.
     You can see this at work in
     use of the C preprocessor <literal>#include</literal>
     mechanism with double quotes, not angle brackets:
@@ -246,7 +258,7 @@ program using the F<build/foo.c> path name.
     will be found in the same directory hierarchy,
     and the simplest way to make sure
     that the right include file is found
-    is to duplicate the source files into the build directory,
+    is to duplicate the source files into the variant directory,
     which provides a correct build
     regardless of the original location(s) of the source files.
 
@@ -259,14 +271,14 @@ program using the F<build/foo.c> path name.
     it <emphasis>can</emphasis> usually be safely disabled.
     The next section describes
     how you can disable the duplication of source files
-    in the build directory.
+    in the variant directory.
 
     </para>
 
   </section>
 
   <section>
-  <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title>
+  <title>Telling &SCons; to Not Duplicate Source Files in the Variant Directory Tree</title>
 
     <para>
 
@@ -282,15 +294,15 @@ program using the F<build/foo.c> path name.
     </para>
 
     <programlisting>
-      SConscript('src/SConscript', build_dir='build', duplicate=0)
+      SConscript('src/SConscript', variant_dir='build', duplicate=0)
     </programlisting>
 
     <para>
 
     When this flag is specified,
-    &SCons; uses the build directory
+    &SCons; uses the variant directory
     like most people expect--that is,
-    the output files are placed in the build directory
+    the output files are placed in the variant directory
     while the source files stay in the source directory:
 
     </para>
@@ -310,18 +322,18 @@ program using the F<build/foo.c> path name.
   </section>
 
   <section>
-  <title>The &BuildDir; Function</title>
+  <title>The &VariantDir; Function</title>
 
     <para>
 
-    Use the &BuildDir; function to establish that target
+    Use the &VariantDir; function to establish that target
     files should be built in a separate directory
     from the source files:
 
     </para>
 
     <programlisting>
-      BuildDir('build', 'src')
+      VariantDir('build', 'src')
       env = Environment()
       env.Program('build/hello.c')
     </programlisting>
@@ -340,9 +352,9 @@ program using the F<build/foo.c> path name.
 
     <para>
 
-    When using the &BuildDir; function directly,
+    When using the &VariantDir; function directly,
     &SCons; still duplicates the source files
-    in the build directory by default:
+    in the variant directory by default:
 
     </para>
 
@@ -364,7 +376,7 @@ program using the F<build/foo.c> path name.
     </para>
 
     <programlisting>
-      BuildDir('build', 'src', duplicate=0)
+      VariantDir('build', 'src', duplicate=0)
       env = Environment()
       env.Program('build/hello.c')
     </programlisting>
@@ -389,11 +401,11 @@ program using the F<build/foo.c> path name.
   </section>
 
   <section>
-  <title>Using &BuildDir; With an &SConscript; File</title>
+  <title>Using &VariantDir; With an &SConscript; File</title>
 
     <para>
 
-    Even when using the &BuildDir; function,
+    Even when using the &VariantDir; function,
     it's much more natural to use it with
     a subsidiary &SConscript; file.
     For example, if the
@@ -415,7 +427,7 @@ program using the F<build/foo.c> path name.
 
     
     <programlisting>
-      BuildDir('build', 'src')
+      VariantDir('build', 'src')
       SConscript('build/SConscript')
       </programlisting>
 
@@ -448,11 +460,11 @@ program using the F<build/foo.c> path name.
   <!--
 
   <section>
-  <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title>
+  <title>Why You'd Want to Call &VariantDir; Instead of &SConscript;</title>
 
     <para>
 
-    XXX why call BuildDir() instead of SConscript(build_dir=)
+    XXX why call VariantDir() instead of SConscript(variant_dir=)
 
     </para>
 
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index ca5ace8..dc90622 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -261,7 +261,7 @@
     <screen>
       % <userinput>scons</userinput>
       scons: Reading SConscript files ...
-      { 'BUILDERS': {'InstallAs': &lt;function InstallAsBuilderWrapper at 0x700000&gt;, 'Install': &lt;function InstallBuilderWrapper at 0x700000&gt;},
+      { 'BUILDERS': {'_InternalInstall': &lt;function InstallBuilderWrapper at 0x700000&gt;, '_InternalInstallAs': &lt;function InstallAsBuilderWrapper at 0x700000&gt;},
         'CONFIGUREDIR': '#/.sconf_temp',
         'CONFIGURELOG': '#/config.log',
         'CPPSUFFIXES': [ '.c',
@@ -293,7 +293,7 @@
         'INSTALL': &lt;function copyFunc at 0x700000&gt;,
         'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
         'LIBPREFIX': 'lib',
-        'LIBPREFIXES': '$LIBPREFIX',
+        'LIBPREFIXES': ['$LIBPREFIX'],
         'LIBSUFFIX': '.a',
         'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'],
         'MAXLINELENGTH': 128072,
@@ -338,7 +338,7 @@
     <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      { 'BUILDERS': {'RES': &lt;SCons.Builder.BuilderBase instance at 0x700000&gt;, 'Object': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, 'InstallAs': &lt;function InstallAsBuilderWrapper at 0x700000&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0x700000&gt;, 'Install': &lt;function InstallBuilderWrapper at 0x700000&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;},
+      { 'BUILDERS': {'_InternalInstall': &lt;function InstallBuilderWrapper at 0x700000&gt;, 'Object': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0x700000&gt;, 'RES': &lt;SCons.Builder.BuilderBase instance at 0x700000&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, '_InternalInstallAs': &lt;function InstallAsBuilderWrapper at 0x700000&gt;},
         'CC': 'cl',
         'CCCOM': &lt;SCons.Action.FunctionAction instance at 0x700000&gt;,
         'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS',
@@ -1115,10 +1115,10 @@
       % <userinput>scons -Q --debug=stacktrace</userinput>
       scons: *** Source `prog.c' not found, needed by target `prog.o'.  Stop.
       scons: internal stack trace:
-        File "bootstrap/src/engine/SCons/Job.py", line 114, in start
-        File "bootstrap/src/engine/SCons/Script/Main.py", line 157, in prepare
+        File "bootstrap/src/engine/SCons/Job.py", line 131, in start
+        File "bootstrap/src/engine/SCons/Script/Main.py", line 169, in prepare
         File "bootstrap/src/engine/SCons/Taskmaster.py", line 169, in prepare
-        File "bootstrap/src/engine/SCons/Node/FS.py", line 2568, in prepare
+        File "bootstrap/src/engine/SCons/Node/FS.py", line 2551, in prepare
         File "bootstrap/src/engine/SCons/Node/__init__.py", line 349, in prepare
     </screen>
 
diff --git a/doc/user/variants.in b/doc/user/variants.in
index 2bdc394..9980b1d 100644
--- a/doc/user/variants.in
+++ b/doc/user/variants.in
@@ -49,7 +49,7 @@ is pretty smart about rebuilding things when you change options.
 
   <para>
 
-  The &build_dir; keyword argument of
+  The &variant_dir; keyword argument of
   the &SConscript; function provides everything
   we need to show how easy it is to create
   variant builds using &SCons;.
@@ -79,7 +79,7 @@ is pretty smart about rebuilding things when you change options.
 
     Export('env')
 
-    env.SConscript('src/SConscript', build_dir='build/$PLATFORM')
+    env.SConscript('src/SConscript', variant_dir='build/$PLATFORM')
     </file>
     <directory name="src"></directory>
     <directory name="src/hello"></directory>
@@ -140,7 +140,7 @@ is pretty smart about rebuilding things when you change options.
     <file name="SConstruct" printme="1">
     env = Environment(OS = ARGUMENTS.get('OS'))
     for os in ['newell', 'post']:
-        SConscript('src/SConscript', build_dir='build/' + os)
+        SConscript('src/SConscript', variant_dir='build/' + os)
     </file>
   </scons_example>
 
diff --git a/doc/user/variants.xml b/doc/user/variants.xml
index 6727859..3b570cd 100644
--- a/doc/user/variants.xml
+++ b/doc/user/variants.xml
@@ -49,7 +49,7 @@ is pretty smart about rebuilding things when you change options.
 
   <para>
 
-  The &build_dir; keyword argument of
+  The &variant_dir; keyword argument of
   the &SConscript; function provides everything
   we need to show how easy it is to create
   variant builds using &SCons;.
@@ -78,7 +78,7 @@ is pretty smart about rebuilding things when you change options.
 
     Export('env')
 
-    env.SConscript('src/SConscript', build_dir='build/$PLATFORM')
+    env.SConscript('src/SConscript', variant_dir='build/$PLATFORM')
   </programlisting>
 
   <para>
@@ -123,7 +123,7 @@ is pretty smart about rebuilding things when you change options.
     <file name="SConstruct" printme="1">
     env = Environment(OS = ARGUMENTS.get('OS'))
     for os in ['newell', 'post']:
-        SConscript('src/SConscript', build_dir='build/' + os)
+        SConscript('src/SConscript', variant_dir='build/' + os)
     </file>
   </scons_example>