path: root/SCons/Script/SConscript.xml

<?xml version="1.0"?>
<!--
SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
SPDX-License-Identifier: MIT
SPDX-FileType: DOCUMENTATION

This file is processed by the bin/SConsDoc.py module.
-->

<!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="Default">
<arguments>
(target[, ...])
</arguments>
<summary>
<para>
Specify default targets to the &SCons; target selection mechanism.
Any call to &f-Default; will cause &SCons; to use the
defined default target list instead of
its built-in algorithm for determining default targets
(see the manpage section "Target Selection").
</para>

<para>
<parameter>target</parameter> may be one or more strings,
a list of strings,
a <classname>NodeList</classname> as returned by a Builder,
or <constant>None</constant>.
A string <parameter>target</parameter> may be the name of
a file or directory, or a target previously defined by a call to
&f-link-Alias; (defining the alias later will still create
the alias, but it will not be recognized as a default).
Calls to &f-Default; are additive.
A <parameter>target</parameter> of
<literal>None</literal>
will clear any existing default target list;
subsequent calls to
&f-Default;
will add to the (now empty) default target list
like normal.
</para>

<para>
Both forms of this call affect the
same global list of default targets; the
construction environment method applies
construction variable expansion to the targets.
</para>

<para>
The current list of targets added using
&f-Default; is available in the
&DEFAULT_TARGETS; list (see below).
</para>

<para>
Examples:
</para>

<example_commands>
Default('foo', 'bar', 'baz')
env.Default(['a', 'b', 'c'])
hello = env.Program('hello', 'hello.c')
env.Default(hello)
</example_commands>

</summary>
</scons_function>

<scons_function name="EnsurePythonVersion">
<arguments signature="global">
(major, minor)
</arguments>
<summary>
<para>
Ensure that the Python version is at least
<varname>major</varname>.<varname>minor</varname>.
This function will
print out an error message and exit SCons with a non-zero exit code if the
actual Python version is not late enough.
</para>

<para>
Example:
</para>

<example_commands>
EnsurePythonVersion(2,2)
</example_commands>
</summary>
</scons_function>

<scons_function name="EnsureSConsVersion">
<arguments signature="global">
(major, minor, [revision])
</arguments>
<summary>
<para>
Ensure that the SCons version is at least
<varname>major.minor</varname>,
or
<varname>major.minor.revision</varname>.
if
<varname>revision</varname>
is specified.
This function will
print out an error message and exit SCons with a non-zero exit code if the
actual SCons version is not late enough.
</para>

<para>
Examples:
</para>

<example_commands>
EnsureSConsVersion(0,14)

EnsureSConsVersion(0,96,90)
</example_commands>
</summary>
</scons_function>

<scons_function name="GetSConsVersion">
<arguments signature="global">
()
</arguments>
<summary>
<para>
Returns the current SCons version in the form of a Tuple[int, int, int],
representing the major, minor, and revision values respectively.
<emphasis>Added in 4.8.0</emphasis>.
</para>
</summary>
</scons_function>

<scons_function name="Exit">
<arguments signature="global">
([value])
</arguments>
<summary>
<para>
This tells
&scons;
to exit immediately
with the specified
<varname>value</varname>.
A default exit value of
<literal>0</literal>
(zero)
is used if no value is specified.
</para>
</summary>
</scons_function>

<scons_function name="Export">
<arguments>
([vars...], [key=value...])
</arguments>
<summary>
<para>
Exports variables for sharing with other SConscript files.
The variables are added to a global collection where
they can be imported by other SConscript files.
<parameter>vars</parameter> may be one or more
strings, or a list of strings. If any string
contains whitespace, it is split automatically
into individual strings. Each string must
match the name of a variable that is in scope
during evaluation of the current SConscript file,
or an exception is raised.
</para>

<para>
A <parameter>vars</parameter> argument
may also be a dictionary or
individual keyword arguments;
in accordance with &Python; syntax rules,
keyword arguments must come after any
non-keyword arguments.
The dictionary/keyword form can be used
to map the local name of a variable to
a different name to be used for imports.
See the Examples for an illustration of the syntax.
</para>

<para>
&f-Export; calls are cumulative. Specifying a previously
exported variable will replace the previous value in the collection.
Both local variables and global variables can be exported.
</para>

<para>
To use an exported variable, an SConscript must
call &f-link-Import; to bring it into its own scope.
Importing creates an additional reference to the object that
was originally exported, so if that object is mutable,
changes made will be visible to other users of that object.
</para>

<para>
Examples:
</para>

<example_commands>
env = Environment()
# Make env available for all SConscript files to Import().
Export("env")

package = 'my_name'
# Make env and package available for all SConscript files:.
Export("env", "package")

# Make env and package available for all SConscript files:
Export(["env", "package"])

# Make env available using the name debug:
Export(debug=env)

# Make env available using the name debug:
Export({"debug": env})
</example_commands>

<para>
Note that the
&f-link-SConscript;
function also supports an &exports;
argument that allows exporting one or more variables
to the SConscript files invoked by that call (only).
See the description of that function for details.
</para>
</summary>
</scons_function>

<scons_function name="GetLaunchDir">
<arguments signature="global">
()
</arguments>
<summary>
<para>
Returns the absolute path name of the directory from which
&scons;
was initially invoked.
This can be useful when using the
<option>-u</option>,
<option>-U</option>
or
<option>-D</option>
options, which internally
change to the directory in which the
&SConstruct;
file is found.
</para>
</summary>
</scons_function>

<scons_function name="Help">
<arguments>
(text, append=False, local_only=False)
</arguments>
<summary>
<para>
Adds <parameter>text</parameter> to the help message shown when
&scons; is called with the
<option>-h</option> or <option>--help</option>
argument.
</para>
<para>
On the first call to &f-Help;,
if <parameter>append</parameter> is <constant>False</constant>
(the default), any existing help text is discarded.
The default help text is the help for the &scons;
command itself plus help collected from any
project-local &f-link-AddOption; calls.
This is the help printed if &f-Help; has never been called.
If <parameter>append</parameter> is <constant>True</constant>,
<parameter>text</parameter> is appended to
the existing help text.
If <parameter>local_only</parameter> is also <constant>True</constant>
(the default is <constant>False</constant>),
the project-local help from &f-AddOption; calls is preserved
in the help message but the &scons; command help is not.
</para>
<para>
Subsequent calls to
&f-Help; ignore the keyword arguments
<parameter>append</parameter> and
<parameter>local_only</parameter>
and always append to the existing help text.
</para>
<para>
<emphasis>Changed in 4.6.0</emphasis>: added <parameter>local_only</parameter>.
</para>

</summary>
</scons_function>

<scons_function name="Import">
<arguments>
(vars...)
</arguments>
<summary>
<para>
Imports variables into the scope of the current SConscript file.
<parameter>vars</parameter>
must be strings representing names of variables
which have been previously exported either by the
&f-link-Export; function or by the
&exports; argument to the
&f-link-SConscript; function.
Variables exported by the
&f-SConscript; call
take precedence.
Multiple variable names can be passed to
&f-Import;
as separate arguments, as a list of strings,
or as words in a space-separated string.
The wildcard <literal>"*"</literal> can be used to import all
available variables.
</para>

<para>
If the imported variable is mutable,
changes made locally will be reflected in the object the
variable is bound to. This allows subsidiary SConscript files
to contribute to building up, for example, a &consenv;.
</para>

<para>
Examples:
</para>

<example_commands>
Import("env")
Import("env", "variable")
Import(["env", "variable"])
Import("*")
</example_commands>
</summary>
</scons_function>

<scons_function name="Return">
<arguments signature="global">
([vars..., stop=True])
</arguments>
<summary>
<para>
Return to the calling SConscript, optionally
returning the values of variables named in
<varname>vars</varname>.
Multiple strings containing variable names may be passed to
&f-Return;. A string containing white space
is split into individual variable names.
Returns the value if one variable is specified,
else returns a tuple of values.
Returns an empty tuple if <parameter>vars</parameter>
is omitted.
</para>

<para>
By default &Return; stops processing the current SConscript
and returns immediately.
The optional
<literal>stop</literal>
keyword argument
may be set to a false value
to continue processing the rest of the SConscript
file after the
&f-Return;
call (this was the default behavior prior to SCons 0.98.)
However, the values returned
are still the values of the variables in the named
<varname>vars</varname>
at the point
&f-Return;
was called.
</para>

<para>
Examples:
</para>

<example_commands>
# Returns no values (evaluates False)
Return()

# Returns the value of the 'foo' Python variable.
Return("foo")

# Returns the values of the Python variables 'foo' and 'bar'.
Return("foo", "bar")

# Returns the values of Python variables 'val1' and 'val2'.
Return('val1 val2')
</example_commands>
</summary>
</scons_function>

<scons_function name="SConscript">
<arguments>
(scriptnames, [exports, variant_dir, duplicate, must_exist])
<!-- (scriptnames, [exports, variant_dir, src_dir, duplicate, must_exist]) -->
</arguments>
<arguments>
(dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist])
<!-- (dirs=subdirs, [name=scriptname, exports, variant_dir, src_dir, duplicate, must_exist]) -->
</arguments>
<summary>
<para>
Executes subsidiary SConscript (build configuration) file(s).
There are two ways to call the
&f-SConscript; function.
</para>

<para>
The first calling style is to supply
one or more SConscript file names
as the first positional argument,
which can be a string or a list of strings.
If there is a second positional argument,
it is treated as if the
<varname>exports</varname>
keyword argument had been given (see below).
Examples:
</para>
<example_commands>
SConscript('SConscript')  # run SConscript in the current directory
SConscript('src/SConscript')  # run SConscript in the src directory
SConscript(['src/SConscript', 'doc/SConscript'])
SConscript(Split('src/SConscript doc/SConscript'))
config = SConscript('MyConfig.py')
</example_commands>

<para>
The second calling style is to omit the positional argument naming
the script and instead specify directory names using the
<varname>dirs</varname> keyword argument.
The value can be a string or list of strings.
In this case,
&scons;
will execute a subsidiary configuration file named
&SConscript; (by default)
in each of the specified directories.
You may specify a name other than
&SConscript;
by supplying an optional
<varname>name</varname>=<replaceable>scriptname</replaceable>
keyword argument.
The first three examples below have the same effect
as the first three examples above:
</para>
<example_commands>
SConscript(dirs='.')  # run SConscript in the current directory
SConscript(dirs='src')  # run SConscript in the src directory
SConscript(dirs=['src', 'doc'])
SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
</example_commands>

<para>
The optional
<varname>exports</varname>
keyword argument specifies variables to make available
for use by the called SConscripts,
which are evaluated in an isolated context
and otherwise do not have access to local variables
from the calling SConscript.
The value may be a string or list of strings representing
variable names, or a dictionary mapping local names to
the names they can be imported by.
For the first (scriptnames) calling style,
a second positional argument will also be interpreted as
<varname>exports</varname>;
the second (directory) calling style accepts no
positional arguments and must use the keyword form.
These variables are locally exported only to the called
SConscript file(s), and take precedence over any same-named
variables in the global pool managed by the
&f-link-Export;
function.
<!-- If multiple dirs are provided, each script gets a fresh export. -->
The subsidiary SConscript files
must use the
&f-link-Import;
function to import the variables into their local scope.
Examples:
</para>
<example_commands>
foo = SConscript('sub/SConscript', exports='env')
SConscript('dir/SConscript', exports=['env', 'variable'])
SConscript(dirs='subdir', exports='env variable')
SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
</example_commands>

<para>
If the optional
<varname>variant_dir</varname>
argument is present, it causes an effect equivalent to the
&f-link-VariantDir; function,
but in effect only within the scope of the &f-SConscript; call.
The <varname>variant_dir</varname>
argument is interpreted relative to the directory of the
<emphasis>calling</emphasis> SConscript file.
The source directory is the directory in which the
<emphasis>called</emphasis> SConscript
file resides and the SConscript
file is evaluated as if it were in the
<varname>variant_dir</varname>
directory. Thus:
</para>
<example_commands>
SConscript('src/SConscript', variant_dir='build')
</example_commands>

<para>
is equivalent to:
</para>

<example_commands>
VariantDir('build', 'src')
SConscript('build/SConscript')
</example_commands>

<para>
If the sources are in the same directory as the
&SConstruct;,
</para>

<example_commands>
SConscript('SConscript', variant_dir='build')
</example_commands>

<para>
is equivalent to:
</para>

<example_commands>
VariantDir('build', '.')
SConscript('build/SConscript')
</example_commands>

<para>
The optional
<varname>duplicate</varname> argument is
interpreted as for &f-link-VariantDir;.
If the <varname>variant_dir</varname> argument
is omitted, the <varname>duplicate</varname> argument is ignored.
See the description of
&f-link-VariantDir;
for additional details and restrictions.
</para>

<para>
<!--
If
<varname>variant_dir</varname>
and"
<varname>src_dir</varname>
are both present,
xxxxx everything is in a state of confusion.
</para>
<example_commands>
SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
runs src/SConscript in build/src, but
SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
runs lib/SConscript (in lib!).  However,
SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
runs src/SConscript in build.  Moreover,
SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
runs src/lib/SConscript in build/lib.  Moreover,
SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
can't find build/src/lib/SConscript, even though it ought to exist.
</example_commands>
<para>
is equivalent to
</para>
<example_commands>
????????????????
</example_commands>
<para>
and what about this alternative?
TODO??? SConscript('build/SConscript', src_dir='src')
-->
</para>

<para>
If the optional
<varname>must_exist</varname>
is <constant>True</constant> (the default),
an exception is raised if a requested
SConscript file is not found.
To allow missing scripts to be silently ignored
(the default behavior prior to &SCons; version 3.1),
pass
<literal>must_exist=False</literal> in the &f-SConscript; call.
</para>

<para>
<emphasis>Changed in 4.6.0</emphasis>: <parameter>must_exist</parameter>
now defaults to <constant>True</constant>.
</para>

<para>
Here are some composite examples:
</para>

<example_commands>
# collect the configuration information and use it to build src and doc
shared_info = SConscript('MyConfig.py')
SConscript('src/SConscript', exports='shared_info')
SConscript('doc/SConscript', exports='shared_info')
</example_commands>

<example_commands>
# build debugging and production versions.  SConscript
# can use Dir('.').path to determine variant.
SConscript('SConscript', variant_dir='debug', duplicate=0)
SConscript('SConscript', variant_dir='prod', duplicate=0)
</example_commands>

<example_commands>
# build debugging and production versions.  SConscript
# is passed flags to use.
opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
</example_commands>

<example_commands>
# build common documentation and compile for different architectures
SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
</example_commands>

<para>
&f-SConscript; returns the values of any variables
named by the executed SConscript file(s) in arguments
to the &f-link-Return; function.
If a single &f-SConscript; call causes multiple scripts to
be executed, the return value is a tuple containing
the returns of each of the scripts. If an executed
script does not explicitly call &Return;, it returns
<constant>None</constant>.
</para>

</summary>
</scons_function>

</sconsdoc>