From cdb1d2163a927981e9dab9f977094537e7b0d959 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 15 May 2022 09:44:59 -0600 Subject: Try to improve variantdir docs [skip appveyor] Reorder some bits, add some explantaions, include example of passing different environments to subsidiary SConscript. Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 64 ++++++++++++++++++++++----------------------- SCons/Script/SConscript.xml | 56 ++++++++++++++++++--------------------- 2 files changed, 57 insertions(+), 63 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 3a6df97..79289c3 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -3416,42 +3416,35 @@ env.UpdateValue(target = Value(output), source = Value(input)) -Sets up an alternate build location. -When building in the variant_dir, -&SCons; backfills as needed with files from src_dir -to create a complete build directory. +Sets up a mapping to define a variant build directory +variant_dir, +which must be in or underneath the project top directory. +src_dir may not be underneath +variant_dir. +A &f-VariantDir; mapping is global, even if called using the +the &f-env-VariantDir; form. &f-VariantDir; can be called multiple times with the same src_dir -to set up multiple builds with different options -(variants). - - - -The -variant -location must be in or underneath the project top directory, -and src_dir -may not be underneath -variant_dir. +to set up multiple variant builds with different options. +When files in variant_dir are referenced, +&SCons; backfills as needed with files from src_dir +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 variant_dir. - - - If possible on the platform, the duplication is performed by linking rather than copying. This behavior is affected by the @@ -3470,38 +3463,43 @@ to invoke Builders using the path names of source files in src_dir and the path names of derived files within variant_dir. -This is more efficient than -duplicate=True, +This is more efficient than duplicating, and is safe for most builds; -revert to True +revert to duplicate=True if it causes problems. &f-VariantDir; works most naturally with used with a subsidiary SConscript file. -The subsidiary SConscript file is called as if it -were in +The subsidiary SConscript file must be called as if it were in variant_dir, regardless of the value of duplicate. +When calling an SConscript file, +you can pass an appropriately set up environment +using the exports keyword +argument so the SConscript can pick up the right settings +for that variant build. This is how you tell &scons; -which variant of a source tree to build: +which variant of a source directory to build: +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}) 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. diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml index 3c5b907..0710ea5 100644 --- a/SCons/Script/SConscript.xml +++ b/SCons/Script/SConscript.xml @@ -368,7 +368,7 @@ Return('val1 val2') -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. @@ -395,8 +395,8 @@ config = SConscript('MyConfig.py') The second way to call &f-SConscript; -is to specify a list of (sub)directory names -as a +is to specify a list of directory names +using the dirs=subdirs keyword argument. In this case, @@ -448,38 +448,24 @@ SConscript(dirs=['one', 'two', 'three'], exports='shared_info') If the optional variant_dir argument is present, it causes an effect equivalent to the -&f-link-VariantDir; function. +&f-link-VariantDir; function, +but in effect only during the execution of the SConscript file. The variant_dir -argument is interpreted relative to the directory of the calling -SConscript file. -The optional -duplicate argument is -interpreted as for &f-link-VariantDir;. -If variant_dir -is omitted, the duplicate argument is ignored. -See the description of -&f-link-VariantDir; -below for additional details and restrictions. - - - -If -variant_dir -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 +calling SConscript file. +The source directory is the directory in which the +called SConscript +file resides and the SConscript file is evaluated as if it were in the variant_dir -directory: +directory. Thus: SConscript('src/SConscript', variant_dir='build') -is equivalent to +is equivalent to: @@ -488,9 +474,8 @@ SConscript('build/SConscript') -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;, @@ -498,7 +483,7 @@ SConscript('SConscript', variant_dir='build') -is equivalent to +is equivalent to: @@ -507,6 +492,17 @@ SConscript('build/SConscript') +The optional +duplicate argument is +interpreted as for &f-link-VariantDir;. +If the variant_dir argument +is omitted, the duplicate argument is ignored. +See the description of +&f-link-VariantDir; +for additional details and restrictions. + + + -(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist]) - +(dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist]) + @@ -374,31 +374,27 @@ There are two ways to call the -The first calling style -is to explicitly specify one or more -scripts -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: -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') -The second way to call -&f-SConscript; -is to specify a list of directory names -using the -dirs=subdirs -keyword argument. +The other calling style is to omit the positional argument naming +scripts and instead specify a list of directory names using the +dirs keyword argument. In this case, &scons; will @@ -408,14 +404,13 @@ in each of the specified directories. You may specify a name other than &SConscript; by supplying an optional -name=script -keyword argument. +name keyword argument. The first three examples below have the same effect as the first three examples above: -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') @@ -423,8 +418,12 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript') The optional exports -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 exports; the +second calling style must use the keyword argument form +for exports. These variables are locally exported only to the called SConscript file(s) and do not affect the global pool of variables managed by the @@ -585,11 +584,11 @@ SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0) &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 None. -- cgit v0.12 From 45e9eec5a86adcd815a9bebfba536a44c7f9a756 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 17 May 2022 09:01:11 -0600 Subject: Fix grammar error ("the the") [ci skip] Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 3700a44..346fc75 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -3421,7 +3421,7 @@ Sets up a mapping to define a variant build directory in src_dir may not be underneath variant_dir. A &f-VariantDir; mapping is global, even if called using the -the &f-env-VariantDir; form. +&f-env-VariantDir; form. &f-VariantDir; can be called multiple times with the same src_dir -- cgit v0.12 From b14c20e353712291e0321c0fa1e7557bf385ea04 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 23 May 2022 08:18:51 -0600 Subject: Further tweak of VariantDir doc [skip appveyor] Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 346fc75..294562d 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -3482,14 +3482,11 @@ The subsidiary SConscript file must be called as if it were in variant_dir, regardless of the value of duplicate. -When calling an SConscript file, -you can pass an appropriately set up environment -using the exports keyword -argument so the SConscript can pick up the right settings -for that variant build. -This is how you tell -&scons; -which variant of a source directory to build: +When calling an SConscript file, you can use the +exports 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: @@ -3511,7 +3508,7 @@ in conjunction with calling a subsidiary SConscript file. -Examples: +More examples: -- cgit v0.12 From cf2641d678eb6142f5f00e686f8e4d46959267ee Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 25 May 2022 13:31:38 -0600 Subject: Typo fix [ci skip] Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 294562d..5c4326c 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -318,7 +318,7 @@ Added methods propagate through &f-env-Clone; calls. -Examples: +More examples: @@ -3477,7 +3477,7 @@ if it causes problems. &f-VariantDir; -works most naturally with used with a subsidiary SConscript file. +works most naturally when used with a subsidiary SConscript file. The subsidiary SConscript file must be called as if it were in variant_dir, regardless of the value of -- cgit v0.12 From a4daaa6d49f7f5972e8d7d083d492068b1a5d362 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 26 May 2022 06:41:09 -0600 Subject: SConscript doc tweaks per #4150 review comments [skip appveyor] Signed-off-by: Mats Wichmann --- SCons/Script/SConscript.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml index 17c9236..eb52acc 100644 --- a/SCons/Script/SConscript.xml +++ b/SCons/Script/SConscript.xml @@ -404,7 +404,8 @@ in each of the specified directories. You may specify a name other than &SConscript; by supplying an optional -name keyword argument. +name=scriptname +keyword argument. The first three examples below have the same effect as the first three examples above: @@ -448,7 +449,7 @@ If the optional variant_dir argument is present, it causes an effect equivalent to the &f-link-VariantDir; function, -but in effect only during the execution of the SConscript file. +but in effect only within the scope of the &f-SConscript; call. The variant_dir argument is interpreted relative to the directory of the calling SConscript file. -- cgit v0.12