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/Main.xml | 134 ++++++++++++++++++++++++++++++++++----- 1 file changed, 117 insertions(+), 17 deletions(-) (limited to 'src/engine/SCons/Script/Main.xml') 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) - + + + -- cgit v1.2.3