Merge tag 'upstream/2.3.1'

Upstream version 2.3.1

9 files changed, 378 insertions, 101 deletions

diff --git a/src/engine/SCons/Script/Interactive.py b/src/engine/SCons/Script/Interactive.py
index b9a2e1e..1bc4fc8 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, 2011, 2012, 2013 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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  2013/03/03 09:48:35 garyo"
+__revision__ = "src/engine/SCons/Script/Interactive.py  2014/03/02 14:18:15 garyo"
 
 __doc__ = """
 SCons interactive mode
diff --git a/src/engine/SCons/Script/Main.py b/src/engine/SCons/Script/Main.py
index 3f1b407..164c61d 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, 7, 0)
 
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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, 7, 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  2013/03/03 09:48:35 garyo"
+__revision__ = "src/engine/SCons/Script/Main.py  2014/03/02 14:18:15 garyo"
 
 import SCons.compat
 
@@ -79,7 +79,12 @@ def fetch_win32_parallel_msg():
     import SCons.Platform.win32
     return SCons.Platform.win32.parallel_msg
 
-#
+def revert_io():
+    # This call is added to revert stderr and stdout to the original
+    # ones just in case some build rule or something else in the system
+    # has redirected them elsewhere.
+    sys.stderr = sys.__stderr__
+    sys.stdout = sys.__stdout__
 
 class SConsPrintHelpException(Exception):
     pass
@@ -272,6 +277,9 @@ class BuildTask(SCons.Taskmaster.OutOfDateTask):
                (EnvironmentError, SCons.Errors.StopError,
                             SCons.Errors.UserError))):
             type, value, trace = buildError.exc_info
+            if tb and print_stacktrace:
+                sys.stderr.write("scons: internal stack trace:\n")
+                traceback.print_tb(tb, file=sys.stderr)
             traceback.print_exception(type, value, trace)
         elif tb and print_stacktrace:
             sys.stderr.write("scons: internal stack trace:\n")
@@ -622,7 +630,7 @@ def _set_debug_values(options):
     debug_values = options.debug
 
     if "count" in debug_values:
-        # All of the object counts are within "if __debug__:" blocks,
+        # All of the object counts are within "if track_instances:" blocks,
         # which get stripped when running optimized (with python -O or
         # from compiled *.pyo files).  Provide a warning if __debug__ is
         # stripped, so it doesn't just look like --debug=count is broken.
@@ -630,6 +638,7 @@ def _set_debug_values(options):
         if __debug__: enable_count = True
         if enable_count:
             count_stats.enable(sys.stdout)
+            SCons.Debug.track_instances = True
         else:
             msg = "--debug=count is not supported when running SCons\n" + \
                   "\twith the python -O option or optimized (.pyo) modules."
@@ -644,6 +653,8 @@ def _set_debug_values(options):
     if "memory" in debug_values:
         memory_stats.enable(sys.stdout)
     print_objects = ("objects" in debug_values)
+    if print_objects:
+        SCons.Debug.track_instances = True
     if "presub" in debug_values:
         SCons.Action.print_actions_presub = 1
     if "stacktrace" in debug_values:
@@ -983,9 +994,9 @@ def _main(parser):
         # reading SConscript files and haven't started building
         # things yet, stop regardless of whether they used -i or -k
         # or anything else.
+        revert_io()
         sys.stderr.write("scons: *** %s  Stop.\n" % e)
-        exit_status = 2
-        sys.exit(exit_status)
+        sys.exit(2)
     global sconscript_time
     sconscript_time = time.time() - start_time
 
@@ -1063,6 +1074,7 @@ def _main(parser):
     platform = SCons.Platform.platform_module()
 
     if options.interactive:
+        SCons.Node.interactive = True
         SCons.Script.Interactive.interact(fs, OptionsParser, options,
                                           targets, target_top)
 
@@ -1071,6 +1083,8 @@ def _main(parser):
         # Build the targets
         nodes = _build_targets(fs, options, targets, target_top)
         if not nodes:
+            revert_io()
+            print 'Found nothing to build'
             exit_status = 2
 
 def _build_targets(fs, options, targets, target_top):
@@ -1083,12 +1097,14 @@ def _build_targets(fs, options, targets, target_top):
     SCons.Action.print_actions          = not options.silent
     SCons.Action.execute_actions        = not options.no_exec
     SCons.Node.FS.do_store_info         = not options.no_exec
+    SCons.Node.do_store_info            = not options.no_exec
     SCons.SConf.dryrun                  = options.no_exec
 
     if options.diskcheck:
         SCons.Node.FS.set_diskcheck(options.diskcheck)
 
     SCons.CacheDir.cache_enabled = not options.cache_disable
+    SCons.CacheDir.cache_readonly = options.cache_readonly
     SCons.CacheDir.cache_debug = options.cache_debug
     SCons.CacheDir.cache_force = options.cache_force
     SCons.CacheDir.cache_show = options.cache_show
@@ -1298,12 +1314,8 @@ def _exec_main(parser, values):
         prof = Profile()
         try:
             prof.runcall(_main, parser)
-        except SConsPrintHelpException, e:
+        finally:
             prof.dump_stats(options.profile_file)
-            raise e
-        except SystemExit:
-            pass
-        prof.dump_stats(options.profile_file)
     else:
         _main(parser)
 
@@ -1331,7 +1343,7 @@ def main():
         pass
     parts.append(version_string("engine", SCons))
     parts.append(path_string("engine", SCons))
-    parts.append("Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation")
+    parts.append("Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation")
     version = ''.join(parts)
 
     import SConsOptions
@@ -1341,7 +1353,10 @@ def main():
     OptionsParser = parser
 
     try:
-        _exec_main(parser, values)
+        try:
+            _exec_main(parser, values)
+        finally:
+            revert_io()
     except SystemExit, s:
         if s:
             exit_status = s
@@ -1358,6 +1373,7 @@ def main():
         parser.print_help()
         exit_status = 0
     except SCons.Errors.BuildError, e:
+        print e
         exit_status = e.exitstatus
     except:
         # An exception here is likely a builtin Python exception Python
diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml
index 258584a..162dfac 100644
--- a/src/engine/SCons/Script/Main.xml
+++ b/src/engine/SCons/Script/Main.xml
@@ -1,15 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
-Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
 
 This file is processed by the bin/SConsDoc.py module.
 See its __doc__ string for a discussion of the format.
 -->
 
+<!DOCTYPE sconsdoc [
+<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'>
+%scons;
+<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'>
+%builders-mod;
+<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'>
+%functions-mod;
+<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'>
+%tools-mod;
+<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'>
+%variables-mod;
+]>
+
+<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
+
+
 <scons_function name="AddOption">
 <arguments signature="global">
 (arguments)
 </arguments>
 <summary>
+<para>
 This function adds a new command-line option to be recognized.
 The specified
 <varname>arguments</varname>
@@ -19,7 +39,9 @@ method (with a few additional capabilities noted below);
 see the documentation for
 <literal>optparse</literal>
 for a thorough discussion of its option-processing capabities.
+</para>
 
+<para>
 In addition to the arguments and values supported by the
 <function>optparse.add_option</function>()
 method,
@@ -44,14 +66,18 @@ 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.
+</para>
 
+<para>
 If no
 <literal>default=</literal>
 keyword argument is supplied when calling
 &f-AddOption;,
 the option will have a default value of
 <literal>None</literal>.
+</para>
 
+<para>
 Once a new command-line option has been added with
 &f-AddOption;,
 the option value may be accessed using
@@ -69,7 +95,9 @@ Note, however, that a
 value specified on the command line will
 <emphasis>always</emphasis>
 override a value set by any SConscript file.
+</para>
 
+<para>
 Any specified
 <literal>help=</literal>
 strings for the new option(s)
@@ -90,10 +118,13 @@ The options will appear in the help text
 in the order in which the
 &f-AddOption;
 calls occur.
+</para>
 
+<para>
 Example:
+</para>
 
-<example>
+<example_commands>
 AddOption('--prefix',
           dest='prefix',
           nargs=1, type='string',
@@ -101,7 +132,7 @@ AddOption('--prefix',
           metavar='DIR',
           help='installation prefix')
 env = Environment(PREFIX = GetOption('prefix'))
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
@@ -110,6 +141,7 @@ env = Environment(PREFIX = GetOption('prefix'))
 ()
 </arguments>
 <summary>
+<para>
 Returns a list of exceptions for the
 actions that failed while
 attempting to build targets.
@@ -119,17 +151,23 @@ object
 with the following attributes
 that record various aspects
 of the build failure:
+</para>
 
+<para>
 <literal>.node</literal>
 The node that was being built
 when the build failure occurred.
+</para>
 
+<para>
 <literal>.status</literal>
 The numeric exit status
 returned by the command or Python function
 that failed when trying to build the
 specified Node.
+</para>
 
+<para>
 <literal>.errstr</literal>
 The SCons error string
 describing the build failure.
@@ -137,7 +175,9 @@ describing the build failure.
 message like "Error 2"
 to indicate that an executed
 command exited with a status of 2.)
+</para>
 
+<para>
 <literal>.filename</literal>
 The name of the file or
 directory that actually caused the failure.
@@ -158,7 +198,9 @@ but the
 <literal>.filename</literal>
 attribute will be
 <filename>sub/dir</filename>.
+</para>
 
+<para>
 <literal>.executor</literal>
 The SCons Executor object
 for the target Node
@@ -166,21 +208,27 @@ being built.
 This can be used to retrieve
 the construction environment used
 for the failed action.
+</para>
 
+<para>
 <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.
+</para>
 
+<para>
 <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.
+</para>
 
+<para>
 Note that the
 &f-GetBuildFailures;
 function
@@ -200,8 +248,9 @@ standard Python
 <function>atexit.register</function>()
 function.
 Example:
+</para>
 
-<example>
+<example_commands>
 import atexit
 
 def print_build_failures():
@@ -210,7 +259,7 @@ def print_build_failures():
         print "%s failed: %s" % (bf.node, bf.errstr)
 
 atexit.register(print_build_failures)
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
@@ -219,13 +268,16 @@ atexit.register(print_build_failures)
 (name)
 </arguments>
 <summary>
+<para>
 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:
+</para>
 
+<para>
 <variablelist>
 <varlistentry>
 <term><literal>cache_debug</literal></term>
@@ -468,10 +520,13 @@ which corresponds to --warn and --warning.
 </listitem>
 </varlistentry>
 </variablelist>
+</para>
 
+<para>
 See the documentation for the
 corresponding command line object for information about each specific
 option.
+</para>
 </summary>
 </scons_function>
 
@@ -486,10 +541,13 @@ option.
 (list_of_strings, [interval, file, overwrite])
 </arguments>
 <summary>
+<para>
 Allows SCons to show progress made during the build
 by displaying a string or calling a function while
 evaluating Nodes (e.g. files).
+</para>
 
+<para>
 If the first specified argument is a Python callable
 (a function or an object that has a
 <function>__call__</function>()
@@ -509,17 +567,21 @@ 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.)
+</para>
 
+<para>
 An example of a simple custom progress function
 that prints a string containing the Node name
 every 10 Nodes:
+</para>
 
-<example>
+<example_commands>
 def my_progress_function(node, *args, **kw):
     print 'Evaluating node %s!' % node
 Progress(my_progress_function, interval=10)
-</example>
+</example_commands>
 
+<para>
 A more complicated example of a custom progress display object
 that prints a string containing a count
 every 100 evaluated Nodes.
@@ -528,8 +590,9 @@ Note the use of
 (a carriage return)
 at the end so that the string
 will overwrite itself on a display:
+</para>
 
-<example>
+<example_commands>
 import sys
 class ProgressCounter(object):
     count = 0
@@ -537,8 +600,9 @@ class ProgressCounter(object):
         self.count += 100
         sys.stderr.write('Evaluated %s nodes\r' % self.count)
 Progress(ProgressCounter(), interval=100)
-</example>
+</example_commands>
 
+<para>
 If the first argument
 &f-link-Progress;
 is a string,
@@ -554,12 +618,14 @@ argument.
 The following will print a series of dots
 on the error output,
 one dot for every 100 evaluated Nodes:
+</para>
 
-<example>
+<example_commands>
 import sys
 Progress('.', interval=100, file=sys.stderr)
-</example>
+</example_commands>
 
+<para>
 If the string contains the verbatim substring
 &cv-TARGET;,
 it will be replaced with the Node.
@@ -577,12 +643,14 @@ and the
 <literal>overwrite=</literal>
 keyword argument to make sure the previously-printed
 file name is overwritten with blank spaces:
+</para>
 
-<example>
+<example_commands>
 import sys
 Progress('$TARGET\r', overwrite=True)
-</example>
+</example_commands>
 
+<para>
 If the first argument to
 &f-Progress;
 is a list of strings,
@@ -592,10 +660,11 @@ in rotating fashion every
 evaluated Nodes.
 This can be used to implement a "spinner"
 on the user's screen as follows:
+</para>
 
-<example>
+<example_commands>
 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
@@ -604,6 +673,7 @@ Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
 (target, ...)
 </arguments>
 <summary>
+<para>
 Marks each given
 <varname>target</varname>
 as precious so it is not deleted before it is rebuilt. Normally
@@ -611,17 +681,40 @@ as precious so it is not deleted before it is rebuilt. Normally
 deletes a target before building it.
 Multiple targets can be passed in to a single call to
 &f-Precious;.
+</para>
 </summary>
 </scons_function>
 
+<scons_function name="Pseudo">
+<arguments>
+(target, ...)
+</arguments>
+<summary>
+<para>
+This indicates that each given
+<varname>target</varname>
+should not be created by the build rule, and if the target is created,
+an error will be generated. This is similar to the gnu make .PHONY
+target. However, in the vast majority of cases, an
+&f-Alias;
+is more appropriate.
+
+Multiple targets can be passed in to a single call to
+&f-Pseudo;.
+</para>
+</summary>
+</scons_function>
 <scons_function name="SetOption">
 <arguments>
 (name, value)
 </arguments>
 <summary>
+<para>
 This function provides a way to set a select subset of the scons command
 line options from a SConscript file. The options supported are:
+</para>
 
+<para>
 <variablelist>
 <varlistentry>
 <term><literal>clean</literal></term>
@@ -696,15 +789,22 @@ which corresponds to --stack-size.
 </listitem>
 </varlistentry>
 </variablelist>
+</para>
 
+<para>
 See the documentation for the
 corresponding command line object for information about each specific
 option.
+</para>
 
+<para>
 Example:
+</para>
 
-<example>
+<example_commands>
 SetOption('max_drift', 1)
-</example>
+</example_commands>
 </summary>
 </scons_function>
+
+</sconsdoc>
diff --git a/src/engine/SCons/Script/MainTests.py b/src/engine/SCons/Script/MainTests.py
index 592b4d9..25977fa 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, 2011, 2012, 2013 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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  2013/03/03 09:48:35 garyo"
+__revision__ = "src/engine/SCons/Script/MainTests.py  2014/03/02 14:18:15 garyo"
 
 import unittest
 import SCons.Errors
diff --git a/src/engine/SCons/Script/SConsOptions.py b/src/engine/SCons/Script/SConsOptions.py
index 6a6bae3..09f71b7 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, 2011, 2012, 2013 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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  2013/03/03 09:48:35 garyo"
+__revision__ = "src/engine/SCons/Script/SConsOptions.py  2014/03/02 14:18:15 garyo"
 
 import optparse
 import re
@@ -248,7 +248,7 @@ class SConsOption(optparse.Option):
 class SConsOptionGroup(optparse.OptionGroup):
     """
     A subclass for SCons-specific option groups.
-    
+
     The only difference between this and the base class is that we print
     the group's help text flush left, underneath their own title but
     lined up with the normal "SCons Options".
@@ -337,10 +337,75 @@ class SConsOptionParser(optparse.OptionParser):
 
         option.process(opt, value, values, self)
 
+    def reparse_local_options(self):
+        """
+        Re-parse the leftover command-line options stored
+        in self.largs, so that any value overridden on the
+        command line is immediately available if the user turns
+        around and does a GetOption() right away.
+        
+        We mimic the processing of the single args
+        in the original OptionParser._process_args(), but here we
+        allow exact matches for long-opts only (no partial
+        argument names!).
+
+        Else, this would lead to problems in add_local_option()
+        below. When called from there, we try to reparse the
+        command-line arguments that
+          1. haven't been processed so far (self.largs), but
+          2. are possibly not added to the list of options yet.
+          
+        So, when we only have a value for "--myargument" yet,
+        a command-line argument of "--myarg=test" would set it.
+        Responsible for this behaviour is the method
+        _match_long_opt(), which allows for partial matches of
+        the option name, as long as the common prefix appears to
+        be unique.
+        This would lead to further confusion, because we might want
+        to add another option "--myarg" later on (see issue #2929).
+        
+        """
+        rargs = []
+        largs_restore = []
+        # Loop over all remaining arguments
+        skip = False
+        for l in self.largs:
+            if skip:
+                # Accept all remaining arguments as they are
+                largs_restore.append(l)
+            else:
+                if len(l) > 2 and l[0:2] == "--":
+                    # Check long option
+                    lopt = (l,)
+                    if "=" in l:
+                        # Split into option and value
+                        lopt = l.split("=", 1)
+                        
+                    if lopt[0] in self._long_opt:
+                        # Argument is already known
+                        rargs.append('='.join(lopt))
+                    else:
+                        # Not known yet, so reject for now
+                        largs_restore.append('='.join(lopt))
+                else:
+                    if l == "--" or l == "-":
+                        # Stop normal processing and don't
+                        # process the rest of the command-line opts
+                        largs_restore.append(l)
+                        skip = True
+                    else:
+                        rargs.append(l)
+        
+        # Parse the filtered list
+        self.parse_args(rargs, self.values)
+        # Restore the list of remaining arguments for the
+        # next call of AddOption/add_local_option...
+        self.largs = self.largs + largs_restore
+
     def add_local_option(self, *args, **kw):
         """
         Adds a local option to the parser.
-        
+
         This is initiated by a SetOption() call to add a user-defined
         command-line option.  We add the option to a separate option
         group for the local options, creating the group if necessary.
@@ -364,7 +429,7 @@ class SConsOptionParser(optparse.OptionParser):
             # available if the user turns around and does a GetOption()
             # right away.
             setattr(self.values.__defaults__, result.dest, result.default)
-            self.parse_args(self.largs, self.values)
+            self.reparse_local_options()
 
         return result
 
@@ -394,11 +459,11 @@ class SConsIndentedHelpFormatter(optparse.IndentedHelpFormatter):
         out liking:
 
         --  add our own regular expression that doesn't break on hyphens
-            (so things like --no-print-directory don't get broken); 
+            (so things like --no-print-directory don't get broken);
 
         --  wrap the list of options themselves when it's too long
             (the wrapper.fill(opts) call below);
- 
+
         --  set the subsequent_indent when wrapping the help_text.
         """
         # The help for each option consists of two parts:
@@ -564,6 +629,11 @@ def Parser(version):
                   action="store_true",
                   help="Copy already-built targets into the CacheDir.")
 
+    op.add_option('--cache-readonly',
+                  dest='cache_readonly', default=False,
+                  action="store_true",
+                  help="Do not update CacheDir with built targets.")
+
     op.add_option('--cache-show',
                   dest='cache_show', default=False,
                   action="store_true",
@@ -579,8 +649,10 @@ def Parser(version):
         if not value in c_options:
             raise OptionValueError(opt_invalid('config', value, c_options))
         setattr(parser.values, option.dest, value)
+
     opt_config_help = "Controls Configure subsystem: %s." \
                       % ", ".join(config_options)
+
     op.add_option('--config',
                   nargs=1, type="string",
                   dest="config", default="auto",
@@ -606,23 +678,25 @@ def Parser(version):
                      "pdb", "prepare", "presub", "stacktrace",
                      "time"]
 
-    def opt_debug(option, opt, value, parser,
+    def opt_debug(option, opt, value__, parser,
                   debug_options=debug_options,
                   deprecated_debug_options=deprecated_debug_options):
-        if value in debug_options:
-            parser.values.debug.append(value)
-        elif value in deprecated_debug_options.keys():
-            parser.values.debug.append(value)
-            try:
-                parser.values.delayed_warnings
-            except AttributeError:
-                parser.values.delayed_warnings = []
-            msg = deprecated_debug_options[value]
-            w = "The --debug=%s option is deprecated%s." % (value, msg)
-            t = (SCons.Warnings.DeprecatedDebugOptionsWarning, w)
-            parser.values.delayed_warnings.append(t)
-        else:
-            raise OptionValueError(opt_invalid('debug', value, debug_options))
+        for value in value__.split(','):
+            if value in debug_options:
+                parser.values.debug.append(value)
+            elif value in deprecated_debug_options.keys():
+                parser.values.debug.append(value)
+                try:
+                    parser.values.delayed_warnings
+                except AttributeError:
+                    parser.values.delayed_warnings = []
+                msg = deprecated_debug_options[value]
+                w = "The --debug=%s option is deprecated%s." % (value, msg)
+                t = (SCons.Warnings.DeprecatedDebugOptionsWarning, w)
+                parser.values.delayed_warnings.append(t)
+            else:
+                raise OptionValueError(opt_invalid('debug', value, debug_options))
+
     opt_debug_help = "Print various types of debugging information: %s." \
                      % ", ".join(debug_options)
     op.add_option('--debug',
diff --git a/src/engine/SCons/Script/SConscript.py b/src/engine/SCons/Script/SConscript.py
index 59039ea..52aade2 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, 2011, 2012, 2013 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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  2013/03/03 09:48:35 garyo"
+__revision__ = "src/engine/SCons/Script/SConscript.py  2014/03/02 14:18:15 garyo"
 
 import SCons
 import SCons.Action
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
index e30997c..9fab301 100644
--- a/src/engine/SCons/Script/SConscript.xml
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -1,15 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
-Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
 
 This file is processed by the bin/SConsDoc.py module.
 See its __doc__ string for a discussion of the format.
 -->
 
+<!DOCTYPE sconsdoc [
+<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'>
+%scons;
+<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'>
+%builders-mod;
+<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'>
+%functions-mod;
+<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'>
+%tools-mod;
+<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'>
+%variables-mod;
+]>
+
+<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
+
+
 <scons_function name="Default">
 <arguments>
 (targets)
 </arguments>
 <summary>
+<para>
 This specifies a list of default targets,
 which will be built by
 &scons;
@@ -18,7 +38,9 @@ Multiple calls to
 &f-Default;
 are legal,
 and add to the list of default targets.
+</para>
 
+<para>
 Multiple targets should be specified as
 separate arguments to the
 &f-Default;
@@ -27,16 +49,20 @@ method, or as a list.
 will also accept the Node returned by any
 of a construction environment's
 builder methods.
+</para>
 
+<para>
 Examples:
+</para>
 
-<example>
+<example_commands>
 Default('foo', 'bar', 'baz')
 env.Default(['a', 'b', 'c'])
 hello = env.Program('hello', 'hello.c')
 env.Default(hello)
-</example>
+</example_commands>
 
+<para>
 An argument to
 &f-Default;
 of
@@ -46,13 +72,16 @@ Later calls to
 &f-Default;
 will add to the (now empty) default-target list
 like normal.
+</para>
 
+<para>
 The current list of targets added using the
 &f-Default;
 function or method is available in the
 <literal>DEFAULT_TARGETS</literal>
 list;
 see below.
+</para>
 </summary>
 </scons_function>
 
@@ -61,17 +90,21 @@ see below.
 (major, minor)
 </arguments>
 <summary>
+<para>
 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.
+</para>
 
+<para>
 Example:
+</para>
 
-<example>
+<example_commands>
 EnsurePythonVersion(2,2)
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
@@ -80,6 +113,7 @@ EnsurePythonVersion(2,2)
 (major, minor, [revision])
 </arguments>
 <summary>
+<para>
 Ensure that the SCons version is at least
 <varname>major.minor</varname>,
 or
@@ -90,14 +124,17 @@ 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.
+</para>
 
+<para>
 Examples:
+</para>
 
-<example>
+<example_commands>
 EnsureSConsVersion(0,14)
 
 EnsureSConsVersion(0,96,90)
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
@@ -106,6 +143,7 @@ EnsureSConsVersion(0,96,90)
 ([value])
 </arguments>
 <summary>
+<para>
 This tells
 &scons;
 to exit immediately
@@ -115,6 +153,7 @@ A default exit value of
 <literal>0</literal>
 (zero)
 is used if no value is specified.
+</para>
 </summary>
 </scons_function>
 
@@ -123,6 +162,7 @@ is used if no value is specified.
 (vars)
 </arguments>
 <summary>
+<para>
 This tells
 &scons;
 to export a list of variables from the current
@@ -137,10 +177,13 @@ 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.
+</para>
 
+<para>
 Examples:
+</para>
 
-<example>
+<example_commands>
 env = Environment()
 # Make env available for all SConscript files to Import().
 Export("env")
@@ -157,8 +200,9 @@ Export(debug = env)
 
 # Make env available using the name debug:
 Export({"debug":env})
-</example>
+</example_commands>
 
+<para>
 Note that the
 &f-SConscript;
 function supports an
@@ -168,6 +212,7 @@ set of variables to a single SConscript file.
 See the description of the
 &f-SConscript;
 function, below.
+</para>
 </summary>
 </scons_function>
 
@@ -176,6 +221,7 @@ function, below.
 ()
 </arguments>
 <summary>
+<para>
 Returns the absolute path name of the directory from which
 &scons;
 was initially invoked.
@@ -188,6 +234,7 @@ options, which internally
 change to the directory in which the
 &SConstruct;
 file is found.
+</para>
 </summary>
 </scons_function>
 
@@ -196,6 +243,7 @@ file is found.
 (text)
 </arguments>
 <summary>
+<para>
 This specifies help text to be printed if the
 <option>-h</option>
 argument is given to
@@ -206,6 +254,7 @@ is called multiple times, the text is appended together in the order
 that
 &f-Help;
 is called.
+</para>
 </summary>
 </scons_function>
 
@@ -214,6 +263,7 @@ is called.
 (vars)
 </arguments>
 <summary>
+<para>
 This tells
 &scons;
 to import a list of variables into the current SConscript file. This
@@ -230,15 +280,18 @@ 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.
+</para>
 
+<para>
 Examples:
+</para>
 
-<example>
+<example_commands>
 Import("env")
 Import("env", "variable")
 Import(["env", "variable"])
 Import("*")
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
@@ -247,6 +300,7 @@ Import("*")
 ([vars..., stop=])
 </arguments>
 <summary>
+<para>
 By default,
 this stops processing the current SConscript
 file and returns to the calling SConscript file
@@ -256,7 +310,9 @@ string arguments.
 Multiple strings contaning variable names may be passed to
 &f-Return;.
 Any strings that contain white space
+</para>
 
+<para>
 The optional
 <literal>stop=</literal>
 keyword argument may be set to a false value
@@ -271,10 +327,13 @@ are still the values of the variables in the named
 at the point
 &f-Return;
 is called.
+</para>
 
+<para>
 Examples:
+</para>
 
-<example>
+<example_commands>
 # Returns without returning a value.
 Return()
 
@@ -286,7 +345,7 @@ Return("foo", "bar")
 
 # Returns the values of Python variables 'val1' and 'val2'.
 Return('val1 val2')
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
@@ -300,6 +359,7 @@ Return('val1 val2')
 <!-- (dirs=subdirs, [name=script, exports, variant_dir, src_dir, duplicate]) -->
 </arguments>
 <summary>
+<para>
 This tells
 &scons;
 to execute
@@ -311,7 +371,9 @@ will be returned by the call to
 There are two ways to call the
 &f-SConscript;
 function.
+</para>
 
+<para>
 The first way you can call
 &f-SConscript;
 is to explicitly specify one or more
@@ -323,13 +385,15 @@ multiple scripts must be specified as a list
 a function like
 &f-Split;).
 Examples:
-<example>
+</para>
+<example_commands>
 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>
+</example_commands>
 
+<para>
 The second way you can call
 &f-SConscript;
 is to specify a list of (sub)directory names
@@ -349,13 +413,15 @@ by supplying an optional
 keyword argument.
 The first three examples below have the same effect
 as the first three examples above:
-<example>
+</para>
+<example_commands>
 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>
+</example_commands>
 
+<para>
 The optional
 <varname>exports</varname>
 argument provides a list of variable names or a dictionary of
@@ -373,13 +439,15 @@ must use the
 &f-link-Import;
 function to import the variables.
 Examples:
-<example>
+</para>
+<example_commands>
 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>
+</example_commands>
 
+<para>
 If the optional
 <varname>variant_dir</varname>
 argument is present, it causes an effect equivalent to the
@@ -405,7 +473,9 @@ file.
 See the description of the
 &f-VariantDir;
 function below for additional details and restrictions.
+</para>
 
+<para>
 If
 <varname>variant_dir</varname>
 is present,
@@ -421,32 +491,40 @@ file resides and the
 file is evaluated as if it were in the
 <varname>variant_dir</varname>
 directory:
-<example>
+</para>
+<example_commands>
 SConscript('src/SConscript', variant_dir = 'build')
-</example>
+</example_commands>
 
+<para>
 is equivalent to
+</para>
 
-<example>
+<example_commands>
 VariantDir('build', 'src')
 SConscript('build/SConscript')
-</example>
+</example_commands>
 
+<para>
 This later paradigm is often used when the sources are
 in the same directory as the
 &SConstruct;:
+</para>
 
-<example>
+<example_commands>
 SConscript('SConscript', variant_dir = 'build')
-</example>
+</example_commands>
 
+<para>
 is equivalent to
+</para>
 
-<example>
+<example_commands>
 VariantDir('build', '.')
 SConscript('build/SConscript')
-</example>
+</example_commands>
 
+<para>
 <!--
 If
 <varname>variant_dir</varname>
@@ -454,7 +532,8 @@ and"
 <varname>src_dir</varname>
 are both present,
 xxxxx everything is in a state of confusion.
-<example>
+</para>
+<example_commands>
 SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
 runs src/SConscript in build/src, but
 SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
@@ -465,45 +544,53 @@ 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>
+</example_commands>
+<para>
 is equivalent to
-<example>
+</para>
+<example_commands>
 ????????????????
-</example>
+</example_commands>
+<para>
 and what about this alternative?
 TODO??? SConscript('build/SConscript', src_dir='src')
 -->
+</para>
 
+<para>
 Here are some composite examples:
+</para>
 
-<example>
+<example_commands>
 # 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_commands>
 
-<example>
+<example_commands>
 # 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_commands>
 
-<example>
+<example_commands>
 # 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_commands>
 
-<example>
+<example_commands>
 # 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>
+</example_commands>
 </summary>
 </scons_function>
+
+</sconsdoc>
\ No newline at end of file
diff --git a/src/engine/SCons/Script/SConscriptTests.py b/src/engine/SCons/Script/SConscriptTests.py
index eaf7b80..6a2dcda 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, 2011, 2012, 2013 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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  2013/03/03 09:48:35 garyo"
+__revision__ = "src/engine/SCons/Script/SConscriptTests.py  2014/03/02 14:18:15 garyo"
 
 import SCons.Script.SConscript
 
diff --git a/src/engine/SCons/Script/__init__.py b/src/engine/SCons/Script/__init__.py
index 5b3eac8..c27dacd 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, 2011, 2012, 2013 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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  2013/03/03 09:48:35 garyo"
+__revision__ = "src/engine/SCons/Script/__init__.py  2014/03/02 14:18:15 garyo"
 
 import time
 start_time = time.time()