diff options
Diffstat (limited to 'src/engine/SCons/Script/SConscript.xml')
| -rw-r--r-- | src/engine/SCons/Script/SConscript.xml | 177 |
1 files changed, 83 insertions, 94 deletions
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml index d42fdac..8a6a928 100644 --- a/src/engine/SCons/Script/SConscript.xml +++ b/src/engine/SCons/Script/SConscript.xml @@ -167,21 +167,22 @@ is used if no value is specified. </arguments> <summary> <para> -Exports a list of variables from the current +Exports variables from the current SConscript file to a global collection where they can be -imported by any other SConscript file. -<parameter>vars</parameter> are keys used to -look up the value, so they must be -string represenations of the names of the variables -to be exported. -Subsequent calls to -&f-Export; -will over-write any previous exports that have the same name. -Multiple variable names can be passed to -&f-Export; -as separate arguments or as words in a space-separated string. +imported by other SConscript files. +<parameter>vars</parameter> may be one or more +strings representing variable names to be exported. +If a string contains whitespace, it is split into +separate strings, as if multiple string arguments +had been given. A <parameter>vars</parameter> argument +may also be a dictionary, which can be used to map variables +to different names when exported. 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. +</para> + +<para> +&f-Export; calls are cumulative. Specifying a previously +exported variable will overwirte the earlier value. Both local variables and global variables can be exported. </para> @@ -202,22 +203,19 @@ Export("env", "package") Export(["env", "package"]) # Make env available using the name debug: -Export(debug = env) +Export(debug=env) # Make env available using the name debug: -Export({"debug":env}) +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-link-SConscript; -function, below. +function supports an &exports; +argument that allows exporting a variable or +set of variables to a specific SConscript file or files. +See the description below. </para> </summary> </scons_function> @@ -276,12 +274,12 @@ message. </arguments> <summary> <para> -Imports a list of variables into the current SConscript file. -The variables must be string representations of variable -names which have been previously exported either by the +Imports variables into the current SConscript file. +<parameter>vars</parameter> +must be strings representating names of variables +which have been previously exported either by the &f-link-Export; function or by the -<varname>exports</varname> -argument to +&exports; argument to &f-link-SConscript;. Variables exported by &f-SConscript; @@ -308,29 +306,29 @@ Import("*") <scons_function name="Return"> <arguments signature="global"> -([vars..., stop=]) +([vars..., stop=True]) </arguments> <summary> <para> Return to the calling SConscript, optionally -returning the values of variables named in the -<varname>vars</varname> -string arguments. +returning the values of variables named in +<varname>vars</varname>. Multiple strings contaning variable names may be passed to &f-Return;. A string containing white space -is split into words, which are considered individual -variable names. -Returns a tuple of values, or value that evaluates -<constant>False</constant> -if no <parameter>vars</parameter> were specified. +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 +<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; @@ -348,7 +346,7 @@ Examples: </para> <example_commands> -# Returns without returning a value. +# Returns no values (evaluates False) Return() # Returns the value of the 'foo' Python variable. @@ -374,22 +372,13 @@ Return('val1 val2') </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;. +Execute one or more subsidiary SConscript (configuration) files. There are two ways to call the -&f-SConscript; -function. +&f-SConscript; function. </para> <para> -The first way you can call -&f-SConscript; +The first calling style is to explicitly specify one or more <varname>scripts</varname> as the first argument. @@ -408,22 +397,22 @@ config = SConscript('MyConfig.py') </example_commands> <para> -The second way you can call +The second way to call &f-SConscript; is to specify a list of (sub)directory names as a -<literal>dirs=</literal><varname>subdirs</varname> +<varname>dirs</varname>=<replaceable>subdirs</replaceable> keyword argument. In this case, &scons; -will, by default, +will 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> +<varname>name</varname>=<replaceable>script</replaceable> keyword argument. The first three examples below have the same effect as the first three examples above: @@ -438,10 +427,10 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript') <para> The optional <varname>exports</varname> -argument provides a list of string representations of -variable names or a dictionary of named values to export. +argument provides a string or list of strings representing +variable names, or a dictionary of named values, to export. These variables are locally exported only to the called -SConscript files +SConscript file(s) and do not affect the global pool of variables managed by the &f-link-Export; function. @@ -463,49 +452,34 @@ SConscript(dirs=['one', 'two', 'three'], exports='shared_info') 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 ---> +&f-link-VariantDir; function. +The <varname>variant_dir</varname> argument is interpreted relative to the directory of the calling -&SConscript; -file. -See the description of the -&f-VariantDir; -function for additional details and restrictions. +SConscript file. +The optional +<varname>duplicate</varname> argument is +interpreted as for &f-link-VariantDir;. +If <varname>variant_dir</varname> +is omitted, the <varname>duplicate</varname> argument is ignored. +See the description of +&f-link-VariantDir; +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; +SConscript file resides and the -&SConscript; +SConscript file is evaluated as if it were in the <varname>variant_dir</varname> directory: </para> <example_commands> -SConscript('src/SConscript', variant_dir = 'build') +SConscript('src/SConscript', variant_dir='build') </example_commands> <para> @@ -524,7 +498,7 @@ in the same directory as the </para> <example_commands> -SConscript('SConscript', variant_dir = 'build') +SConscript('SConscript', variant_dir='build') </example_commands> <para> @@ -570,14 +544,17 @@ TODO??? SConscript('build/SConscript', src_dir='src') </para> <para> -The optional +If the optional <varname>must_exist</varname> -argument, if true, causes an exception to be raised if a requested -&SConscript; file is not found. The current default is false, -causing only a warning to be omitted, but this behavior is deprecated. +is <constant>True</constant>, +causes an exception to be raised if a requested +SConscript file is not found. The current default is +<constant>False</constant>, +causing only a warning to be emitted, but this default is deprecated +(<emphasis>since 3.1</emphasis>). For scripts which truly intend to be optional, transition to -explicty supplying -<literal>must_exist=False</literal> to the call. +explicitly supplying +<literal>must_exist=False</literal> to the &f-SConscript; call. </para> <para> @@ -613,6 +590,18 @@ 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(s) in arguments +to the &f-link-Return; function (see above for details). +If a single &f-SConscript; call causes multiple scripts to +be executed, the return value is a tuple containing +the returns of all of the scripts. If an executed +script does not explicitly call &Return;, it returns +<constant>None</constant>. +</para> + </summary> </scons_function> |