summaryrefslogtreecommitdiff
path: root/src/engine/SCons/Script
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
committerLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
commita3a0ab66f0da855e75e3a0e2acfb8aa106b46510 (patch)
tree5352edff1387c3d7e5a8b49ec56524f085c22782 /src/engine/SCons/Script
parent51fa4e4acb6fc8fc7a2af0fbdc21fd1e8feddb3a (diff)
parent140d836e9cd54fb67b969fd82ef7ed19ba574d40 (diff)
Merge tag 'upstream/2.3.1'
Upstream version 2.3.1
Diffstat (limited to 'src/engine/SCons/Script')
-rw-r--r--src/engine/SCons/Script/Interactive.py4
-rw-r--r--src/engine/SCons/Script/Main.py42
-rw-r--r--src/engine/SCons/Script/Main.xml134
-rw-r--r--src/engine/SCons/Script/MainTests.py4
-rw-r--r--src/engine/SCons/Script/SConsOptions.py118
-rw-r--r--src/engine/SCons/Script/SConscript.py4
-rw-r--r--src/engine/SCons/Script/SConscript.xml165
-rw-r--r--src/engine/SCons/Script/SConscriptTests.py4
-rw-r--r--src/engine/SCons/Script/__init__.py4
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()