diff options
Diffstat (limited to 'src/engine/SCons/Script')
| -rw-r--r-- | src/engine/SCons/Script/Interactive.py | 4 | ||||
| -rw-r--r-- | src/engine/SCons/Script/Main.py | 42 | ||||
| -rw-r--r-- | src/engine/SCons/Script/Main.xml | 134 | ||||
| -rw-r--r-- | src/engine/SCons/Script/MainTests.py | 4 | ||||
| -rw-r--r-- | src/engine/SCons/Script/SConsOptions.py | 118 | ||||
| -rw-r--r-- | src/engine/SCons/Script/SConscript.py | 4 | ||||
| -rw-r--r-- | src/engine/SCons/Script/SConscript.xml | 165 | ||||
| -rw-r--r-- | src/engine/SCons/Script/SConscriptTests.py | 4 | ||||
| -rw-r--r-- | src/engine/SCons/Script/__init__.py | 4 |
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() |