%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> (arguments)

Adds a local (project-specific) command-line option. arguments are the same as those supported by the add_option method in the standard Python library module optparse, 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, &f-AddOption; allows setting the nargs keyword value to a string consisting of a question mark ('?') to indicate that the option argument for that option string is optional. If the option string is present on the command line but has no matching option argument, the value of the const keyword argument is produced as the value of the option. If the option string is omitted from the command line, the value of the default keyword argument is produced, as usual; if there is no default keyword argument in the &f-AddOption; call, None is produced. optparse recognizes abbreviations of long option names, as long as they can be unambiguously resolved. For example, if add_option is called to define a --devicename option, it will recognize --device, --dev and so forth as long as there is no other option which could also match to the same abbreviation. Options added via &f-AddOption; do not support the automatic recognition of abbreviations. Instead, to allow specific abbreviations, include them as synonyms in the &f-AddOption; call itself. Once a new command-line option has been added with &f-AddOption;, the option value may be accessed using &f-link-GetOption; or &f-link-env-GetOption;. &f-link-SetOption; is not currently supported for options added with &f-AddOption;. Help text for an option is a combination of the string supplied in the help keyword argument to &f-AddOption; and information collected from the other keyword arguments. Such help is displayed if the -h command line option is used (but not with -H). Help for all local options is displayed under the separate heading Local Options. The options are unsorted - they 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')) For that example, the following help text would be produced: Local Options: --prefix=DIR installation prefix Help text for local options may be unavailable if the &f-link-Help; function has been called, see the &f-Help; documentation for details. As an artifact of the internal implementation, the behavior of options added by &AddOption; which take option arguments is undefined if whitespace (rather than an = sign) is used as the separator on the command line. Users should avoid such usage; it is recommended to add a note to this effect to project documentation if the situation is likely to arise. In addition, if the nargs keyword is used to specify more than one following option argument (that is, with a value of 2 or greater), such arguments would necessarily be whitespace separated, triggering the issue. Developers should not use &AddOption; this way. Future versions of &SCons; will likely forbid such usage.

()

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 options which can be set via the command line or using the &f-link-SetOption; function. name can be an entry from the following table, which shows the corresponding command line arguments that could affect the value. name can be also be the destination variable name from a project-specific option added using the &f-link-AddOption; function, as long as the addition happens prior to the &f-GetOption; call in the SConscript files. Query name Command-line options Notes cache_debug --cache-debug cache_disable --cache-disable, --no-cache cache_force --cache-force, --cache-populate cache_readonly --cache-readonly cache_show --cache-show clean -c, --clean, --remove climb_up -D -U -u --up --search_up config --config debug --debug directory -C, --directory diskcheck --diskcheck duplicate --duplicate enable_virtualenv --enable-virtualenv experimental --experimental since 4.2 file -f, --file, --makefile, --sconstruct hash_format --hash-format since 4.2 help -h, --help ignore_errors -i, --ignore-errors ignore_virtualenv --ignore-virtualenv implicit_cache --implicit-cache implicit_deps_changed --implicit-deps-changed implicit_deps_unchanged --implicit-deps-unchanged include_dir -I, --include-dir install_sandbox --install-sandbox Available only if the &t-link-install; tool has been called keep_going -k, --keep-going max_drift --max-drift md5_chunksize --hash-chunksize, --md5-chunksize --hash-chunksize since 4.2 no_exec -n, --no-exec, --just-print, --dry-run, --recon no_progress -Q num_jobs -j, --jobs package_type --package-type Available only if the &t-link-packaging; tool has been called profile_file --profile question -q, --question random --random repository -Y, --repository, --srcdir silent -s, --silent, --quiet site_dir --site-dir, --no-site-dir stack_size --stack-size taskmastertrace_file --taskmastertrace tree_printers --tree warn --warn, --warning See the documentation for the corresponding command line option 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 (default 1). 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 **kwargs as arguments to your function or method signatures. 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, **kwargs): 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 to &f-Progress; is a string or list of strings, it is taken as text to be displayed every interval evaluated Nodes. If the first argument is a list of strings, then each string in the list will be displayed in rotating fashion every interval evaluated Nodes. The default is to print the string on standard output. An alternate output stream may be specified with the file keyword argument, which the caller must pass already opened. 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 $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 carriage return) (\r) to cause each line to overwritten by the next line, and the overwrite keyword argument (default False) to make sure the previously-printed file name is overwritten with blank spaces: import sys Progress('$TARGET\r', overwrite=True) A list of strings can be used to implement a "spinner" on the user's screen as follows, changing every five evaluated Nodes: 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;.

(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)

Sets &scons; option variable name to value. These options are all also settable via command-line options but the variable name may differ from the command-line option name - see the table for correspondences. A value set via command-line option will take precedence over one set with &f-SetOption;, which allows setting a project default in the scripts and temporarily overriding it via command line. &f-SetOption; calls can also be placed in the site_init.py file. See the documentation in the manpage for the corresponding command line option for information about each specific option. The value parameter is mandatory, for option values which are boolean in nature (that is, the command line option does not take an argument) use a value which evaluates to true (e.g. True, 1) or false (e.g. False, 0). Options which affect the reading and processing of SConscript files are not settable using &f-SetOption; since those files must be read in order to find the &f-SetOption; call in the first place. The settable variables with their associated command-line options are: Settable name Command-line options Notes clean -c, --clean, --remove diskcheck --diskcheck duplicate --duplicate experimental --experimental since 4.2 hash_chunksize --hash-chunksize Actually sets md5_chunksize. since 4.2 hash_format --hash-format since 4.2 help -h, --help implicit_cache --implicit-cache implicit_deps_changed --implicit-deps-changed Also sets implicit_cache. (settable since 4.2) implicit_deps_unchanged --implicit-deps-unchanged Also sets implicit_cache. (settable since 4.2) max_drift --max-drift md5_chunksize --md5-chunksize no_exec -n, --no-exec, --just-print, --dry-run, --recon no_progress -Q See If no_progress is set via &f-SetOption; in an SConscript file (but not if set in a site_init.py file) there will still be an initial status message about reading SConscript files since &SCons; has to start reading them before it can see the &f-SetOption;. num_jobs -j, --jobs random --random silent -s, --silent, --quiet stack_size --stack-size warn --warn Example: SetOption('max_drift', 0)

([throw_exception=False])

Check that all the options specified on the command line are either defined by SCons itself or defined by calls to &f-link-AddOption;. If there are any command line options not defined. Calling this function will cause SCons to issue an error message and then exit with an error exit status. If optional throw_exception is True, &f-ValidateOptions; will raise a SConsBadOptionError exception instead of printing an error message and exiting with an error status. Then the calling &SConscript; logic can catch that exception and handle invalid options itself. This function should only be called after the last &f-link-AddOption; call in your &SConscript; logic. Be aware that some tools call &f-link-AddOption;, if you are getting error messages for arguments that they add, you will need to ensure that you load those tools before you call &f-ValidateOptions;. Example: try: ValidateOptions(throw_exception=True) except SConsBadOptionError as e: print("Parser is SConsOptionParser:%s" % (isinstance(e.parser, SConsOptionParser))) print("Message is :%s" % e.opt_str) Exit(3)