From ba4425ab5227fd9597fccd368bffff6bf1032149 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 10 Sep 2011 11:25:53 +0200 Subject: Imported Upstream version 2.1.0 --- src/engine/SCons/Script/SConscript.xml | 509 +++++++++++++++++++++++++++++++++ 1 file changed, 509 insertions(+) create mode 100644 src/engine/SCons/Script/SConscript.xml (limited to 'src/engine/SCons/Script/SConscript.xml') diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml new file mode 100644 index 0000000..f24ca78 --- /dev/null +++ b/src/engine/SCons/Script/SConscript.xml @@ -0,0 +1,509 @@ + + + + +(targets) + + +This specifies a list of default targets, +which will be built by +&scons; +if no explicit targets are given on the command line. +Multiple calls to +&f-Default; +are legal, +and add to the list of default targets. + +Multiple targets should be specified as +separate arguments to the +&f-Default; +method, or as a list. +&f-Default; +will also accept the Node returned by any +of a construction environment's +builder methods. + +Examples: + + +Default('foo', 'bar', 'baz') +env.Default(['a', 'b', 'c']) +hello = env.Program('hello', 'hello.c') +env.Default(hello) + + +An argument to +&f-Default; +of +None +will clear all default targets. +Later calls to +&f-Default; +will add to the (now empty) default-target list +like normal. + +The current list of targets added using the +&f-Default; +function or method is available in the +DEFAULT_TARGETS +list; +see below. + + + + + +(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) + + + + + + +([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) + + +This tells +&scons; +to export a list of variables from the current +SConscript file to all other SConscript files. +The exported variables are kept in a global collection, +so subsequent calls to +&f-Export; +will over-write previous exports that have the same name. +Multiple variable names can be passed to +&f-Export; +as separate arguments or as a list. +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. +Both local variables and global variables can be exported. + +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-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-SConscript; +function, below. + + + + + +() + + +Returns the absolute path name of the directory from which +&scons; +was initially invoked. +This can be useful when using the +, + +or + +options, which internally +change to the directory in which the +&SConstruct; +file is found. + + + + + +(text) + + +This specifies help text to be printed if the + +argument is given to +&scons;. +If +&f-Help; +is called multiple times, the text is appended together in the order +that +&f-Help; +is called. + + + + + +(vars) + + +This tells +&scons; +to import a list of variables into the current SConscript file. This +will import variables that were exported with +&f-Export; +or in the +exports +argument to +&f-link-SConscript;. +Variables exported by +&f-SConscript; +have precedence. +Multiple variable names can be passed to +&f-Import; +as separate arguments or as a list. The variable "*" can be used +to import all variables. + +Examples: + + +Import("env") +Import("env", "variable") +Import(["env", "variable"]) +Import("*") + + + + + + +([vars..., stop=]) + + +By default, +this stops processing the current SConscript +file and returns to the calling SConscript file +the values of the variables named in the +vars +string arguments. +Multiple strings contaning variable names may be passed to +&f-Return;. +Any strings that contain white space + +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; +is called. + +Examples: + + +# Returns without returning a value. +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') + + + + + + +(scripts, [exports, variant_dir, duplicate]) + + + +(dirs=subdirs, [name=script, exports, variant_dir, duplicate]) + + + +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;. +There are two ways to call the +&f-SConscript; +function. + +The first way you can call +&f-SConscript; +is to explicitly specify one or more +scripts +as the first argument. +A single script may be specified as a string; +multiple scripts must be specified as a list +(either explicitly or as created by +a function like +&f-Split;). +Examples: + +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 you can call +&f-SConscript; +is to specify a list of (sub)directory names +as a +dirs=subdirs +keyword argument. +In this case, +&scons; +will, by default, +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 +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 +argument provides a list of variable names or a dictionary of +named values to export to the +script(s). +These variables are locally exported only to the specified +script(s), +and do not affect the global pool of variables used by the +&f-Export; +function. + +The subsidiary +script(s) +must use the +&f-link-Import; +function to import the variables. +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; +method described below. +(If +variant_dir +is not present, the + +duplicate + +argument is ignored.) +The +variant_dir + +argument is interpreted relative to the directory of the calling +&SConscript; +file. +See the description of the +&f-VariantDir; +function 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; +file is evaluated as if it were in the +variant_dir +directory: + +SConscript('src/SConscript', variant_dir = 'build') + + +is equivalent to + + +VariantDir('build', 'src') +SConscript('build/SConscript') + + +This later paradigm is often used when the sources are +in the same directory as the +&SConstruct;: + + +SConscript('SConscript', variant_dir = 'build') + + +is equivalent to + + +VariantDir('build', '.') +SConscript('build/SConscript') + + + + +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) + + + -- cgit v1.2.3