mirror of
https://github.com/Relintai/scons_gd.git
synced 2025-02-10 16:40:14 +01:00
1012 lines
26 KiB
XML
1012 lines
26 KiB
XML
<?xml version="1.0"?>
|
|
<!--
|
|
Copyright 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 http://www.scons.org/dbxsd/v1.0/scons.xsd">
|
|
|
|
|
|
<scons_function name="AddOption">
|
|
<arguments signature="global">
|
|
(arguments)
|
|
</arguments>
|
|
<summary>
|
|
<para>
|
|
Adds a local (project-specific) command-line option.
|
|
<parameter>arguments</parameter>
|
|
are the same as those supported by the <function>add_option</function>
|
|
method in the standard Python library module <systemitem>optparse</systemitem>,
|
|
with a few additional capabilities noted below.
|
|
See the documentation for
|
|
<systemitem>optparse</systemitem>
|
|
for a thorough discussion of its option-processing capabities.
|
|
</para>
|
|
|
|
<para>
|
|
In addition to the arguments and values supported by the
|
|
<systemitem>optparse</systemitem>
|
|
<function>add_option</function>
|
|
method, &f-AddOption;
|
|
allows setting the
|
|
<parameter>nargs</parameter>
|
|
keyword value to
|
|
a string consisting of a question mark
|
|
(<literal>'?'</literal>)
|
|
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
|
|
<parameter>const</parameter>
|
|
keyword argument is produced as the value
|
|
of the option.
|
|
If the option string is omitted from
|
|
the command line, the value of the
|
|
<parameter>default</parameter>
|
|
keyword argument is produced, as usual;
|
|
if there is no
|
|
<parameter>default</parameter>
|
|
keyword argument in the &f-AddOption; call,
|
|
<constant>None</constant> is produced.
|
|
</para>
|
|
|
|
<para>
|
|
<systemitem>optparse</systemitem> recognizes
|
|
abbreviations of long option names,
|
|
as long as they can be unambiguously resolved.
|
|
For example, if
|
|
<function>add_option</function> is called to
|
|
define a <option>--devicename</option> option,
|
|
it will recognize <option>--device</option>,
|
|
<option>--dev</option>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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;.
|
|
<!-- was:
|
|
The value may also be set using
|
|
&f-SetOption;
|
|
or
|
|
&f-env.SetOption;,
|
|
if conditions in a
|
|
&SConscript;
|
|
require overriding any default value.
|
|
Note however that a
|
|
value specified on the command line will
|
|
<emphasis>always</emphasis>
|
|
override a value set by any SConscript file.
|
|
-->
|
|
</para>
|
|
|
|
<para>
|
|
Help text for an option is a combination
|
|
of the string supplied in the
|
|
<parameter>help</parameter> keyword
|
|
argument to &f-AddOption; and information
|
|
collected from the other keyword arguments.
|
|
Such help is displayed if the
|
|
<option>-h</option> command line option
|
|
is used (but not with <option>-H</option>).
|
|
Help for all local options is displayed
|
|
under the separate heading
|
|
<emphasis role="bold">Local Options</emphasis>.
|
|
The options are unsorted - they will appear
|
|
in the help text in the order in which the
|
|
&f-AddOption;
|
|
calls occur.
|
|
</para>
|
|
|
|
<para>
|
|
Example:
|
|
</para>
|
|
|
|
<example_commands>
|
|
AddOption(
|
|
'--prefix',
|
|
dest='prefix',
|
|
nargs=1,
|
|
type='string',
|
|
action='store',
|
|
metavar='DIR',
|
|
help='installation prefix',
|
|
)
|
|
env = Environment(PREFIX=GetOption('prefix'))
|
|
</example_commands>
|
|
|
|
<para>For that example,
|
|
the following help text would be produced:</para>
|
|
|
|
<screen>
|
|
Local Options:
|
|
--prefix=DIR installation prefix
|
|
</screen>
|
|
|
|
<para>
|
|
Help text for local options may be unavailable if
|
|
the &f-link-Help; function has been called,
|
|
see the &f-Help; documentation for details.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
As an artifact of the internal implementation,
|
|
the behavior of options added by &AddOption;
|
|
which take option arguments is undefined
|
|
<emphasis>if</emphasis> whitespace
|
|
(rather than an <literal>=</literal> 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 <parameter>nargs</parameter>
|
|
keyword is used to specify more than one following
|
|
option argument (that is, with a value of <constant>2</constant>
|
|
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.
|
|
</para>
|
|
</note>
|
|
|
|
</summary>
|
|
</scons_function>
|
|
|
|
<scons_function name="GetBuildFailures">
|
|
<arguments signature="global">
|
|
()
|
|
</arguments>
|
|
<summary>
|
|
<para>
|
|
Returns a list of exceptions for the
|
|
actions that failed while
|
|
attempting to build targets.
|
|
Each element in the returned list is a
|
|
<classname>BuildError</classname>
|
|
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.
|
|
(This is often a generic
|
|
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.
|
|
This may be different from the
|
|
<literal>.node</literal>
|
|
attribute.
|
|
For example,
|
|
if an attempt to build a target named
|
|
<filename>sub/dir/target</filename>
|
|
fails because the
|
|
<filename>sub/dir</filename>
|
|
directory could not be created,
|
|
then the
|
|
<literal>.node</literal>
|
|
attribute will be
|
|
<filename>sub/dir/target</filename>
|
|
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
|
|
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
|
|
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
|
|
<function>atexit.register</function>()
|
|
function.
|
|
Example:
|
|
</para>
|
|
|
|
<example_commands>
|
|
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)
|
|
</example_commands>
|
|
</summary>
|
|
</scons_function>
|
|
|
|
<scons_function name="GetOption">
|
|
<arguments>
|
|
(name)
|
|
</arguments>
|
|
<summary>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<parameter>name</parameter> can be an entry from the following table,
|
|
which shows the corresponding command line arguments
|
|
that could affect the value.
|
|
<parameter>name</parameter> 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.
|
|
</para>
|
|
|
|
<informaltable rowsep="1" colsep="1" frame="topbot">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Query name</entry>
|
|
<entry align="left">Command-line options</entry>
|
|
<entry align="left">Notes</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><varname>cache_debug</varname></entry>
|
|
<entry><option>--cache-debug</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>cache_disable</varname></entry>
|
|
<entry>
|
|
<option>--cache-disable</option>,
|
|
<option>--no-cache</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>cache_force</varname></entry>
|
|
<entry>
|
|
<option>--cache-force</option>,
|
|
<option>--cache-populate</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>cache_readonly</varname></entry>
|
|
<entry><option>--cache-readonly</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>cache_show</varname></entry>
|
|
<entry><option>--cache-show</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>clean</varname></entry>
|
|
<entry>
|
|
<option>-c</option>,
|
|
<option>--clean</option>,
|
|
<option>--remove</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>climb_up</varname></entry>
|
|
<entry>
|
|
<option>-D</option>
|
|
<option>-U</option>
|
|
<option>-u</option>
|
|
<option>--up</option>
|
|
<option>--search_up</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>config</varname></entry>
|
|
<entry><option>--config</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>debug</varname></entry>
|
|
<entry><option>--debug</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>directory</varname></entry>
|
|
<entry><option>-C</option>, <option>--directory</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>diskcheck</varname></entry>
|
|
<entry><option>--diskcheck</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>duplicate</varname></entry>
|
|
<entry><option>--duplicate</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>enable_virtualenv</varname></entry>
|
|
<entry><option>--enable-virtualenv</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>experimental</varname></entry>
|
|
<entry><option>--experimental</option></entry>
|
|
<entry><emphasis>since 4.2</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>file</varname></entry>
|
|
<entry>
|
|
<option>-f</option>,
|
|
<option>--file</option>,
|
|
<option>--makefile</option>,
|
|
<option>--sconstruct</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>hash_format</varname></entry>
|
|
<entry><option>--hash-format</option></entry>
|
|
<entry><emphasis>since 4.2</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>help</varname></entry>
|
|
<entry><option>-h</option>, <option>--help</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>ignore_errors</varname></entry>
|
|
<entry><option>-i</option>, <option>--ignore-errors</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>ignore_virtualenv</varname></entry>
|
|
<entry><option>--ignore-virtualenv</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>implicit_cache</varname></entry>
|
|
<entry><option>--implicit-cache</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>implicit_deps_changed</varname></entry>
|
|
<entry><option>--implicit-deps-changed</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>implicit_deps_unchanged</varname></entry>
|
|
<entry><option>--implicit-deps-unchanged</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>include_dir</varname></entry>
|
|
<entry><option>-I</option>, <option>--include-dir</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>install_sandbox</varname></entry>
|
|
<entry><option>--install-sandbox</option></entry>
|
|
<entry>Available only if the &t-link-install; tool has been called</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>keep_going</varname></entry>
|
|
<entry><option>-k</option>, <option>--keep-going</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>max_drift</varname></entry>
|
|
<entry><option>--max-drift</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>md5_chunksize</varname></entry>
|
|
<entry>
|
|
<option>--hash-chunksize</option>,
|
|
<option>--md5-chunksize</option>
|
|
</entry>
|
|
<entry><emphasis><option>--hash-chunksize</option> since 4.2</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>no_exec</varname></entry>
|
|
<entry>
|
|
<option>-n</option>,
|
|
<option>--no-exec</option>,
|
|
<option>--just-print</option>,
|
|
<option>--dry-run</option>,
|
|
<option>--recon</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>no_progress</varname></entry>
|
|
<entry><option>-Q</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>num_jobs</varname></entry>
|
|
<entry><option>-j</option>, <option>--jobs</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>package_type</varname></entry>
|
|
<entry><option>--package-type</option></entry>
|
|
<entry>Available only if the &t-link-packaging; tool has been called</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>profile_file</varname></entry>
|
|
<entry><option>--profile</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>question</varname></entry>
|
|
<entry><option>-q</option>, <option>--question</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>random</varname></entry>
|
|
<entry><option>--random</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>repository</varname></entry>
|
|
<entry>
|
|
<option>-Y</option>,
|
|
<option>--repository</option>,
|
|
<option>--srcdir</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>silent</varname></entry>
|
|
<entry>
|
|
<option>-s</option>,
|
|
<option>--silent</option>,
|
|
<option>--quiet</option>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>site_dir</varname></entry>
|
|
<entry><option>--site-dir</option>, <option>--no-site-dir</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>stack_size</varname></entry>
|
|
<entry><option>--stack-size</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>taskmastertrace_file</varname></entry>
|
|
<entry><option>--taskmastertrace</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>tree_printers</varname></entry>
|
|
<entry><option>--tree</option></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>warn</varname></entry>
|
|
<entry><option>--warn</option>, <option>--warning</option></entry>
|
|
</row>
|
|
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
See the documentation for the
|
|
corresponding command line option for information about each specific
|
|
option.
|
|
</para>
|
|
</summary>
|
|
</scons_function>
|
|
|
|
<scons_function name="Progress">
|
|
<arguments signature="global">
|
|
(callable, [interval])
|
|
</arguments>
|
|
<arguments signature="global">
|
|
(string, [interval, file, overwrite])
|
|
</arguments>
|
|
<arguments signature="global">
|
|
(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
|
|
<methodname>__call__</methodname> method),
|
|
the function will be called
|
|
once every
|
|
<varname>interval</varname>
|
|
times a Node is evaluated (default <constant>1</constant>).
|
|
The callable will be passed the evaluated Node
|
|
as its only argument.
|
|
(For future compatibility,
|
|
it's a good idea to also add
|
|
<parameter>*args</parameter>
|
|
and
|
|
<parameter>**kwargs</parameter>
|
|
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.)
|
|
</para>
|
|
|
|
<para>
|
|
An example of a simple custom progress function
|
|
that prints a string containing the Node name
|
|
every 10 Nodes:
|
|
</para>
|
|
|
|
<example_commands>
|
|
def my_progress_function(node, *args, **kwargs):
|
|
print('Evaluating node %s!' % node)
|
|
Progress(my_progress_function, interval=10)
|
|
</example_commands>
|
|
|
|
<para>
|
|
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
|
|
<literal>\r</literal>
|
|
(a carriage return)
|
|
at the end so that the string
|
|
will overwrite itself on a display:
|
|
</para>
|
|
|
|
<example_commands>
|
|
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)
|
|
</example_commands>
|
|
|
|
<para>
|
|
If the first argument to
|
|
&f-Progress; is a string or list of strings,
|
|
it is taken as text to be displayed every
|
|
<varname>interval</varname>
|
|
evaluated Nodes.
|
|
If the first argument is a list of strings,
|
|
then each string in the list will be displayed
|
|
in rotating fashion every
|
|
<varname>interval</varname>
|
|
evaluated Nodes.
|
|
</para>
|
|
|
|
<para>
|
|
The default is to print the string on standard output.
|
|
An alternate output stream
|
|
may be specified with the
|
|
<parameter>file</parameter>
|
|
keyword argument, which the
|
|
caller must pass already opened.
|
|
</para>
|
|
|
|
<para>
|
|
The following will print a series of dots
|
|
on the error output,
|
|
one dot for every 100 evaluated Nodes:
|
|
</para>
|
|
|
|
<example_commands>
|
|
import sys
|
|
Progress('.', interval=100, file=sys.stderr)
|
|
</example_commands>
|
|
|
|
<para>
|
|
If the string contains the verbatim substring
|
|
<literal>$TARGET;</literal>,
|
|
it will be replaced with the Node.
|
|
Note that, for performance reasons, this is
|
|
<emphasis>not</emphasis>
|
|
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)
|
|
(<literal>\r</literal>)
|
|
to cause each line to overwritten by the next line,
|
|
and the
|
|
<parameter>overwrite</parameter>
|
|
keyword argument (default <literal>False</literal>)
|
|
to make sure the previously-printed
|
|
file name is overwritten with blank spaces:
|
|
</para>
|
|
|
|
<example_commands>
|
|
import sys
|
|
Progress('$TARGET\r', overwrite=True)
|
|
</example_commands>
|
|
|
|
<para>
|
|
A list of strings can be used to implement a "spinner"
|
|
on the user's screen as follows, changing every
|
|
five evaluated Nodes:
|
|
</para>
|
|
|
|
<example_commands>
|
|
Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
|
|
</example_commands>
|
|
</summary>
|
|
</scons_function>
|
|
|
|
<scons_function name="Precious">
|
|
<arguments>
|
|
(target, ...)
|
|
</arguments>
|
|
<summary>
|
|
<para>
|
|
Marks each given
|
|
<varname>target</varname>
|
|
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;.
|
|
</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>
|
|
Sets &scons; option variable <parameter>name</parameter>
|
|
to <parameter>value</parameter>.
|
|
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
|
|
<filename>site_init.py</filename> file.
|
|
</para>
|
|
|
|
<para>
|
|
See the documentation in the manpage for the
|
|
corresponding command line option for information about each specific option.
|
|
The <parameter>value</parameter> parameter is mandatory,
|
|
for option values which are boolean in nature
|
|
(that is, the command line option does not take an argument)
|
|
use a <parameter>value</parameter>
|
|
which evaluates to true (e.g. <constant>True</constant>,
|
|
<constant>1</constant>) or false (e.g. <constant>False</constant>,
|
|
<constant>0</constant>).
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The settable variables with their associated command-line options are:
|
|
</para>
|
|
|
|
<!-- UPDATE_SETOPTION_DOCS -->
|
|
<!-- This list comes directly from SConsValues.settable. Keep in sync. -->
|
|
|
|
<informaltable rowsep="1" colsep="1" frame="topbot">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Settable name</entry>
|
|
<entry align="left">Command-line options</entry>
|
|
<entry align="left">Notes</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><varname>clean</varname></entry>
|
|
<entry>
|
|
<option>-c</option>,
|
|
<option>--clean</option>,
|
|
<option>--remove</option>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>diskcheck</varname></entry>
|
|
<entry><option>--diskcheck</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>duplicate</varname></entry>
|
|
<entry><option>--duplicate</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>experimental</varname></entry>
|
|
<entry><option>--experimental</option></entry>
|
|
<entry><emphasis>since 4.2</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>hash_chunksize</varname></entry>
|
|
<entry><option>--hash-chunksize</option></entry>
|
|
<entry>
|
|
Actually sets <varname>md5_chunksize</varname>.
|
|
<emphasis>since 4.2</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>hash_format</varname></entry>
|
|
<entry><option>--hash-format</option></entry>
|
|
<entry><emphasis>since 4.2</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>help</varname></entry>
|
|
<entry><option>-h</option>, <option>--help</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>implicit_cache</varname></entry>
|
|
<entry><option>--implicit-cache</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>implicit_deps_changed</varname></entry>
|
|
<entry><option>--implicit-deps-changed</option></entry>
|
|
<entry>
|
|
Also sets <varname>implicit_cache</varname>.
|
|
<emphasis>(settable since 4.2)</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>implicit_deps_unchanged</varname></entry>
|
|
<entry><option>--implicit-deps-unchanged</option></entry>
|
|
<entry>
|
|
Also sets <varname>implicit_cache</varname>.
|
|
<emphasis>(settable since 4.2)</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>max_drift</varname></entry>
|
|
<entry><option>--max-drift</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>md5_chunksize</varname></entry>
|
|
<entry><option>--md5-chunksize</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>no_exec</varname></entry>
|
|
<entry>
|
|
<option>-n</option>,
|
|
<option>--no-exec</option>,
|
|
<option>--just-print</option>,
|
|
<option>--dry-run</option>,
|
|
<option>--recon</option>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>no_progress</varname></entry>
|
|
<entry><option>-Q</option></entry>
|
|
<entry>See
|
|
<footnote>
|
|
<para>If <varname>no_progress</varname> is set via &f-SetOption;
|
|
in an SConscript file
|
|
(but not if set in a <filename>site_init.py</filename> 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;.
|
|
</para>
|
|
</footnote>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>num_jobs</varname></entry>
|
|
<entry><option>-j</option>, <option>--jobs</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>random</varname></entry>
|
|
<entry><option>--random</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>silent</varname></entry>
|
|
<entry>
|
|
<option>-s</option>,
|
|
<option>--silent</option>,
|
|
<option>--quiet</option>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>stack_size</varname></entry>
|
|
<entry><option>--stack-size</option></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><varname>warn</varname></entry>
|
|
<entry><option>--warn</option></entry>
|
|
</row>
|
|
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
Example:
|
|
</para>
|
|
|
|
<example_commands>
|
|
SetOption('max_drift', 0)
|
|
</example_commands>
|
|
</summary>
|
|
|
|
|
|
</scons_function>
|
|
|
|
<scons_function name="ValidateOptions">
|
|
<arguments signature="global">
|
|
([throw_exception=False])
|
|
</arguments>
|
|
|
|
<summary>
|
|
<para>
|
|
Check that all the options specified on the command line are either defined by SCons itself
|
|
or defined by calls to &f-link-AddOption;.
|
|
</para>
|
|
<para>
|
|
This function should only be called after the last &f-link-AddOption; call in your &SConscript;
|
|
logic.
|
|
</para>
|
|
<para>
|
|
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;.
|
|
</para>
|
|
<para>
|
|
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.</para>
|
|
<para>If the optional <parameter>throw_exception</parameter> is <literal>True</literal>, &f-ValidateOptions; will raise a
|
|
<exceptionname>SConsBadOptionError</exceptionname>
|
|
exception. This would allow the calling
|
|
&SConscript; logic can catch that exception and handle invalid options itself.
|
|
</para>
|
|
|
|
<para>
|
|
Example:
|
|
</para>
|
|
|
|
<example_commands>
|
|
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)
|
|
</example_commands>
|
|
|
|
<para>
|
|
This function is useful to force SCons to fail fast before you execute any expensive logic later in your
|
|
build logic.
|
|
For example if you specify build options via any flags, a simple typo could yield the incorrect build
|
|
option throughout your entire build.
|
|
</para>
|
|
<example_commands>
|
|
scons --compilers=mingw (the correct flag is --compiler)
|
|
</example_commands>
|
|
<para>
|
|
Could cause SCons to run configure steps with the incorrect compiler. Costing developer time trying to
|
|
track down why the configure logic failed with a compiler which should work.
|
|
</para>
|
|
|
|
|
|
|
|
</summary>
|
|
</scons_function>
|
|
|
|
</sconsdoc>
|