(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 -H or -h 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)