Imported Upstream version 2.1.0upstream/2.1.0

9 files changed, 1316 insertions, 26 deletions

diff --git a/src/engine/SCons/Script/Interactive.py b/src/engine/SCons/Script/Interactive.py
index e2906d4..f2151fa 100644
--- a/src/engine/SCons/Script/Interactive.py
+++ b/src/engine/SCons/Script/Interactive.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -20,7 +20,7 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-__revision__ = "src/engine/SCons/Script/Interactive.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Script/Interactive.py 5357 2011/09/09 21:31:03 bdeegan"
 
 __doc__ = """
 SCons interactive mode
diff --git a/src/engine/SCons/Script/Main.py b/src/engine/SCons/Script/Main.py
index 31bcff3..2f00e5c 100644
--- a/src/engine/SCons/Script/Main.py
+++ b/src/engine/SCons/Script/Main.py
@@ -13,7 +13,7 @@ it goes here.
 unsupported_python_version = (2, 3, 0)
 deprecated_python_version = (2, 4, 0)
 
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -34,7 +34,7 @@ deprecated_python_version = (2, 4, 0)
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-__revision__ = "src/engine/SCons/Script/Main.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Script/Main.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.compat
 
@@ -60,6 +60,7 @@ import SCons.Errors
 import SCons.Job
 import SCons.Node
 import SCons.Node.FS
+import SCons.Platform
 import SCons.SConf
 import SCons.Script
 import SCons.Taskmaster
@@ -653,6 +654,10 @@ def _set_debug_values(options):
         print_time = 1
     if "tree" in debug_values:
         options.tree_printers.append(TreePrinter())
+    if "prepare" in debug_values:
+        SCons.Taskmaster.print_prepare = 1
+    if "duplicate" in debug_values:
+        SCons.Node.FS.print_duplicate = 1
 
 def _create_path(plist):
     path = '.'
@@ -665,15 +670,15 @@ def _create_path(plist):
 
 def _load_site_scons_dir(topdir, site_dir_name=None):
     """Load the site_scons dir under topdir.
-    Adds site_scons to sys.path, imports site_scons/site_init.py,
-    and adds site_scons/site_tools to default toolpath."""
+    Prepends site_scons to sys.path, imports site_scons/site_init.py,
+    and prepends site_scons/site_tools to default toolpath."""
     if site_dir_name:
         err_if_not_found = True       # user specified: err if missing
     else:
         site_dir_name = "site_scons"
         err_if_not_found = False
         
-    site_dir = os.path.join(topdir.path, site_dir_name)
+    site_dir = os.path.join(topdir, site_dir_name)
     if not os.path.exists(site_dir):
         if err_if_not_found:
             raise SCons.Errors.UserError("site dir %s not found."%site_dir)
@@ -682,11 +687,12 @@ def _load_site_scons_dir(topdir, site_dir_name=None):
     site_init_filename = "site_init.py"
     site_init_modname = "site_init"
     site_tools_dirname = "site_tools"
+    # prepend to sys.path
     sys.path = [os.path.abspath(site_dir)] + sys.path
     site_init_file = os.path.join(site_dir, site_init_filename)
     site_tools_dir = os.path.join(site_dir, site_tools_dirname)
     if os.path.exists(site_init_file):
-        import imp
+        import imp, re
         # TODO(2.4): turn this into try:-except:-finally:
         try:
             try:
@@ -705,14 +711,26 @@ def _load_site_scons_dir(topdir, site_dir_name=None):
                     fmt = 'cannot import site_init.py: missing SCons.Script module %s'
                     raise SCons.Errors.InternalError(fmt % repr(e))
                 try:
+                    sfx = description[0]
+                    modname = os.path.basename(pathname)[:-len(sfx)]
+                    site_m = {"__file__": pathname, "__name__": modname, "__doc__": None}
+                    re_special = re.compile("__[^_]+__")
+                    for k in m.__dict__.keys():
+                        if not re_special.match(k):
+                            site_m[k] = m.__dict__[k]
+
                     # This is the magic.
-                    exec fp in m.__dict__
+                    exec fp in site_m
                 except KeyboardInterrupt:
                     raise
                 except Exception, e:
                     fmt = '*** Error loading site_init file %s:\n'
                     sys.stderr.write(fmt % repr(site_init_file))
                     raise
+                else:
+                    for k in site_m:
+                        if not re_special.match(k):
+                            m.__dict__[k] = site_m[k]
             except KeyboardInterrupt:
                 raise
             except ImportError, e:
@@ -723,7 +741,55 @@ def _load_site_scons_dir(topdir, site_dir_name=None):
             if fp:
                 fp.close()
     if os.path.exists(site_tools_dir):
-        SCons.Tool.DefaultToolpath.append(os.path.abspath(site_tools_dir))
+        # prepend to DefaultToolpath
+        SCons.Tool.DefaultToolpath.insert(0, os.path.abspath(site_tools_dir))
+
+def _load_all_site_scons_dirs(topdir, verbose=None):
+    """Load all of the predefined site_scons dir.
+    Order is significant; we load them in order from most generic
+    (machine-wide) to most specific (topdir).
+    The verbose argument is only for testing.
+    """
+    platform = SCons.Platform.platform_default()
+
+    def homedir(d):
+        return os.path.expanduser('~/'+d)
+
+    if platform == 'win32' or platform == 'cygwin':
+        # Note we use $ here instead of %...% because older
+        # pythons (prior to 2.6?) didn't expand %...% on Windows.
+        # This set of dirs should work on XP, Vista, 7 and later.
+        sysdirs=[
+            os.path.expandvars('$ALLUSERSPROFILE\\Application Data\\scons'),
+            os.path.expandvars('$USERPROFILE\\Local Settings\\Application Data\\scons')]
+        appdatadir = os.path.expandvars('$APPDATA\\scons')
+        if appdatadir not in sysdirs:
+            sysdirs.append(appdatadir)
+        sysdirs.append(homedir('.scons'))
+
+    elif platform == 'darwin':  # MacOS X
+        sysdirs=['/Library/Application Support/SCons',
+                 '/opt/local/share/scons', # (for MacPorts)
+                 '/sw/share/scons', # (for Fink)
+                  homedir('Library/Application Support/SCons'),
+                  homedir('.scons')]
+    elif platform == 'sunos':   # Solaris
+        sysdirs=['/opt/sfw/scons',
+                 '/usr/share/scons',
+                 homedir('.scons')]
+    else:                       # Linux, HPUX, etc.
+        # assume posix-like, i.e. platform == 'posix'
+        sysdirs=['/usr/share/scons',
+                 homedir('.scons')]
+
+    dirs=sysdirs + [topdir]
+    for d in dirs:
+        if verbose:    # this is used by unit tests.
+            print "Loading site dir ", d
+        _load_site_scons_dir(d)
+
+def test_load_all_site_scons_dirs(d):
+    _load_all_site_scons_dirs(d, True)
 
 def version_string(label, module):
     version = module.__version__
@@ -739,6 +805,10 @@ def version_string(label, module):
                   module.__developer__,
                   module.__buildsys__)
 
+def path_string(label, module):
+    path = module.__path__
+    return "\t%s path: %s\n"%(label,path)
+
 def _main(parser):
     global exit_status
     global this_build_status
@@ -860,9 +930,9 @@ def _main(parser):
         progress_display.set_mode(0)
 
     if options.site_dir:
-        _load_site_scons_dir(d, options.site_dir)
+        _load_site_scons_dir(d.path, options.site_dir)
     elif not options.no_site_dir:
-        _load_site_scons_dir(d)
+        _load_all_site_scons_dirs(d.path)
         
     if options.include_dir:
         sys.path = options.include_dir + sys.path
@@ -1258,7 +1328,8 @@ def main():
         # __main__.__version__, hence there is no script version.
         pass 
     parts.append(version_string("engine", SCons))
-    parts.append("Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation")
+    parts.append(path_string("engine", SCons))
+    parts.append("Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation")
     version = ''.join(parts)
 
     import SConsOptions
diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml
new file mode 100644
index 0000000..9c97826
--- /dev/null
+++ b/src/engine/SCons/Script/Main.xml
@@ -0,0 +1,710 @@
+<!--
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
+
+This file is processed by the bin/SConsDoc.py module.
+See its __doc__ string for a discussion of the format.
+-->
+
+<scons_function name="AddOption">
+<arguments signature="global">
+(arguments)
+</arguments>
+<summary>
+This function adds a new command-line option to be recognized.
+The specified
+<varname>arguments</varname>
+are the same as supported by the standard Python
+<function>optparse.add_option</function>()
+method (with a few additional capabilities noted below);
+see the documentation for
+<literal>optparse</literal>
+for a thorough discussion of its option-processing capabities.
+
+In addition to the arguments and values supported by the
+<function>optparse.add_option</function>()
+method,
+the SCons
+&f-AddOption;
+function allows you to set the
+<literal>nargs</literal>
+keyword value to
+<literal>'?'</literal>
+(a string with just the question mark)
+to indicate that the specified long option(s) take(s) an
+<emphasis>optional</emphasis>
+argument.
+When
+<literal>nargs = '?'</literal>
+is passed to the
+&f-AddOption;
+function, the
+<literal>const</literal>
+keyword argument
+may be used to supply the "default"
+value that should be used when the
+option is specified on the command line
+without an explicit argument.
+
+If no
+<literal>default=</literal>
+keyword argument is supplied when calling
+&f-AddOption;,
+the option will have a default value of
+<literal>None</literal>.
+
+Once a new command-line option has been added with
+&f-AddOption;,
+the option value may be accessed using
+&f-GetOption;
+or
+<function>env.GetOption</function>().
+The value may also be set, using
+&f-SetOption;
+or
+<function>env.SetOption</function>(),
+if conditions in a
+&SConscript;
+require overriding any default value.
+Note, however, that a
+value specified on the command line will
+<emphasis>always</emphasis>
+override a value set by any SConscript file.
+
+Any specified
+<literal>help=</literal>
+strings for the new option(s)
+will be displayed by the
+<option>-H</option>
+or
+<option>-h</option>
+options
+(the latter only if no other help text is
+specified in the SConscript files).
+The help text for the local options specified by
+&f-AddOption;
+will appear below the SCons options themselves,
+under a separate
+<literal>Local Options</literal>
+heading.
+The options will appear in the help text
+in the order in which the
+&f-AddOption;
+calls occur.
+
+Example:
+
+<example>
+AddOption('--prefix',
+          dest='prefix',
+          nargs=1, type='string',
+          action='store',
+          metavar='DIR',
+          help='installation prefix')
+env = Environment(PREFIX = GetOption('prefix'))
+</example>
+</summary>
+</scons_function>
+
+<scons_function name="GetBuildFailures">
+<arguments signature="global">
+()
+</arguments>
+<summary>
+Returns a list of exceptions for the
+actions that failed while
+attempting to build targets.
+Each element in the returned list is a
+<classname>BuildError</classname>
+object
+with the following attributes
+that record various aspects
+of the build failure:
+
+<literal>.node</literal>
+The node that was being built
+when the build failure occurred.
+
+<literal>.status</literal>
+The numeric exit status
+returned by the command or Python function
+that failed when trying to build the
+specified Node.
+
+<literal>.errstr</literal>
+The SCons error string
+describing the build failure.
+(This is often a generic
+message like "Error 2"
+to indicate that an executed
+command exited with a status of 2.)
+
+<literal>.filename</literal>
+The name of the file or
+directory that actually caused the failure.
+This may be different from the
+<literal>.node</literal>
+attribute.
+For example,
+if an attempt to build a target named
+<filename>sub/dir/target</filename>
+fails because the
+<filename>sub/dir</filename>
+directory could not be created,
+then the
+<literal>.node</literal>
+attribute will be
+<filename>sub/dir/target</filename>
+but the
+<literal>.filename</literal>
+attribute will be
+<filename>sub/dir</filename>.
+
+<literal>.executor</literal>
+The SCons Executor object
+for the target Node
+being built.
+This can be used to retrieve
+the construction environment used
+for the failed action.
+
+<literal>.action</literal>
+The actual SCons Action object that failed.
+This will be one specific action
+out of the possible list of
+actions that would have been
+executed to build the target.
+
+<literal>.command</literal>
+The actual expanded command that was executed and failed,
+after expansion of
+&cv-link-TARGET;,
+&cv-link-SOURCE;,
+and other construction variables.
+
+Note that the
+&f-GetBuildFailures;
+function
+will always return an empty list
+until any build failure has occurred,
+which means that
+&f-GetBuildFailures;
+will always return an empty list
+while the
+&SConscript;
+files are being read.
+Its primary intended use is
+for functions that will be
+executed before SCons exits
+by passing them to the
+standard Python
+<function>atexit.register</function>()
+function.
+Example:
+
+<example>
+import atexit
+
+def print_build_failures():
+    from SCons.Script import GetBuildFailures
+    for bf in GetBuildFailures():
+        print "%s failed: %s" % (bf.node, bf.errstr)
+
+atexit.register(print_build_failures)
+</example>
+</summary>
+</scons_function>
+
+<scons_function name="GetOption">
+<arguments>
+(name)
+</arguments>
+<summary>
+This function provides a way to query the value of
+SCons options set on scons command line
+(or set using the
+&f-link-SetOption;
+function).
+The options supported are:
+
+<variablelist>
+<varlistentry>
+<term><literal>cache_debug</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-debug;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>cache_disable</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-disable;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>cache_force</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-force;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>cache_show</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-show;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>clean</literal></term>
+<listitem>
+<para>
+which corresponds to -c, --clean and --remove;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>config</literal></term>
+<listitem>
+<para>
+which corresponds to --config;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>directory</literal></term>
+<listitem>
+<para>
+which corresponds to -C and --directory;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>diskcheck</literal></term>
+<listitem>
+<para>
+which corresponds to --diskcheck
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>duplicate</literal></term>
+<listitem>
+<para>
+which corresponds to --duplicate;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>file</literal></term>
+<listitem>
+<para>
+which corresponds to -f, --file, --makefile and --sconstruct;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>help</literal></term>
+<listitem>
+<para>
+which corresponds to -h and --help;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>ignore_errors</literal></term>
+<listitem>
+<para>
+which corresponds to --ignore-errors;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_cache</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-cache;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_deps_changed</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-deps-changed;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_deps_unchanged</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-deps-unchanged;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>interactive</literal></term>
+<listitem>
+<para>
+which corresponds to --interact and --interactive;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>keep_going</literal></term>
+<listitem>
+<para>
+which corresponds to -k and --keep-going;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>max_drift</literal></term>
+<listitem>
+<para>
+which corresponds to --max-drift;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>no_exec</literal></term>
+<listitem>
+<para>
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>no_site_dir</literal></term>
+<listitem>
+<para>
+which corresponds to --no-site-dir;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>num_jobs</literal></term>
+<listitem>
+<para>
+which corresponds to -j and --jobs;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>profile_file</literal></term>
+<listitem>
+<para>
+which corresponds to --profile;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>question</literal></term>
+<listitem>
+<para>
+which corresponds to -q and --question;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>random</literal></term>
+<listitem>
+<para>
+which corresponds to --random;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>repository</literal></term>
+<listitem>
+<para>
+which corresponds to -Y, --repository and --srcdir;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>silent</literal></term>
+<listitem>
+<para>
+which corresponds to -s, --silent and --quiet;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>site_dir</literal></term>
+<listitem>
+<para>
+which corresponds to --site-dir;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>stack_size</literal></term>
+<listitem>
+<para>
+which corresponds to --stack-size;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>taskmastertrace_file</literal></term>
+<listitem>
+<para>
+which corresponds to --taskmastertrace; and
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>warn</literal></term>
+<listitem>
+<para>
+which corresponds to --warn and --warning.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+</summary>
+</scons_function>
+
+<scons_function name="Progress">
+<arguments signature="global">
+(callable, [interval])
+</arguments>
+<arguments signature="global">
+(string, [interval, file, overwrite])
+</arguments>
+<arguments signature="global">
+(list_of_strings, [interval, file, overwrite])
+</arguments>
+<summary>
+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
+<function>__call__</function>()
+method),
+the function will be called
+once every
+<varname>interval</varname>
+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
+<literal>*args</literal>
+and
+<literal>**kw</literal>
+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:
+
+<example>
+def my_progress_function(node, *args, **kw):
+    print 'Evaluating node %s!' % node
+Progress(my_progress_function, interval=10)
+</example>
+
+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
+<literal>\r</literal>
+(a carriage return)
+at the end so that the string
+will overwrite itself on a display:
+
+<example>
+import sys
+class ProgressCounter(object):
+    count = 0
+    def __call__(self, node, *args, **kw):
+        self.count += 100
+        sys.stderr.write('Evaluated %s nodes\r' % self.count)
+Progress(ProgressCounter(), interval=100)
+</example>
+
+If the first argument
+&f-link-Progress;
+is a string,
+the string will be displayed
+every
+<varname>interval</varname>
+evaluated Nodes.
+The default is to print the string on standard output;
+an alternate output stream
+may be specified with the
+<literal>file=</literal>
+argument.
+The following will print a series of dots
+on the error output,
+one dot for every 100 evaluated Nodes:
+
+<example>
+import sys
+Progress('.', interval=100, file=sys.stderr)
+</example>
+
+If the string contains the verbatim substring
+&cv-TARGET;,
+it will be replaced with the Node.
+Note that, for performance reasons, this is
+<emphasis>not</emphasis>
+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
+<literal>\r</literal>
+(carriage return) to cause each line to overwritten by the next line,
+and the
+<literal>overwrite=</literal>
+keyword argument to make sure the previously-printed
+file name is overwritten with blank spaces:
+
+<example>
+import sys
+Progress('$TARGET\r', overwrite=True)
+</example>
+
+If the first argument to
+&f-Progress;
+is a list of strings,
+then each string in the list will be displayed
+in rotating fashion every
+<varname>interval</varname>
+evaluated Nodes.
+This can be used to implement a "spinner"
+on the user's screen as follows:
+
+<example>
+Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
+</example>
+</summary>
+</scons_function>
+
+<scons_function name="Precious">
+<arguments>
+(target, ...)
+</arguments>
+<summary>
+Marks each given
+<varname>target</varname>
+as precious so it is not deleted before it is rebuilt. Normally
+&scons;
+deletes a target before building it.
+Multiple targets can be passed in to a single call to
+&f-Precious;.
+</summary>
+</scons_function>
+
+<scons_function name="SetOption">
+<arguments>
+(name, value)
+</arguments>
+<summary>
+This function provides a way to set a select subset of the scons command
+line options from a SConscript file. The options supported are:
+
+<variablelist>
+<varlistentry>
+<term><literal>clean</literal></term>
+<listitem>
+<para>
+which corresponds to -c, --clean and --remove;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>duplicate</literal></term>
+<listitem>
+<para>
+which corresponds to --duplicate;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>help</literal></term>
+<listitem>
+<para>
+which corresponds to -h and --help;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_cache</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-cache;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>max_drift</literal></term>
+<listitem>
+<para>
+which corresponds to --max-drift;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>no_exec</literal></term>
+<listitem>
+<para>
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>num_jobs</literal></term>
+<listitem>
+<para>
+which corresponds to -j and --jobs;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>random</literal></term>
+<listitem>
+<para>
+which corresponds to --random; and
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>stack_size</literal></term>
+<listitem>
+<para>
+which corresponds to --stack-size.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+
+Example:
+
+<example>
+SetOption('max_drift', 1)
+</example>
+</summary>
+</scons_function>
diff --git a/src/engine/SCons/Script/MainTests.py b/src/engine/SCons/Script/MainTests.py
index 923f791..06780d8 100644
--- a/src/engine/SCons/Script/MainTests.py
+++ b/src/engine/SCons/Script/MainTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Script/MainTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Script/MainTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import unittest
 import SCons.Errors
diff --git a/src/engine/SCons/Script/SConsOptions.py b/src/engine/SCons/Script/SConsOptions.py
index 8afedf6..79d9927 100644
--- a/src/engine/SCons/Script/SConsOptions.py
+++ b/src/engine/SCons/Script/SConsOptions.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Script/SConsOptions.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Script/SConsOptions.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import optparse
 import re
@@ -596,9 +596,9 @@ def Parser(version):
         "tree"          : '; please use --tree=all instead',
     }
 
-    debug_options = ["count", "explain", "findlibs",
+    debug_options = ["count", "duplicate", "explain", "findlibs",
                      "includes", "memoizer", "memory", "objects",
-                     "pdb", "presub", "stacktrace",
+                     "pdb", "prepare", "presub", "stacktrace",
                      "time"] + list(deprecated_debug_options.keys())
 
     def opt_debug(option, opt, value, parser,
@@ -867,7 +867,7 @@ def Parser(version):
         sys.stderr.write(msg)
 
     op.add_option('-l', '--load-average', '--max-load',
-                  nargs=1, type="int",
+                  nargs=1, type="float",
                   dest="load_average", default=0,
                   action="callback", callback=opt_not_yet,
                   # action="store",
diff --git a/src/engine/SCons/Script/SConscript.py b/src/engine/SCons/Script/SConscript.py
index 5e896f1..ee5e290 100644
--- a/src/engine/SCons/Script/SConscript.py
+++ b/src/engine/SCons/Script/SConscript.py
@@ -6,7 +6,7 @@ files.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -28,7 +28,7 @@ files.
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 from __future__ import division
 
-__revision__ = "src/engine/SCons/Script/SConscript.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Script/SConscript.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons
 import SCons.Action
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
new file mode 100644
index 0000000..f24ca78
--- /dev/null
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -0,0 +1,509 @@
+<!--
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
+
+This file is processed by the bin/SConsDoc.py module.
+See its __doc__ string for a discussion of the format.
+-->
+
+<scons_function name="Default">
+<arguments>
+(targets)
+</arguments>
+<summary>
+This specifies a list of default targets,
+which will be built by
+&scons;
+if no explicit targets are given on the command line.
+Multiple calls to
+&f-Default;
+are legal,
+and add to the list of default targets.
+
+Multiple targets should be specified as
+separate arguments to the
+&f-Default;
+method, or as a list.
+&f-Default;
+will also accept the Node returned by any
+of a construction environment's
+builder methods.
+
+Examples:
+
+<example>
+Default('foo', 'bar', 'baz')
+env.Default(['a', 'b', 'c'])
+hello = env.Program('hello', 'hello.c')
+env.Default(hello)
+</example>
+
+An argument to
+&f-Default;
+of
+<literal>None</literal>
+will clear all default targets.
+Later calls to
+&f-Default;
+will add to the (now empty) default-target list
+like normal.
+
+The current list of targets added using the
+&f-Default;
+function or method is available in the
+<literal>DEFAULT_TARGETS</literal>
+list;
+see below.
+</summary>
+</scons_function>
+
+<scons_function name="EnsurePythonVersion">
+<arguments>
+(major, minor)
+</arguments>
+<summary>
+Ensure that the Python version is at least
+<varname>major</varname>.<varname>minor</varname>.
+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:
+
+<example>
+EnsurePythonVersion(2,2)
+</example>
+</summary>
+</scons_function>
+
+<scons_function name="EnsureSConsVersion">
+<arguments>
+(major, minor, [revision])
+</arguments>
+<summary>
+Ensure that the SCons version is at least
+<varname>major.minor</varname>,
+or
+<varname>major.minor.revision</varname>.
+if
+<varname>revision</varname>
+is specified.
+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:
+
+<example>
+EnsureSConsVersion(0,14)
+
+EnsureSConsVersion(0,96,90)
+</example>
+</summary>
+</scons_function>
+
+<scons_function name="Exit">
+<arguments>
+([value])
+</arguments>
+<summary>
+This tells
+&scons;
+to exit immediately
+with the specified
+<varname>value</varname>.
+A default exit value of
+<literal>0</literal>
+(zero)
+is used if no value is specified.
+</summary>
+</scons_function>
+
+<scons_function name="Export">
+<arguments>
+(vars)
+</arguments>
+<summary>
+This tells
+&scons;
+to export a list of variables from the current
+SConscript file to all other SConscript files.
+The exported variables are kept in a global collection,
+so subsequent calls to
+&f-Export;
+will over-write previous exports that have the same name.
+Multiple variable names can be passed to
+&f-Export;
+as separate arguments or as a list.
+Keyword arguments can be used to provide names and their values.
+A dictionary can be used to map variables to a different name when exported.
+Both local variables and global variables can be exported.
+
+Examples:
+
+<example>
+env = Environment()
+# Make env available for all SConscript files to Import().
+Export("env")
+
+package = 'my_name'
+# Make env and package available for all SConscript files:.
+Export("env", "package")
+
+# Make env and package available for all SConscript files:
+Export(["env", "package"])
+
+# Make env available using the name debug:
+Export(debug = env)
+
+# Make env available using the name debug:
+Export({"debug":env})
+</example>
+
+Note that the
+&f-SConscript;
+function supports an
+<varname>exports</varname>
+argument that makes it easier to to export a variable or
+set of variables to a single SConscript file.
+See the description of the
+&f-SConscript;
+function, below.
+</summary>
+</scons_function>
+
+<scons_function name="GetLaunchDir">
+<arguments>
+()
+</arguments>
+<summary>
+Returns the absolute path name of the directory from which
+&scons;
+was initially invoked.
+This can be useful when using the
+<option>-u</option>,
+<option>-U</option>
+or
+<option>-D</option>
+options, which internally
+change to the directory in which the
+&SConstruct;
+file is found.
+</summary>
+</scons_function>
+
+<scons_function name="Help">
+<arguments>
+(text)
+</arguments>
+<summary>
+This specifies help text to be printed if the
+<option>-h</option>
+argument is given to
+&scons;.
+If
+&f-Help;
+is called multiple times, the text is appended together in the order
+that
+&f-Help;
+is called.
+</summary>
+</scons_function>
+
+<scons_function name="Import">
+<arguments>
+(vars)
+</arguments>
+<summary>
+This tells
+&scons;
+to import a list of variables into the current SConscript file. This
+will import variables that were exported with
+&f-Export;
+or in the
+<varname>exports</varname>
+argument to
+&f-link-SConscript;.
+Variables exported by
+&f-SConscript;
+have precedence.
+Multiple variable names can be passed to
+&f-Import;
+as separate arguments or as a list. The variable "*" can be used
+to import all variables.
+
+Examples:
+
+<example>
+Import("env")
+Import("env", "variable")
+Import(["env", "variable"])
+Import("*")
+</example>
+</summary>
+</scons_function>
+
+<scons_function name="Return">
+<arguments signature="global">
+([vars..., stop=])
+</arguments>
+<summary>
+By default,
+this stops processing the current SConscript
+file and returns to the calling SConscript file
+the values of the variables named in the
+<varname>vars</varname>
+string arguments.
+Multiple strings contaning variable names may be passed to
+&f-Return;.
+Any strings that contain white space
+
+The optional
+<literal>stop=</literal>
+keyword argument may be set to a false value
+to continue processing the rest of the SConscript
+file after the
+&f-Return;
+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
+<varname>vars</varname>
+at the point
+&f-Return;
+is called.
+
+Examples:
+
+<example>
+# Returns without returning a value.
+Return()
+
+# Returns the value of the 'foo' Python variable.
+Return("foo")
+
+# 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')
+</example>
+</summary>
+</scons_function>
+
+<scons_function name="SConscript">
+<arguments>
+(scripts, [exports, variant_dir, duplicate])
+<!-- (scripts, [exports, variant_dir, src_dir, duplicate]) -->
+</arguments>
+<arguments>
+(dirs=subdirs, [name=script, exports, variant_dir, duplicate])
+<!-- (dirs=subdirs, [name=script, exports, variant_dir, src_dir, duplicate]) -->
+</arguments>
+<summary>
+This tells
+&scons;
+to execute
+one or more subsidiary SConscript (configuration) files.
+Any variables returned by a called script using
+&f-link-Return;
+will be returned by the call to
+&f-SConscript;.
+There are two ways to call the
+&f-SConscript;
+function.
+
+The first way you can call
+&f-SConscript;
+is to explicitly specify one or more
+<varname>scripts</varname>
+as the first argument.
+A single script may be specified as a string;
+multiple scripts must be specified as a list
+(either explicitly or as created by
+a function like
+&f-Split;).
+Examples:
+<example>
+SConscript('SConscript')      # run SConscript in the current directory
+SConscript('src/SConscript')  # run SConscript in the src directory
+SConscript(['src/SConscript', 'doc/SConscript'])
+config = SConscript('MyConfig.py')
+</example>
+
+The second way you can call
+&f-SConscript;
+is to specify a list of (sub)directory names
+as a
+<literal>dirs=</literal><varname>subdirs</varname>
+keyword argument.
+In this case,
+&scons;
+will, by default,
+execute a subsidiary configuration file named
+&SConscript;
+in each of the specified directories.
+You may specify a name other than
+&SConscript;
+by supplying an optional
+<literal>name=</literal><varname>script</varname>
+keyword argument.
+The first three examples below have the same effect
+as the first three examples above:
+<example>
+SConscript(dirs='.')      # run SConscript in the current directory
+SConscript(dirs='src')    # run SConscript in the src directory
+SConscript(dirs=['src', 'doc'])
+SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
+</example>
+
+The optional
+<varname>exports</varname>
+argument provides a list of variable names or a dictionary of
+named values to export to the
+<varname>script(s)</varname>.
+These variables are locally exported only to the specified
+<varname>script(s)</varname>,
+and do not affect the global pool of variables used by the
+&f-Export;
+function.
+<!-- If multiple dirs are provided, each script gets a fresh export. -->
+The subsidiary
+<varname>script(s)</varname>
+must use the
+&f-link-Import;
+function to import the variables.
+Examples:
+<example>
+foo = SConscript('sub/SConscript', exports='env')
+SConscript('dir/SConscript', exports=['env', 'variable'])
+SConscript(dirs='subdir', exports='env variable')
+SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
+</example>
+
+If the optional
+<varname>variant_dir</varname>
+argument is present, it causes an effect equivalent to the
+&f-link-VariantDir;
+method described below.
+(If
+<varname>variant_dir</varname>
+is not present, the
+<!-- <varname>src_dir</varname> and -->
+<varname>duplicate</varname>
+<!-- arguments are ignored.) -->
+argument is ignored.)
+The
+<varname>variant_dir</varname>
+<!--
+and
+<varname>src_dir</varname>
+arguments are interpreted relative to the directory of the calling
+-->
+argument is interpreted relative to the directory of the calling
+&SConscript;
+file.
+See the description of the
+&f-VariantDir;
+function below for additional details and restrictions.
+
+If
+<varname>variant_dir</varname>
+is present,
+<!--
+but
+<varname>src_dir</varname>
+is not,
+-->
+the source directory is the directory in which the
+&SConscript;
+file resides and the
+&SConscript;
+file is evaluated as if it were in the
+<varname>variant_dir</varname>
+directory:
+<example>
+SConscript('src/SConscript', variant_dir = 'build')
+</example>
+
+is equivalent to
+
+<example>
+VariantDir('build', 'src')
+SConscript('build/SConscript')
+</example>
+
+This later paradigm is often used when the sources are
+in the same directory as the
+&SConstruct;:
+
+<example>
+SConscript('SConscript', variant_dir = 'build')
+</example>
+
+is equivalent to
+
+<example>
+VariantDir('build', '.')
+SConscript('build/SConscript')
+</example>
+
+<!--
+If
+<varname>variant_dir</varname>
+and"
+<varname>src_dir</varname>
+are both present,
+xxxxx everything is in a state of confusion.
+<example>
+SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
+runs src/SConscript in build/src, but
+SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
+runs lib/SConscript (in lib!).  However,
+SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
+runs src/SConscript in build.  Moreover,
+SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
+runs src/lib/SConscript in build/lib.  Moreover,
+SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
+can't find build/src/lib/SConscript, even though it ought to exist.
+</example>
+is equivalent to
+<example>
+????????????????
+</example>
+and what about this alternative?
+TODO??? SConscript('build/SConscript', src_dir='src')
+-->
+
+Here are some composite examples:
+
+<example>
+# collect the configuration information and use it to build src and doc
+shared_info = SConscript('MyConfig.py')
+SConscript('src/SConscript', exports='shared_info')
+SConscript('doc/SConscript', exports='shared_info')
+</example>
+
+<example>
+# build debugging and production versions.  SConscript
+# can use Dir('.').path to determine variant.
+SConscript('SConscript', variant_dir='debug', duplicate=0)
+SConscript('SConscript', variant_dir='prod', duplicate=0)
+</example>
+
+<example>
+# build debugging and production versions.  SConscript
+# is passed flags to use.
+opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
+SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
+opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
+SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
+</example>
+
+<example>
+# build common documentation and compile for different architectures
+SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
+SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
+SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
+</example>
+</summary>
+</scons_function>
diff --git a/src/engine/SCons/Script/SConscriptTests.py b/src/engine/SCons/Script/SConscriptTests.py
index 6d855ef..ebd89fc 100644
--- a/src/engine/SCons/Script/SConscriptTests.py
+++ b/src/engine/SCons/Script/SConscriptTests.py
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Script/SConscriptTests.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Script/SConscriptTests.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import SCons.Script.SConscript
 
diff --git a/src/engine/SCons/Script/__init__.py b/src/engine/SCons/Script/__init__.py
index b4545ec..f2503ae 100644
--- a/src/engine/SCons/Script/__init__.py
+++ b/src/engine/SCons/Script/__init__.py
@@ -12,7 +12,7 @@ it goes here.
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -34,7 +34,7 @@ it goes here.
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Script/__init__.py 5134 2010/08/16 23:02:40 bdeegan"
+__revision__ = "src/engine/SCons/Script/__init__.py 5357 2011/09/09 21:31:03 bdeegan"
 
 import time
 start_time = time.time()