<?xml version="1.0" encoding="UTF-8"?>
<!--
__COPYRIGHT__

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="Default">
<arguments>
(targets)
</arguments>
<summary>
<para>
This specifies a list of default targets,
which will be built by
&scons;
if no explicit targets are given on the command line.
Multiple calls to
&f-Default;
are legal,
and add to the list of default targets.
</para>

<para>
Multiple targets should be specified as
separate arguments to the
&f-Default;
method, or as a list.
&f-Default;
will also accept the Node returned by any
of a construction environment's
builder methods.
</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>

<para>
An argument to
&f-Default;
of
<literal>None</literal>
will clear all default targets.
Later calls to
&f-Default;
will add to the (now empty) default-target list
like normal.
</para>

<para>
The current list of targets added using the
&f-Default;
function or method is available in the
<literal>DEFAULT_TARGETS</literal>
list;
see below.
</para>
</summary>
</scons_function>

<scons_function name="EnsurePythonVersion">
<arguments>
(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>
(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="Exit">
<arguments>
([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)
</arguments>
<summary>
<para>
This tells
&scons;
to export a list of variables from the current
SConscript file to all other SConscript files.
The exported variables are kept in a global collection,
so subsequent calls to
&f-Export;
will over-write previous exports that have the same name.
Multiple variable names can be passed to
&f-Export;
as separate arguments or as a list.
Keyword arguments can be used to provide names and their values.
A dictionary can be used to map variables to a different name when exported.
Both local variables and global variables can be exported.
</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-SConscript;
function supports an
<varname>exports</varname>
argument that makes it easier to to export a variable or
set of variables to a single SConscript file.
See the description of the
&f-SConscript;
function, below.
</para>
</summary>
</scons_function>

<scons_function name="GetLaunchDir">
<arguments>
()
</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)
</arguments>
<summary>
<para>
This specifies help text to be printed if the
<option>-h</option>
argument is given to
&scons;.
If 
&f-Help;
is called multiple times, the text is appended together in the order that 
&f-Help;
is called. With append set to False, any 
&f-Help;
text generated with 
&f-AddOption;
is clobbered. If append is True, the AddOption help is prepended to the help
string, thus preserving the 
<option>-h</option>
message.
</para>
</summary>
</scons_function>

<scons_function name="Import">
<arguments>
(vars)
</arguments>
<summary>
<para>
This tells
&scons;
to import a list of variables into the current SConscript file. This
will import variables that were exported with
&f-Export;
or in the
<varname>exports</varname>
argument to
&f-link-SConscript;.
Variables exported by
&f-SConscript;
have precedence.
Multiple variable names can be passed to
&f-Import;
as separate arguments or as a list. The variable "*" can be used
to import all variables.
</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=])
</arguments>
<summary>
<para>
By default,
this stops processing the current SConscript
file and returns to the calling SConscript file
the values of the variables named in the
<varname>vars</varname>
string arguments.
Multiple strings contaning variable names may be passed to
&f-Return;.
Any strings that contain white space
</para>

<para>
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;
is called.
</para>

<para>
Examples:
</para>

<example_commands>
# Returns without returning a value.
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>
(scripts, [exports, variant_dir, duplicate])
<!-- (scripts, [exports, variant_dir, src_dir, duplicate]) -->
</arguments>
<arguments>
(dirs=subdirs, [name=script, exports, variant_dir, duplicate])
<!-- (dirs=subdirs, [name=script, exports, variant_dir, src_dir, duplicate]) -->
</arguments>
<summary>
<para>
This tells
&scons;
to execute
one or more subsidiary SConscript (configuration) files.
Any variables returned by a called script using
&f-link-Return;
will be returned by the call to
&f-SConscript;.
There are two ways to call the
&f-SConscript;
function.
</para>

<para>
The first way you can call
&f-SConscript;
is to explicitly specify one or more
<varname>scripts</varname>
as the first argument.
A single script may be specified as a string;
multiple scripts must be specified as a list
(either explicitly or as created by
a function like
&f-Split;).
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'])
config = SConscript('MyConfig.py')
</example_commands>

<para>
The second way you can call
&f-SConscript;
is to specify a list of (sub)directory names
as a
<literal>dirs=</literal><varname>subdirs</varname>
keyword argument.
In this case,
&scons;
will, by default,
execute a subsidiary configuration file named
&SConscript;
in each of the specified directories.
You may specify a name other than
&SConscript;
by supplying an optional
<literal>name=</literal><varname>script</varname>
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>
argument provides a list of variable names or a dictionary of
named values to export to the
<varname>script(s)</varname>.
These variables are locally exported only to the specified
<varname>script(s)</varname>,
and do not affect the global pool of variables used by the
&f-Export;
function.
<!-- If multiple dirs are provided, each script gets a fresh export. -->
The subsidiary
<varname>script(s)</varname>
must use the
&f-link-Import;
function to import the variables.
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;
method described below.
(If
<varname>variant_dir</varname>
is not present, the
<!-- <varname>src_dir</varname> and -->
<varname>duplicate</varname>
<!-- arguments are ignored.) -->
argument is ignored.)
The
<varname>variant_dir</varname>
<!--
and
<varname>src_dir</varname>
arguments are interpreted relative to the directory of the calling
-->
argument is interpreted relative to the directory of the calling
&SConscript;
file.
See the description of the
&f-VariantDir;
function below for additional details and restrictions.
</para>

<para>
If
<varname>variant_dir</varname>
is present,
<!--
but
<varname>src_dir</varname>
is not,
-->
the source directory is the directory in which the
&SConscript;
file resides and the
&SConscript;
file is evaluated as if it were in the
<varname>variant_dir</varname>
directory:
</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>
This later paradigm is often used when 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>
<!--
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>
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>
</summary>
</scons_function>

</sconsdoc>