%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> (target[, ...])

Specify default targets to the &SCons; target selection mechanism. Any call to &f-Default; will cause &SCons; to use the defined default target list instead of its built-in algorithm for determining default targets (see the manpage section "Target Selection"). target may be one or more strings, a list of strings, a NodeList as returned by a Builder, or None. A string target may be the name of a file or directory, or a target previously defined by a call to &f-link-Alias; (defining the alias later will still create the alias, but it will not be recognized as a default). Calls to &f-Default; are additive. A target of None will clear any existing default target list; subsequent calls to &f-Default; will add to the (now empty) default target list like normal. Both forms of this call affect the same global list of default targets; the construction environment method applies construction variable expansion to the targets. The current list of targets added using &f-Default; is available in the &DEFAULT_TARGETS; list (see below). Examples: Default('foo', 'bar', 'baz') env.Default(['a', 'b', 'c']) hello = env.Program('hello', 'hello.c') env.Default(hello)

(major, minor)

Ensure that the Python version is at least major.minor. 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. Example: EnsurePythonVersion(2,2)

(major, minor, [revision])

Ensure that the SCons version is at least major.minor, or major.minor.revision. if revision 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. Examples: EnsureSConsVersion(0,14) EnsureSConsVersion(0,96,90)

()

Returns the current SCons version in the form of a Tuple[int, int, int], representing the major, minor, and revision values respectively. Added in 4.8.0.

([value])

This tells &scons; to exit immediately with the specified value. A default exit value of 0 (zero) is used if no value is specified.

([vars...], [key=value...])

Exports variables for sharing with other SConscript files. The variables are added to a global collection where they can be imported by other SConscript files. vars may be one or more strings, or a list of strings. If any string contains whitespace, it is split automatically into individual strings. Each string must match the name of a variable that is in scope during evaluation of the current SConscript file, or an exception is raised. A vars argument may also be a dictionary or individual keyword arguments; in accordance with &Python; syntax rules, keyword arguments must come after any non-keyword arguments. The dictionary/keyword form can be used to map the local name of a variable to a different name to be used for imports. See the Examples for an illustration of the syntax. &f-Export; calls are cumulative. Specifying a previously exported variable will replace the previous value in the collection. Both local variables and global variables can be exported. To use an exported variable, an SConscript must call &f-link-Import; to bring it into its own scope. Importing creates an additional reference to the object that was originally exported, so if that object is mutable, changes made will be visible to other users of that object. Examples: env = Environment() # Make env available for all SConscript files to Import(). Export("env") package = 'my_name' # Make env and package available for all SConscript files:. Export("env", "package") # Make env and package available for all SConscript files: Export(["env", "package"]) # Make env available using the name debug: Export(debug=env) # Make env available using the name debug: Export({"debug": env}) Note that the &f-link-SConscript; function also supports an &exports; argument that allows exporting one or more variables to the SConscript files invoked by that call (only). See the description of that function for details.

()

Returns the absolute path name of the directory from which &scons; was initially invoked. This can be useful when using the -u, -U or -D options, which internally change to the directory in which the &SConstruct; file is found.

(text, append=False, local_only=False)

Adds text to the help message shown when &scons; is called with the -h or --help argument. On the first call to &f-Help;, if append is False (the default), any existing help text is discarded. The default help text is the help for the &scons; command itself plus help collected from any project-local &f-link-AddOption; calls. This is the help printed if &f-Help; has never been called. If append is True, text is appended to the existing help text. If local_only is also True (the default is False), the project-local help from &f-AddOption; calls is preserved in the help message but the &scons; command help is not. Subsequent calls to &f-Help; ignore the keyword arguments append and local_only and always append to the existing help text. Changed in 4.6.0: added local_only.

(vars...)

Imports variables into the scope of the current SConscript file. vars must be strings representing names of variables which have been previously exported either by the &f-link-Export; function or by the &exports; argument to the &f-link-SConscript; function. Variables exported by the &f-SConscript; call take precedence. Multiple variable names can be passed to &f-Import; as separate arguments, as a list of strings, or as words in a space-separated string. The wildcard "*" can be used to import all available variables. If the imported variable is mutable, changes made locally will be reflected in the object the variable is bound to. This allows subsidiary SConscript files to contribute to building up, for example, a &consenv;. Examples: Import("env") Import("env", "variable") Import(["env", "variable"]) Import("*")

([vars..., stop=True])

Return to the calling SConscript, optionally returning the values of variables named in vars. Multiple strings containing variable names may be passed to &f-Return;. A string containing white space 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 to continue processing the rest of the SConscript file after the &f-Return; call (this was the default behavior prior to SCons 0.98.) However, the values returned are still the values of the variables in the named vars at the point &f-Return; was called. Examples: # Returns no values (evaluates False) Return() # Returns the value of the 'foo' Python variable. Return("foo") # Returns the values of the Python variables 'foo' and 'bar'. Return("foo", "bar") # Returns the values of Python variables 'val1' and 'val2'. Return('val1 val2')

(scriptnames, [exports, variant_dir, duplicate, must_exist]) (dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist])

Executes subsidiary SConscript (build configuration) file(s). There are two ways to call the &f-SConscript; function. The first calling style is to supply one or more SConscript file names as the first positional argument, which can be a string or a list of strings. If there is a second positional argument, it is treated as if the exports keyword argument had been given (see below). Examples: SConscript('SConscript') # run SConscript in the current directory SConscript('src/SConscript') # run SConscript in the src directory SConscript(['src/SConscript', 'doc/SConscript']) SConscript(Split('src/SConscript doc/SConscript')) config = SConscript('MyConfig.py') The second calling style is to omit the positional argument naming the script and instead specify directory names using the dirs keyword argument. The value can be a string or list of strings. In this case, &scons; will execute a subsidiary configuration file named &SConscript; (by default) in each of the specified directories. You may specify a name other than &SConscript; by supplying an optional name=scriptname 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=['src', 'doc']) SConscript(dirs=['sub1', 'sub2'], name='MySConscript') The optional exports keyword argument specifies variables to make available for use by the called SConscripts, which are evaluated in an isolated context and otherwise do not have access to local variables from the calling SConscript. The value may be a string or list of strings representing variable names, or a dictionary mapping local names to the names they can be imported by. For the first (scriptnames) calling style, a second positional argument will also be interpreted as exports; the second (directory) calling style accepts no positional arguments and must use the keyword form. These variables are locally exported only to the called SConscript file(s), and take precedence over any same-named variables in the global pool managed by the &f-link-Export; function. The subsidiary SConscript files must use the &f-link-Import; function to import the variables into their local scope. Examples: 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') If the optional variant_dir argument is present, it causes an effect equivalent to the &f-link-VariantDir; function, 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. 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. Thus: SConscript('src/SConscript', variant_dir='build') is equivalent to: VariantDir('build', 'src') SConscript('build/SConscript') If the sources are in the same directory as the &SConstruct;, SConscript('SConscript', variant_dir='build') is equivalent to: VariantDir('build', '.') 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. If the optional must_exist is True (the default), an exception is raised if a requested SConscript file is not found. To allow missing scripts to be silently ignored (the default behavior prior to &SCons; version 3.1), pass must_exist=False in the &f-SConscript; call. Changed in 4.6.0: must_exist now defaults to True. Here are some composite examples: # 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') # 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) # 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) # 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) &f-SConscript; returns the values of any variables 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 each of the scripts. If an executed script does not explicitly call &Return;, it returns None.