From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- src/engine/SCons/Script/Interactive.py | 4 +- src/engine/SCons/Script/Main.py | 42 +++++--- src/engine/SCons/Script/Main.xml | 134 ++++++++++++++++++++--- src/engine/SCons/Script/MainTests.py | 4 +- src/engine/SCons/Script/SConsOptions.py | 118 +++++++++++++++++---- src/engine/SCons/Script/SConscript.py | 4 +- src/engine/SCons/Script/SConscript.xml | 165 ++++++++++++++++++++++------- src/engine/SCons/Script/SConscriptTests.py | 4 +- src/engine/SCons/Script/__init__.py | 4 +- 9 files changed, 378 insertions(+), 101 deletions(-) (limited to 'src/engine/SCons/Script') 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 @@ + + +%scons; + +%builders-mod; + +%functions-mod; + +%tools-mod; + +%variables-mod; +]> + + + + (arguments) + This function adds a new command-line option to be recognized. The specified arguments @@ -19,7 +39,9 @@ method (with a few additional capabilities noted below); see the documentation for optparse for a thorough discussion of its option-processing capabities. + + In addition to the arguments and values supported by the optparse.add_option() 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. + + If no default= keyword argument is supplied when calling &f-AddOption;, the option will have a default value of None. + + 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 always override a value set by any SConscript file. + + Any specified help= 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. + + Example: + - + AddOption('--prefix', dest='prefix', nargs=1, type='string', @@ -101,7 +132,7 @@ AddOption('--prefix', metavar='DIR', help='installation prefix') env = Environment(PREFIX = GetOption('prefix')) - + @@ -110,6 +141,7 @@ env = Environment(PREFIX = GetOption('prefix')) () + 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: + + .node The node that was being built when the build failure occurred. + + .status The numeric exit status returned by the command or Python function that failed when trying to build the specified Node. + + .errstr 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.) + + .filename The name of the file or directory that actually caused the failure. @@ -158,7 +198,9 @@ but the .filename attribute will be sub/dir. + + .executor 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. + + .action 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. + + .command 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 @@ -200,8 +248,9 @@ standard Python atexit.register() function. Example: + - + 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) - + @@ -219,13 +268,16 @@ atexit.register(print_build_failures) (name) + 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: + + cache_debug @@ -468,10 +520,13 @@ which corresponds to --warn and --warning. + + See the documentation for the corresponding command line object for information about each specific option. + @@ -486,10 +541,13 @@ option. (list_of_strings, [interval, file, overwrite]) + Allows SCons to show progress made during the build by displaying a string or calling a function while evaluating Nodes (e.g. files). + + If the first specified argument is a Python callable (a function or an object that has a __call__() @@ -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.) + + An example of a simple custom progress function that prints a string containing the Node name every 10 Nodes: + - + def my_progress_function(node, *args, **kw): print 'Evaluating node %s!' % node Progress(my_progress_function, interval=10) - + + 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: + - + 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) - + + 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: + - + import sys Progress('.', interval=100, file=sys.stderr) - + + If the string contains the verbatim substring &cv-TARGET;, it will be replaced with the Node. @@ -577,12 +643,14 @@ and the overwrite= keyword argument to make sure the previously-printed file name is overwritten with blank spaces: + - + import sys Progress('$TARGET\r', overwrite=True) - + + 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: + - + Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) - + @@ -604,6 +673,7 @@ Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) (target, ...) + Marks each given target 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;. + + + +(target, ...) + + + +This indicates that each given +target +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;. + + + (name, value) + This function provides a way to set a select subset of the scons command line options from a SConscript file. The options supported are: + + clean @@ -696,15 +789,22 @@ which corresponds to --stack-size. + + See the documentation for the corresponding command line object for information about each specific option. + + Example: + - + SetOption('max_drift', 1) - + + + 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 @@ + + +%scons; + +%builders-mod; + +%functions-mod; + +%tools-mod; + +%variables-mod; +]> + + + + (targets) + 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. + + 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. + + Examples: + - + Default('foo', 'bar', 'baz') env.Default(['a', 'b', 'c']) hello = env.Program('hello', 'hello.c') env.Default(hello) - + + 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. + + The current list of targets added using the &f-Default; function or method is available in the DEFAULT_TARGETS list; see below. + @@ -61,17 +90,21 @@ see below. (major, minor) + Ensure that the Python version is at least major.minor. 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: + - + EnsurePythonVersion(2,2) - + @@ -80,6 +113,7 @@ EnsurePythonVersion(2,2) (major, minor, [revision]) + Ensure that the SCons version is at least major.minor, 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. + + Examples: + - + EnsureSConsVersion(0,14) EnsureSConsVersion(0,96,90) - + @@ -106,6 +143,7 @@ EnsureSConsVersion(0,96,90) ([value]) + This tells &scons; to exit immediately @@ -115,6 +153,7 @@ A default exit value of 0 (zero) is used if no value is specified. + @@ -123,6 +162,7 @@ is used if no value is specified. (vars) + 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. + + Examples: + - + 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}) - + + 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. + @@ -176,6 +221,7 @@ function, below. () + 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. + @@ -196,6 +243,7 @@ file is found. (text) + This specifies help text to be printed if the 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. + @@ -214,6 +263,7 @@ is called. (vars) + 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. + + Examples: + - + Import("env") Import("env", "variable") Import(["env", "variable"]) Import("*") - + @@ -247,6 +300,7 @@ Import("*") ([vars..., stop=]) + 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 + + The optional stop= 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. + + Examples: + - + # 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') - + @@ -300,6 +359,7 @@ Return('val1 val2') + 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. + + 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: - + + 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') - + + 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: - + + 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') - + + The optional exports 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: - + + 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') - + + If the optional variant_dir 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. + + If variant_dir is present, @@ -421,32 +491,40 @@ file resides and the file is evaluated as if it were in the variant_dir directory: - + + SConscript('src/SConscript', variant_dir = 'build') - + + is equivalent to + - + VariantDir('build', 'src') SConscript('build/SConscript') - + + This later paradigm is often used when the sources are in the same directory as the &SConstruct;: + - + SConscript('SConscript', variant_dir = 'build') - + + is equivalent to + - + VariantDir('build', '.') SConscript('build/SConscript') - + + + + Here are some composite examples: + - + # 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') - + - + # 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) - + - + # 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) - + - + # 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) - + + + \ 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() -- cgit v1.2.3