From aaf6595eba0f393fe474b42fda7360b734ae590e Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 28 Apr 2020 10:27:20 -0600 Subject: docs: tweak "manpage" (shared) Return, SConscript [ci skip] After previous updates, the manpage part (also shared to the userguide) was a little less precise than it could be. SConscript definition now describes the return value more accurately (e.g. add what happens if multiple scripts called) and moved to its own paragraph (at end) rather than inline. Signed-off-by: Mats Wichmann --- src/engine/SCons/Script/SConscript.xml | 177 ++++++++++++++++----------------- 1 file changed, 83 insertions(+), 94 deletions(-) (limited to 'src') diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml index d42fdace6..8a6a92811 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. -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. -vars 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. +vars 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 vars 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. + + + +&f-Export; calls are cumulative. Specifying a previously +exported variable will overwirte the earlier value. Both local variables and global variables can be exported. @@ -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}) Note that the -&f-SConscript; -function supports an -exports -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. @@ -276,12 +274,12 @@ message. -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. +vars +must be strings representating names of variables +which have been previously exported either by the &f-link-Export; function or by the -exports -argument to +&exports; argument to &f-link-SConscript;. Variables exported by &f-SConscript; @@ -308,29 +306,29 @@ Import("*") -([vars..., stop=]) +([vars..., stop=True]) Return to the calling SConscript, optionally -returning the values of variables named in the -vars -string arguments. +returning the values of variables named in +vars. 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 -False -if no vars 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 vars +is omitted. By default &Return; stops processing the current SConscript and returns immediately. The optional -stop= -keyword argument may be set to a false value +stop +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: -# 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') -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. -The first way you can call -&f-SConscript; +The first calling style is to explicitly specify one or more scripts as the first argument. @@ -408,22 +397,22 @@ config = SConscript('MyConfig.py') -The second way you can call +The second way to call &f-SConscript; is to specify a list of (sub)directory names as a -dirs=subdirs +dirs=subdirs 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 -name=script +name=script 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') The optional exports -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 variant_dir argument is present, it causes an effect equivalent to the -&f-link-VariantDir; -method described below. -(If -variant_dir -is not present, the - -duplicate - -argument is ignored.) -The -variant_dir - +&f-link-VariantDir; function. +The variant_dir 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 +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; +SConscript file resides and the -&SConscript; +SConscript file is evaluated as if it were in the variant_dir directory: -SConscript('src/SConscript', variant_dir = 'build') +SConscript('src/SConscript', variant_dir='build') @@ -524,7 +498,7 @@ in the same directory as the -SConscript('SConscript', variant_dir = 'build') +SConscript('SConscript', variant_dir='build') @@ -570,14 +544,17 @@ TODO??? SConscript('build/SConscript', src_dir='src') -The optional +If the optional must_exist -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 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 emitted, but this default is deprecated +(since 3.1). For scripts which truly intend to be optional, transition to -explicty supplying -must_exist=False to the call. +explicitly supplying +must_exist=False to the &f-SConscript; call. @@ -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) + + +&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 +None. + + -- cgit v1.2.1