Merge pull request #4150 from mwichmann/docs/variantdir

Improve variantdir docs

2 files changed, 81 insertions, 84 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 3a6df97..5c4326c 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -318,7 +318,7 @@ Added methods propagate through &f-env-Clone; calls.
 </para>
 
 <para>
-Examples:
+More examples:
 </para>
 
 <example_commands>
@@ -3416,42 +3416,41 @@ env.UpdateValue(target = Value(output), source = Value(input))
 </arguments>
 <summary>
 <para>
-Sets up an alternate build location.
-When building in the <parameter>variant_dir</parameter>,
-&SCons; backfills as needed with files from <parameter>src_dir</parameter>
-to create a complete build directory.
+Sets up a mapping to define a variant build directory in
+<parameter>variant_dir</parameter>.
+<parameter>src_dir</parameter> may not be underneath
+<parameter>variant_dir</parameter>.
+A &f-VariantDir; mapping is global, even if called using the
+&f-env-VariantDir; form.
 &f-VariantDir;
 can be called multiple times with the same
 <parameter>src_dir</parameter>
-to set up multiple builds with different options
-(<emphasis>variants</emphasis>).
+to set up multiple variant builds with different options.
 </para>
 
 <para>
-The
-<parameter>variant</parameter>
-location must be in or underneath the project top directory,
-and <parameter>src_dir</parameter>
-may not be underneath
-<parameter>variant_dir</parameter>.
+Note if <parameter>variant_dir</parameter>
+is not under the project top directory,
+target selection rules will not pick targets in the
+variant directory unless they are explicitly specified.
 </para>
 
 <para>
+When files in <parameter>variant_dir</parameter> are referenced,
+&SCons; backfills as needed with files from <parameter>src_dir</parameter>
+to create a complete build directory.
 By default, &SCons;
-physically duplicates the source files and SConscript files
-as needed into the variant tree.
-Thus, a build performed in the variant tree is guaranteed to be identical
-to a build performed in the source tree even if
+physically duplicates the source files, SConscript files,
+and directory structure as needed into the variant directory.
+Thus, a build performed in the variant directory is guaranteed to be identical
+to a build performed in the source directory even if
 intermediate source files are generated during the build,
 or if preprocessors or other scanners search for included files
-relative to the source file,
+using paths relative to the source file,
 or if individual compilers or other invoked tools are hard-coded
 to put derived files in the same directory as source files.
 Only the files &SCons; calculates are needed for the build are
 duplicated into <parameter>variant_dir</parameter>.
-</para>
-
-<para>
 If possible on the platform,
 the duplication is performed by linking rather than copying.
 This behavior is affected by the
@@ -3470,44 +3469,46 @@ to invoke Builders using the path names of source files in
 <parameter>src_dir</parameter>
 and the path names of derived files within
 <parameter>variant_dir</parameter>.
-This is more efficient than
-<literal>duplicate=True</literal>,
+This is more efficient than duplicating,
 and is safe for most builds;
-revert to <constant>True</constant>
+revert to <literal>duplicate=True</literal>
 if it causes problems.
 </para>
 
 <para>
 &f-VariantDir;
-works most naturally with used with a subsidiary SConscript file.
-The subsidiary SConscript file is called as if it
-were in
+works most naturally when used with a subsidiary SConscript file.
+The subsidiary SConscript file must be called as if it were in
 <parameter>variant_dir</parameter>,
 regardless of the value of
 <parameter>duplicate</parameter>.
-This is how you tell
-&scons;
-which variant of a source tree to build:
+When calling an SConscript file, you can use the 
+<parameter>exports</parameter> keyword argument
+to pass parameters (individually or as an appropriately set up environment)
+so the SConscript can pick up the right settings for that variant build.
+The SConscript must &f-link-Import; these to use them. Example:
 </para>
 
 <example_commands>
+env1 = Environment(...settings for variant1...)
+env2 = Environment(...settings for variant2...)
+
 # run src/SConscript in two variant directories
 VariantDir('build/variant1', 'src')
-SConscript('build/variant1/SConscript')
+SConscript('build/variant1/SConscript', exports={"env": env1})
 VariantDir('build/variant2', 'src')
-SConscript('build/variant2/SConscript')
+SConscript('build/variant2/SConscript', exports={"env": env2})
 </example_commands>
 
 <para>
 See also the
-&f-link-SConscript;
-function, described above,
+&f-link-SConscript; function
 for another way to specify a variant directory
 in conjunction with calling a subsidiary SConscript file.
 </para>
 
 <para>
-Examples:
+More examples:
 </para>
 
 <example_commands>
diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml
index 3c5b907..eb52acc 100644
--- a/SCons/Script/SConscript.xml
+++ b/SCons/Script/SConscript.xml
@@ -363,42 +363,38 @@ Return('val1 val2')
 <!-- (scripts, [exports, variant_dir, src_dir, duplicate, must_exist]) -->
 </arguments>
 <arguments>
-(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist])
-<!-- (dirs=subdirs, [name=script, exports, variant_dir, src_dir, duplicate, must_exist]) -->
+(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>
-Execute one or more subsidiary SConscript (configuration) files.
+Executes one or more subsidiary SConscript (configuration) files.
 There are two ways to call the
 &f-SConscript; function.
 </para>
 
 <para>
-The first calling style
-is to explicitly specify one or more
-<varname>scripts</varname>
-as the first argument.
+The first calling style is to supply
+one or more SConscript file names
+as the first (positional) argument.
 A single script may be specified as a string;
-multiple scripts must be specified as a list
+multiple scripts must be specified as a list of strings
 (either explicitly or as created by
 a function like
 &f-link-Split;).
 Examples:
 </para>
 <example_commands>
-SConscript('SConscript')      # run SConscript in the current directory
+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 to call
-&f-SConscript;
-is to specify a list of (sub)directory names
-as a
-<varname>dirs</varname>=<replaceable>subdirs</replaceable>
-keyword argument.
+The other calling style is to omit the positional argument naming
+scripts and instead specify a list of directory names using the
+<varname>dirs</varname> keyword argument.
 In this case,
 &scons;
 will
@@ -408,14 +404,14 @@ in each of the specified directories.
 You may specify a name other than
 &SConscript;
 by supplying an optional
-<varname>name</varname>=<replaceable>script</replaceable>
+<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='.')  # 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>
@@ -423,8 +419,12 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
 <para>
 The optional
 <varname>exports</varname>
-argument provides a string or list of strings representing
+keyword argument provides a string or list of strings representing
 variable names, or a dictionary of named values, to export.
+For the first calling style only, a second positional argument
+will be interpreted as <varname>exports</varname>; the
+second calling style must use the keyword argument form
+for <varname>exports</varname>.
 These variables are locally exported only to the called
 SConscript file(s)
 and do not affect the global pool of variables managed by the
@@ -448,38 +448,24 @@ 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; function.
+&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 calling
-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,
-the source directory is the directory in which the
-SConscript
-file resides and the
-SConscript
+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:
+directory. Thus:
 </para>
 <example_commands>
 SConscript('src/SConscript', variant_dir='build')
 </example_commands>
 
 <para>
-is equivalent to
+is equivalent to:
 </para>
 
 <example_commands>
@@ -488,9 +474,8 @@ SConscript('build/SConscript')
 </example_commands>
 
 <para>
-This later paradigm is often used when the sources are
-in the same directory as the
-&SConstruct;:
+If the sources are in the same directory as the
+&SConstruct;,
 </para>
 
 <example_commands>
@@ -498,7 +483,7 @@ SConscript('SConscript', variant_dir='build')
 </example_commands>
 
 <para>
-is equivalent to
+is equivalent to:
 </para>
 
 <example_commands>
@@ -507,6 +492,17 @@ 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>
@@ -589,11 +585,11 @@ SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
 
 <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).
+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 all of the scripts. If an executed
+the returns of each of the scripts. If an executed
 script does not explicitly call &Return;, it returns
 <constant>None</constant>.
 </para>