From ba4425ab5227fd9597fccd368bffff6bf1032149 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 10 Sep 2011 11:25:53 +0200 Subject: Imported Upstream version 2.1.0 --- src/engine/SCons/Script/Main.xml | 710 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 710 insertions(+) create mode 100644 src/engine/SCons/Script/Main.xml (limited to 'src/engine/SCons/Script/Main.xml') diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml new file mode 100644 index 0000000..9c97826 --- /dev/null +++ b/src/engine/SCons/Script/Main.xml @@ -0,0 +1,710 @@ + + + + +(arguments) + + +This function adds a new command-line option to be recognized. +The specified +arguments +are the same as supported by the standard Python +optparse.add_option() +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, +the SCons +&f-AddOption; +function allows you to set the +nargs +keyword value to +'?' +(a string with just the question mark) +to indicate that the specified long option(s) take(s) an +optional +argument. +When +nargs = '?' +is passed to the +&f-AddOption; +function, the +const +keyword argument +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 +&f-GetOption; +or +env.GetOption(). +The value may also be set, using +&f-SetOption; +or +env.SetOption(), +if conditions in a +&SConscript; +require overriding any default value. +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) +will be displayed by the + +or + +options +(the latter only if no other help text is +specified in the SConscript files). +The help text for the local options specified by +&f-AddOption; +will appear below the SCons options themselves, +under a separate +Local Options +heading. +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', + action='store', + metavar='DIR', + help='installation prefix') +env = Environment(PREFIX = GetOption('prefix')) + + + + + + +() + + +Returns a list of exceptions for the +actions that failed while +attempting to build targets. +Each element in the returned list is a +BuildError +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. +(This is often a generic +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. +This may be different from the +.node +attribute. +For example, +if an attempt to build a target named +sub/dir/target +fails because the +sub/dir +directory could not be created, +then the +.node +attribute will be +sub/dir/target +but the +.filename +attribute will be +sub/dir. + +.executor +The SCons Executor object +for the target Node +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 +will always return an empty list +until any build failure has occurred, +which means that +&f-GetBuildFailures; +will always return an empty list +while the +&SConscript; +files are being read. +Its primary intended use is +for functions that will be +executed before SCons exits +by passing them to the +standard Python +atexit.register() +function. +Example: + + +import atexit + +def print_build_failures(): + from SCons.Script import GetBuildFailures + for bf in GetBuildFailures(): + print "%s failed: %s" % (bf.node, bf.errstr) + +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 + + +which corresponds to --cache-debug; + + + + +cache_disable + + +which corresponds to --cache-disable; + + + + +cache_force + + +which corresponds to --cache-force; + + + + +cache_show + + +which corresponds to --cache-show; + + + + +clean + + +which corresponds to -c, --clean and --remove; + + + + +config + + +which corresponds to --config; + + + + +directory + + +which corresponds to -C and --directory; + + + + +diskcheck + + +which corresponds to --diskcheck + + + + +duplicate + + +which corresponds to --duplicate; + + + + +file + + +which corresponds to -f, --file, --makefile and --sconstruct; + + + + +help + + +which corresponds to -h and --help; + + + + +ignore_errors + + +which corresponds to --ignore-errors; + + + + +implicit_cache + + +which corresponds to --implicit-cache; + + + + +implicit_deps_changed + + +which corresponds to --implicit-deps-changed; + + + + +implicit_deps_unchanged + + +which corresponds to --implicit-deps-unchanged; + + + + +interactive + + +which corresponds to --interact and --interactive; + + + + +keep_going + + +which corresponds to -k and --keep-going; + + + + +max_drift + + +which corresponds to --max-drift; + + + + +no_exec + + +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; + + + + +no_site_dir + + +which corresponds to --no-site-dir; + + + + +num_jobs + + +which corresponds to -j and --jobs; + + + + +profile_file + + +which corresponds to --profile; + + + + +question + + +which corresponds to -q and --question; + + + + +random + + +which corresponds to --random; + + + + +repository + + +which corresponds to -Y, --repository and --srcdir; + + + + +silent + + +which corresponds to -s, --silent and --quiet; + + + + +site_dir + + +which corresponds to --site-dir; + + + + +stack_size + + +which corresponds to --stack-size; + + + + +taskmastertrace_file + + +which corresponds to --taskmastertrace; and + + + + +warn + + +which corresponds to --warn and --warning. + + + + + +See the documentation for the +corresponding command line object for information about each specific +option. + + + + + +(callable, [interval]) + + +(string, [interval, file, overwrite]) + + +(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__() +method), +the function will be called +once every +interval +times a Node is evaluated. +The callable will be passed the evaluated Node +as its only argument. +(For future compatibility, +it's a good idea to also add +*args +and +**kw +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. +Note the use of +\r +(a carriage return) +at the end so that the string +will overwrite itself on a display: + + +import sys +class ProgressCounter(object): + count = 0 + def __call__(self, node, *args, **kw): + 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, +the string will be displayed +every +interval +evaluated Nodes. +The default is to print the string on standard output; +an alternate output stream +may be specified with the +file= +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. +Note that, for performance reasons, this is +not +a regular SCons variable substition, +so you can not use other variables +or use curly braces. +The following example will print the name of +every evaluated Node, +using a +\r +(carriage return) to cause each line to overwritten by the next line, +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, +then each string in the list will be displayed +in rotating fashion every +interval +evaluated Nodes. +This can be used to implement a "spinner" +on the user's screen as follows: + + +Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) + + + + + + +(target, ...) + + +Marks each given +target +as precious so it is not deleted before it is rebuilt. Normally +&scons; +deletes a target before building it. +Multiple targets can be passed in to a single call to +&f-Precious;. + + + + + +(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 + + +which corresponds to -c, --clean and --remove; + + + + +duplicate + + +which corresponds to --duplicate; + + + + +help + + +which corresponds to -h and --help; + + + + +implicit_cache + + +which corresponds to --implicit-cache; + + + + +max_drift + + +which corresponds to --max-drift; + + + + +no_exec + + +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; + + + + +num_jobs + + +which corresponds to -j and --jobs; + + + + +random + + +which corresponds to --random; and + + + + +stack_size + + +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