summaryrefslogtreecommitdiff
path: root/src/engine/SCons/Script/SConscript.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
committerLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
commit140d836e9cd54fb67b969fd82ef7ed19ba574d40 (patch)
tree0df3e32ee39603d43f9b90fd2f2e1f7cce4249d4 /src/engine/SCons/Script/SConscript.xml
parentcb3425abe0bc2d05caf401ca24b82a25a81f009d (diff)
Imported Upstream version 2.3.1upstream/2.3.1
Diffstat (limited to 'src/engine/SCons/Script/SConscript.xml')
-rw-r--r--src/engine/SCons/Script/SConscript.xml165
1 files changed, 126 insertions, 39 deletions
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
index e30997c..9fab301 100644
--- a/src/engine/SCons/Script/SConscript.xml
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -1,15 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
<!--
-Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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/scons.xsd scons.xsd">
+
+
<scons_function name="Default">
<arguments>
(targets)
</arguments>
<summary>
+<para>
This specifies a list of default targets,
which will be built by
&scons;
@@ -18,7 +38,9 @@ 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;
@@ -27,16 +49,20 @@ method, or as a list.
will also accept the Node returned by any
of a construction environment's
builder methods.
+</para>
+<para>
Examples:
+</para>
-<example>
+<example_commands>
Default('foo', 'bar', 'baz')
env.Default(['a', 'b', 'c'])
hello = env.Program('hello', 'hello.c')
env.Default(hello)
-</example>
+</example_commands>
+<para>
An argument to
&f-Default;
of
@@ -46,13 +72,16 @@ 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>
@@ -61,17 +90,21 @@ see below.
(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>
+<example_commands>
EnsurePythonVersion(2,2)
-</example>
+</example_commands>
</summary>
</scons_function>
@@ -80,6 +113,7 @@ EnsurePythonVersion(2,2)
(major, minor, [revision])
</arguments>
<summary>
+<para>
Ensure that the SCons version is at least
<varname>major.minor</varname>,
or
@@ -90,14 +124,17 @@ 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>
+<example_commands>
EnsureSConsVersion(0,14)
EnsureSConsVersion(0,96,90)
-</example>
+</example_commands>
</summary>
</scons_function>
@@ -106,6 +143,7 @@ EnsureSConsVersion(0,96,90)
([value])
</arguments>
<summary>
+<para>
This tells
&scons;
to exit immediately
@@ -115,6 +153,7 @@ A default exit value of
<literal>0</literal>
(zero)
is used if no value is specified.
+</para>
</summary>
</scons_function>
@@ -123,6 +162,7 @@ is used if no value is specified.
(vars)
</arguments>
<summary>
+<para>
This tells
&scons;
to export a list of variables from the current
@@ -137,10 +177,13 @@ 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>
+<example_commands>
env = Environment()
# Make env available for all SConscript files to Import().
Export("env")
@@ -157,8 +200,9 @@ Export(debug = env)
# Make env available using the name debug:
Export({"debug":env})
-</example>
+</example_commands>
+<para>
Note that the
&f-SConscript;
function supports an
@@ -168,6 +212,7 @@ set of variables to a single SConscript file.
See the description of the
&f-SConscript;
function, below.
+</para>
</summary>
</scons_function>
@@ -176,6 +221,7 @@ function, below.
()
</arguments>
<summary>
+<para>
Returns the absolute path name of the directory from which
&scons;
was initially invoked.
@@ -188,6 +234,7 @@ options, which internally
change to the directory in which the
&SConstruct;
file is found.
+</para>
</summary>
</scons_function>
@@ -196,6 +243,7 @@ file is found.
(text)
</arguments>
<summary>
+<para>
This specifies help text to be printed if the
<option>-h</option>
argument is given to
@@ -206,6 +254,7 @@ is called multiple times, the text is appended together in the order
that
&f-Help;
is called.
+</para>
</summary>
</scons_function>
@@ -214,6 +263,7 @@ is called.
(vars)
</arguments>
<summary>
+<para>
This tells
&scons;
to import a list of variables into the current SConscript file. This
@@ -230,15 +280,18 @@ 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>
+<example_commands>
Import("env")
Import("env", "variable")
Import(["env", "variable"])
Import("*")
-</example>
+</example_commands>
</summary>
</scons_function>
@@ -247,6 +300,7 @@ Import("*")
([vars..., stop=])
</arguments>
<summary>
+<para>
By default,
this stops processing the current SConscript
file and returns to the calling SConscript file
@@ -256,7 +310,9 @@ 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
@@ -271,10 +327,13 @@ are still the values of the variables in the named
at the point
&f-Return;
is called.
+</para>
+<para>
Examples:
+</para>
-<example>
+<example_commands>
# Returns without returning a value.
Return()
@@ -286,7 +345,7 @@ Return("foo", "bar")
# Returns the values of Python variables 'val1' and 'val2'.
Return('val1 val2')
-</example>
+</example_commands>
</summary>
</scons_function>
@@ -300,6 +359,7 @@ Return('val1 val2')
<!-- (dirs=subdirs, [name=script, exports, variant_dir, src_dir, duplicate]) -->
</arguments>
<summary>
+<para>
This tells
&scons;
to execute
@@ -311,7 +371,9 @@ will be returned by the call to
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
@@ -323,13 +385,15 @@ multiple scripts must be specified as a list
a function like
&f-Split;).
Examples:
-<example>
+</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>
+</example_commands>
+<para>
The second way you can call
&f-SConscript;
is to specify a list of (sub)directory names
@@ -349,13 +413,15 @@ by supplying an optional
keyword argument.
The first three examples below have the same effect
as the first three examples above:
-<example>
+</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>
+</example_commands>
+<para>
The optional
<varname>exports</varname>
argument provides a list of variable names or a dictionary of
@@ -373,13 +439,15 @@ must use the
&f-link-Import;
function to import the variables.
Examples:
-<example>
+</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>
+</example_commands>
+<para>
If the optional
<varname>variant_dir</varname>
argument is present, it causes an effect equivalent to the
@@ -405,7 +473,9 @@ file.
See the description of the
&f-VariantDir;
function below for additional details and restrictions.
+</para>
+<para>
If
<varname>variant_dir</varname>
is present,
@@ -421,32 +491,40 @@ file resides and the
file is evaluated as if it were in the
<varname>variant_dir</varname>
directory:
-<example>
+</para>
+<example_commands>
SConscript('src/SConscript', variant_dir = 'build')
-</example>
+</example_commands>
+<para>
is equivalent to
+</para>
-<example>
+<example_commands>
VariantDir('build', 'src')
SConscript('build/SConscript')
-</example>
+</example_commands>
+<para>
This later paradigm is often used when the sources are
in the same directory as the
&SConstruct;:
+</para>
-<example>
+<example_commands>
SConscript('SConscript', variant_dir = 'build')
-</example>
+</example_commands>
+<para>
is equivalent to
+</para>
-<example>
+<example_commands>
VariantDir('build', '.')
SConscript('build/SConscript')
-</example>
+</example_commands>
+<para>
<!--
If
<varname>variant_dir</varname>
@@ -454,7 +532,8 @@ and"
<varname>src_dir</varname>
are both present,
xxxxx everything is in a state of confusion.
-<example>
+</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')
@@ -465,45 +544,53 @@ 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>
+</example_commands>
+<para>
is equivalent to
-<example>
+</para>
+<example_commands>
????????????????
-</example>
+</example_commands>
+<para>
and what about this alternative?
TODO??? SConscript('build/SConscript', src_dir='src')
-->
+</para>
+<para>
Here are some composite examples:
+</para>
-<example>
+<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>
+</example_commands>
-<example>
+<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>
+</example_commands>
-<example>
+<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>
+</example_commands>
-<example>
+<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>
+</example_commands>
</summary>
</scons_function>
+
+</sconsdoc> \ No newline at end of file