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/Environment.xml | 2973 +++++++++++++++++++++++++++++++++++++- 1 file changed, 2972 insertions(+), 1 deletion(-) (limited to 'src/engine/SCons/Environment.xml') diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 4e5408f..85ba340 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -1,9 +1,12 @@ + + + A dictionary mapping the names of the builders @@ -185,3 +188,2971 @@ A list of the names of the Tool specifications that are part of this construction environment. + + + + + +(action, [cmd/str/fun, [var, ...]] [option=value, ...]) + + +Creates an Action object for +the specified +action. +See the section "Action Objects," +below, for a complete explanation of the arguments and behavior. + +Note that the +env.Action() +form of the invocation will expand +construction variables in any argument strings, +including the +action +argument, at the time it is called +using the construction variables in the +env +construction environment through which +env.Action() +was called. +The +Action() +form delays all variable expansion +until the Action object is actually used. + + + + + +(object, function, [name]) + + +(function, [name]) + + +When called with the +AddMethod() +form, +adds the specified +function +to the specified +object +as the specified method +name. +When called with the +env.AddMethod() +form, +adds the specified +function +to the construction environment +env +as the specified method +name. +In both cases, if +name +is omitted or +None, +the name of the +specified +function +itself is used for the method name. + +Examples: + + +# Note that the first argument to the function to +# be attached as a method must be the object through +# which the method will be called; the Python +# convention is to call it 'self'. +def my_method(self, arg): + print "my_method() got", arg + +# Use the global AddMethod() function to add a method +# to the Environment class. This +AddMethod(Environment, my_method) +env = Environment() +env.my_method('arg') + +# Add the function as a method, using the function +# name for the method call. +env = Environment() +env.AddMethod(my_method, 'other_method_name') +env.other_method_name('another arg') + + + + + + +(target, action) + + +Arranges for the specified +action +to be performed +after the specified +target +has been built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). + +When multiple targets are supplied, +the action may be called multiple times, +once after each action that generates +one or more targets in the list. + + + + + +(target, action) + + +Arranges for the specified +action +to be performed +before the specified +target +is built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). + +When multiple targets are specified, +the action(s) may be called multiple times, +once before each action that generates +one or more targets in the list. + +Note that if any of the targets are built in multiple steps, +the action will be invoked just +before the "final" action that specifically +generates the specified target(s). +For example, when building an executable program +from a specified source +.c +file via an intermediate object file: + + +foo = Program('foo.c') +AddPreAction(foo, 'pre_action') + + +The specified +pre_action +would be executed before +&scons; +calls the link command that actually +generates the executable program binary +foo, +not before compiling the +foo.c +file into an object file. + + + + + +(alias, [targets, [action]]) + + +Creates one or more phony targets that +expand to one or more other targets. +An optional +action +(command) +or list of actions +can be specified that will be executed +whenever the any of the alias targets are out-of-date. +Returns the Node object representing the alias, +which exists outside of any file system. +This Node object, or the alias name, +may be used as a dependency of any other target, +including another alias. +&f-Alias; +can be called multiple times for the same +alias to add additional targets to the alias, +or additional actions to the list for this alias. + +Examples: + + +Alias('install') +Alias('install', '/usr/bin') +Alias(['install', 'install-lib'], '/usr/local/lib') + +env.Alias('install', ['/usr/local/bin', '/usr/local/lib']) +env.Alias('install', ['/usr/local/man']) + +env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") + + + + + + +(target, ...) + + +Marks each given +target +so that it is always assumed to be out of date, +and will always be rebuilt if needed. +Note, however, that +&f-AlwaysBuild; +does not add its target(s) to the default target list, +so the targets will only be built +if they are specified on the command line, +or are a dependent of a target specified on the command line--but +they will +always +be built if so specified. +Multiple targets can be passed in to a single call to +&f-AlwaysBuild;. + + + + + +(key=val, [...]) + + +Appends the specified keyword arguments +to the end of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the values of the construction variable +and the keyword argument are the same type, +then the two values will be simply added together. +Otherwise, the construction variable +and the value of the keyword argument +are both coerced to lists, +and the lists are added together. +(See also the Prepend method, below.) + +Example: + + +env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) + + + + + + +(name, newpath, [envname, sep, delete_existing]) + + +This appends new path elements to the given path in the +specified external environment +(ENV +by default). +This will only add +any particular path once (leaving the last one it encounters and +ignoring the rest, to preserve path order), +and to help assure this, +will normalize all paths (using +os.path.normpath +and +os.path.normcase). +This can also handle the +case where the given old path variable is a list instead of a +string, in which case a list will be returned instead of a string. + +If +delete_existing +is 0, then adding a path that already exists +will not move it to the end; it will stay where it is in the list. + +Example: + + +print 'before:',env['ENV']['INCLUDE'] +include_path = '/foo/bar:/foo' +env.AppendENVPath('INCLUDE', include_path) +print 'after:',env['ENV']['INCLUDE'] + +yields: +before: /foo:/biz +after: /biz:/foo/bar:/foo + + + + + + +(key=val, [...], delete_existing=0) + + +Appends the specified keyword arguments +to the end of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the construction variable being appended to is a list, +then any value(s) that already exist in the +construction variable will +not +be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the end of the list. + +Example: + + +env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) + + + + + + +(build_dir, src_dir, [duplicate]) + + +Deprecated synonyms for +&f-VariantDir; +and +env.VariantDir(). +The +build_dir +argument becomes the +variant_dir +argument of +&f-VariantDir; +or +env.VariantDir(). + + + + + +(action, [arguments]) + + +Creates a Builder object for +the specified +action. +See the section "Builder Objects," +below, for a complete explanation of the arguments and behavior. + +Note that the +env.Builder() +form of the invocation will expand +construction variables in any arguments strings, +including the +action +argument, +at the time it is called +using the construction variables in the +env +construction environment through which +env.Builder() +was called. +The +&f-Builder; +form delays all variable expansion +until after the Builder object is actually called. + + + + + +(cache_dir) + + +Specifies that +&scons; +will maintain a cache of derived files in +cache_dir. +The derived files in the cache will be shared +among all the builds using the same +&f-CacheDir; +call. +Specifying a +cache_dir +of +None +disables derived file caching. + +Calling +env.CacheDir() +will only affect targets built +through the specified construction environment. +Calling +&f-CacheDir; +sets a global default +that will be used by all targets built +through construction environments +that do +not +have an +env.CacheDir() +specified. + +When a +CacheDir() +is being used and +&scons; +finds a derived file that needs to be rebuilt, +it will first look in the cache to see if a +derived file has already been built +from identical input files and an identical build action +(as incorporated into the MD5 build signature). +If so, +&scons; +will retrieve the file from the cache. +If the derived file is not present in the cache, +&scons; +will rebuild it and +then place a copy of the built file in the cache +(identified by its MD5 build signature), +so that it may be retrieved by other +builds that need to build the same derived file +from identical inputs. + +Use of a specified +&f-CacheDir; +may be disabled for any invocation +by using the + +option. + +If the + +option is used, +&scons; +will place a copy of +all +derived files in the cache, +even if they already existed +and were not built by this invocation. +This is useful to populate a cache +the first time +&f-CacheDir; +is added to a build, +or after using the + +option. + +When using +&f-CacheDir;, +&scons; +will report, +"Retrieved `file' from cache," +unless the + +option is being used. +When the + +option is used, +&scons; +will print the action that +would +have been used to build the file, +without any indication that +the file was actually retrieved from the cache. +This is useful to generate build logs +that are equivalent regardless of whether +a given derived file has been built in-place +or retrieved from the cache. + +The +&f-link-NoCache; +method can be used to disable caching of specific files. This can be +useful if inputs and/or outputs of some tool are impossible to +predict or prohibitively large. + + + + + +(targets, files_or_dirs) + + +This specifies a list of files or directories which should be removed +whenever the targets are specified with the + +command line option. +The specified targets may be a list +or an individual target. +Multiple calls to +&f-Clean; +are legal, +and create new targets or add files and directories to the +clean list for the specified targets. + +Multiple files or directories should be specified +either as separate arguments to the +&f-Clean; +method, or as a list. +&f-Clean; +will also accept the return value of any of the construction environment +Builder methods. +Examples: + +The related +&f-link-NoClean; +function overrides calling +&f-Clean; +for the same target, +and any targets passed to both functions will +not +be removed by the + +option. + +Examples: + + +Clean('foo', ['bar', 'baz']) +Clean('dist', env.Program('hello', 'hello.c')) +Clean(['foo', 'bar'], 'something_else_to_clean') + + +In this example, +installing the project creates a subdirectory for the documentation. +This statement causes the subdirectory to be removed +if the project is deinstalled. + +Clean(docdir, os.path.join(docdir, projectname)) + + + + + + +([key=val, ...]) + + +Returns a separate copy of a construction environment. +If there are any keyword arguments specified, +they are added to the returned copy, +overwriting any existing values +for the keywords. + +Example: + + +env2 = env.Clone() +env3 = env.Clone(CCFLAGS = '-g') + + +Additionally, a list of tools and a toolpath may be specified, as in +the Environment constructor: + + +def MyTool(env): env['FOO'] = 'bar' +env4 = env.Clone(tools = ['msvc', MyTool]) + + +The +parse_flags +keyword argument is also recognized: + + +# create an environment for compiling programs that use wxWidgets +wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') + + + + + + +The &b-Command; "Builder" is actually implemented +as a function that looks like a Builder, +but actually takes an additional argument of the action +from which the Builder should be made. +See the &f-link-Command; function description +for the calling syntax and details. + + + + + +(target, source, action, [key=val, ...]) + + +Executes a specific action +(or list of actions) +to build a target file or files. +This is more convenient +than defining a separate Builder object +for a single special-case build. + +As a special case, the +source_scanner +keyword argument can +be used to specify +a Scanner object +that will be used to scan the sources. +(The global +DirScanner +object can be used +if any of the sources will be directories +that must be scanned on-disk for +changes to files that aren't +already specified in other Builder of function calls.) + +Any other keyword arguments specified override any +same-named existing construction variables. + +An action can be an external command, +specified as a string, +or a callable Python object; +see "Action Objects," below, +for more complete information. +Also note that a string specifying an external command +may be preceded by an +@ +(at-sign) +to suppress printing the command in question, +or by a +- +(hyphen) +to ignore the exit status of the external command. + +Examples: + + +env.Command('foo.out', 'foo.in', + "$FOO_BUILD < $SOURCES > $TARGET") + +env.Command('bar.out', 'bar.in', + ["rm -f $TARGET", + "$BAR_BUILD < $SOURCES > $TARGET"], + ENV = {'PATH' : '/usr/local/bin/'}) + +def rename(env, target, source): + import os + os.rename('.tmp', str(target[0])) + +env.Command('baz.out', 'baz.in', + ["$BAZ_BUILD < $SOURCES > .tmp", + rename ]) + + +Note that the +&f-Command; +function will usually assume, by default, +that the specified targets and/or sources are Files, +if no other part of the configuration +identifies what type of entry it is. +If necessary, you can explicitly specify +that targets or source nodes should +be treated as directoriese +by using the +&f-link-Dir; +or +env.Dir() +functions. + +Examples: + + +env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') + +env['DISTDIR'] = 'destination/directory' +env.Command(env.Dir('$DISTDIR')), None, make_distdir) + + +(Also note that SCons will usually +automatically create any directory necessary to hold a target file, +so you normally don't need to create directories by hand.) + + + + + +(env, [custom_tests, conf_dir, log_file, config_h]) + + +([custom_tests, conf_dir, log_file, config_h]) + + +Creates a Configure object for integrated +functionality similar to GNU autoconf. +See the section "Configure Contexts," +below, for a complete explanation of the arguments and behavior. + + + + + +([key=val, ...]) + + +A now-deprecated synonym for +env.Clone(). + + + + + +(function) + + +Specifies that all up-to-date decisions for +targets built through this construction environment +will be handled by the specified +function. +The +function +can be one of the following strings +that specify the type of decision function +to be performed: + + + +timestamp-newer + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is newer than the target file's timestamp. +This is the behavior of the classic Make utility, +and +make +can be used a synonym for +timestamp-newer. + + + + +timestamp-match + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is different than the +timestamp recorded the last time the target was built. +This provides behavior very similar to the classic Make utility +(in particular, files are not opened up so that their +contents can be checksummed) +except that the target will also be rebuilt if a +dependency file has been restored to a version with an +earlier +timestamp, such as can happen when restoring files from backup archives. + + + + +MD5 + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's content has changed sine the last time +the target was built, +as determined be performing an MD5 checksum +on the dependency's contents +and comparing it to the checksum recorded the +last time the target was built. +content +can be used as a synonym for +MD5. + + + + +MD5-timestamp + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's content has changed sine the last time +the target was built, +except that dependencies with a timestamp that matches +the last time the target was rebuilt will be +assumed to be up-to-date and +not +rebuilt. +This provides behavior very similar +to the +MD5 +behavior of always checksumming file contents, +with an optimization of not checking +the contents of files whose timestamps haven't changed. +The drawback is that SCons will +not +detect if a file's content has changed +but its timestamp is the same, +as might happen in an automated script +that runs a build, +updates a file, +and runs the build again, +all within a single second. + + + + + +Examples: + + +# Use exact timestamp matches by default. +Decider('timestamp-match') + +# Use MD5 content signatures for any targets built +# with the attached construction environment. +env.Decider('content') + + +In addition to the above already-available functions, +the +function +argument may be an actual Python function +that takes the following three arguments: + + + +dependency + + +The Node (file) which +should cause the +target +to be rebuilt +if it has "changed" since the last tme +target +was built. + + + + +target + + +The Node (file) being built. +In the normal case, +this is what should get rebuilt +if the +dependency +has "changed." + + + + +prev_ni + + +Stored information about the state of the +dependency +the last time the +target +was built. +This can be consulted to match various +file characteristics +such as the timestamp, +size, or content signature. + + + + + +The +function +should return a +True +(non-zero) +value if the +dependency +has "changed" since the last time +the +target +was built +(indicating that the target +should +be rebuilt), +and +False +(zero) +otherwise +(indicating that the target should +not +be rebuilt). +Note that the decision can be made +using whatever criteria are appopriate. +Ignoring some or all of the function arguments +is perfectly normal. + +Example: + + +def my_decider(dependency, target, prev_ni): + return not os.path.exists(str(target)) + +env.Decider(my_decider) + + + + + + +(target, dependency) + + +Specifies an explicit dependency; +the +target +will be rebuilt +whenever the +dependency +has changed. +Both the specified +target +and +dependency +can be a string +(usually the path name of a file or directory) +or Node objects, +or a list of strings or Node objects +(such as returned by a Builder call). +This should only be necessary +for cases where the dependency +is not caught by a Scanner +for the file. + +Example: + + +env.Depends('foo', 'other-input-file-for-foo') + +mylib = env.Library('mylib.c') +installed_lib = env.Install('lib', mylib) +bar = env.Program('bar.c') + +# Arrange for the library to be copied into the installation +# directory before trying to build the "bar" program. +# (Note that this is for example only. A "real" library +# dependency would normally be configured through the $LIBS +# and $LIBPATH variables, not using an env.Depends() call.) + +env.Depends(bar, installed_lib) + + + + + + +([vars]) + + +Returns a dictionary object +containing copies of all of the +construction variables in the environment. +If there are any variable names specified, +only the specified construction +variables are returned in the dictionary. + +Example: + + +dict = env.Dictionary() +cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') + + + + + + +(name, [directory]) + + +This returns a Directory Node, +an object that represents the specified directory +name. +name +can be a relative or absolute path. +directory +is an optional directory that will be used as the parent directory. +If no +directory +is specified, the current script's directory is used as the parent. + +If +name +is a list, SCons returns a list of Dir nodes. +Construction variables are expanded in +name. + +Directory Nodes can be used anywhere you +would supply a string as a directory name +to a Builder method or function. +Directory Nodes have attributes and methods +that are useful in many situations; +see "File and Directory Nodes," below. + + + + + +([key]) + + +Returns a pretty printable representation of the environment. +key, +if not +None, +should be a string containing the name of the variable of interest. + +This SConstruct: + + +env=Environment() +print env.Dump('CCCOM') + + +will print: + + +'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' + + +While this SConstruct: + + +env=Environment() +print env.Dump() + + +will print: + +{ 'AR': 'ar', + 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET', + 'ARFLAGS': ['r'], + 'AS': 'as', + 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', + 'ASFLAGS': [], + ... + + + + + + +([key=value, ...]) + + +Return a new construction environment +initialized with the specified +key=value +pairs. + + + + + +(action, [strfunction, varlist]) + + +Executes an Action object. +The specified +action +may be an Action object +(see the section "Action Objects," +below, for a complete explanation of the arguments and behavior), +or it may be a command-line string, +list of commands, +or executable Python function, +each of which will be converted +into an Action object +and then executed. +The exit value of the command +or return value of the Python function +will be returned. + +Note that +&scons; +will print an error message if the executed +action +fails--that is, +exits with or returns a non-zero value. +&scons; +will +not, +however, +automatically terminate the build +if the specified +action +fails. +If you want the build to stop in response to a failed +&f-Execute; +call, +you must explicitly check for a non-zero return value: + + +Execute(Copy('file.out', 'file.in')) + +if Execute("mkdir sub/dir/ectory"): + # The mkdir failed, don't try to build. + Exit(1) + + + + + + +(name, [directory]) + + +This returns a +File Node, +an object that represents the specified file +name. +name +can be a relative or absolute path. +directory +is an optional directory that will be used as the parent directory. + +If +name +is a list, SCons returns a list of File nodes. +Construction variables are expanded in +name. + +File Nodes can be used anywhere you +would supply a string as a file name +to a Builder method or function. +File Nodes have attributes and methods +that are useful in many situations; +see "File and Directory Nodes," below. + + + + + +(file, dirs) + + +Search for +file +in the path specified by +dirs. +dirs +may be a list of directory names or a single directory name. +In addition to searching for files that exist in the filesystem, +this function also searches for derived files +that have not yet been built. + +Example: + + +foo = env.FindFile('foo', ['dir1', 'dir2']) + + + + + + +() + + +Returns the list of targets set up by the +&b-link-Install; +or +&b-link-InstallAs; +builders. + +This function serves as a convenient method to select the contents of +a binary package. + +Example: + + +Install( '/bin', [ 'executable_a', 'executable_b' ] ) + +# will return the file node list +# [ '/bin/executable_a', '/bin/executable_b' ] +FindInstalledFiles() + +Install( '/lib', [ 'some_library' ] ) + +# will return the file node list +# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ] +FindInstalledFiles() + + + + + + +(node='"."') + + +Returns the list of nodes which serve as the source of the built files. +It does so by inspecting the dependency tree starting at the optional +argument +node +which defaults to the '"."'-node. It will then return all leaves of +node. +These are all children which have no further children. + +This function is a convenient method to select the contents of a Source +Package. + +Example: + + +Program( 'src/main_a.c' ) +Program( 'src/main_b.c' ) +Program( 'main_c.c' ) + +# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c'] +FindSourceFiles() + +# returns ['src/main_b.c', 'src/main_a.c' ] +FindSourceFiles( 'src' ) + + +As you can see build support files (SConstruct in the above example) +will also be returned by this function. + + + + + +(sequence) + + +Takes a sequence (that is, a Python list or tuple) +that may contain nested sequences +and returns a flattened list containing +all of the individual elements in any sequence. +This can be helpful for collecting +the lists returned by calls to Builders; +other Builders will automatically +flatten lists specified as input, +but direct Python manipulation of +these lists does not. + +Examples: + + +foo = Object('foo.c') +bar = Object('bar.c') + +# Because `foo' and `bar' are lists returned by the Object() Builder, +# `objects' will be a list containing nested lists: +objects = ['f1.o', foo, 'f2.o', bar, 'f3.o'] + +# Passing such a list to another Builder is all right because +# the Builder will flatten the list automatically: +Program(source = objects) + +# If you need to manipulate the list directly using Python, you need to +# call Flatten() yourself, or otherwise handle nested lists: +for object in Flatten(objects): + print str(object) + + + + + + +(file, [...]) + + +Returns the +&scons; +path name (or names) for the specified +file +(or files). +The specified +file +or files +may be +&scons; +Nodes or strings representing path names. + + + + + +(pattern, [ondisk, source, strings]) + + +Returns Nodes (or strings) that match the specified +pattern, +relative to the directory of the current +&SConscript; +file. +The +env.Glob() +form performs string substition on +pattern +and returns whatever matches +the resulting expanded pattern. + +The specified +pattern +uses Unix shell style metacharacters for matching: + + + * matches everything + ? matches any single character + [seq] matches any character in seq + [!seq] matches any char not in seq + + +If the first character of a filename is a dot, +it must be matched explicitly. +Character matches do +not +span directory separators. + +The +&f-Glob; +knows about +repositories +(see the +&f-link-Repository; +function) +and source directories +(see the +&f-link-VariantDir; +function) +and +returns a Node (or string, if so configured) +in the local (SConscript) directory +if matching Node is found +anywhere in a corresponding +repository or source directory. + +The +ondisk +argument may be set to +False +(or any other non-true value) +to disable the search for matches on disk, +thereby only returning matches among +already-configured File or Dir Nodes. +The default behavior is to +return corresponding Nodes +for any on-disk matches found. + +The +source +argument may be set to +True +(or any equivalent value) +to specify that, +when the local directory is a +&f-VariantDir;, +the returned Nodes should be from the +corresponding source directory, +not the local directory. + +The +strings +argument may be set to +True +(or any equivalent value) +to have the +&f-Glob; +function return strings, not Nodes, +that represent the matched files or directories. +The returned strings will be relative to +the local (SConscript) directory. +(Note that This may make it easier to perform +arbitrary manipulation of file names, +but if the returned strings are +passed to a different +&SConscript; +file, +any Node translation will be relative +to the other +&SConscript; +directory, +not the original +&SConscript; +directory.) + +Examples: + + +Program('foo', Glob('*.c')) +Zip('/tmp/everything', Glob('.??*') + Glob('*')) + + + + + + + + +(target, dependency) + + +The specified dependency file(s) +will be ignored when deciding if +the target file(s) need to be rebuilt. + +You can also use +&f-Ignore; +to remove a target from the default build. +In order to do this you must specify the directory the target will +be built in as the target, and the file you want to skip building +as the dependency. + +Note that this will only remove the dependencies listed from +the files built by default. It will still be built if that +dependency is needed by another object being built. +See the third and forth examples below. + +Examples: + + +env.Ignore('foo', 'foo.c') +env.Ignore('bar', ['bar1.h', 'bar2.h']) +env.Ignore('.','foobar.obj') +env.Ignore('bar','bar/foobar.obj') + + + + + + +(string) + + +The specified +string +will be preserved as-is +and not have construction variables expanded. + + + + + +(targets) + + +The specified +targets +will have copies made in the local tree, +even if an already up-to-date copy +exists in a repository. +Returns a list of the target Node or Nodes. + + + + + + + +(arg, [unique]) + + +Merges the specified +arg +values to the construction environment's construction variables. +If the +arg +argument is not a dictionary, +it is converted to one by calling +&f-link-env-ParseFlags; +on the argument +before the values are merged. +Note that +arg +must be a single value, +so multiple strings must +be passed in as a list, +not as separate arguments to +&f-env-MergeFlags;. + +By default, +duplicate values are eliminated; +you can, however, specify +unique=0 +to allow duplicate +values to be added. +When eliminating duplicate values, +any construction variables that end with +the string +PATH +keep the left-most unique value. +All other construction variables keep +the right-most unique value. + +Examples: + + +# Add an optimization flag to $CCFLAGS. +env.MergeFlags('-O3') + +# Combine the flags returned from running pkg-config with an optimization +# flag and merge the result into the construction variables. +env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) + +# Combine an optimization flag with the flags returned from running pkg-config +# twice and merge the result into the construction variables. +env.MergeFlags(['-O3', + '!pkg-config gtk+-2.0 --cflags --libs', + '!pkg-config libpng12 --cflags --libs']) + + + + + + +(target, ...) + + +Specifies a list of files which should +not +be cached whenever the +&f-link-CacheDir; +method has been activated. +The specified targets may be a list +or an individual target. + +Multiple files should be specified +either as separate arguments to the +&f-NoCache; +method, or as a list. +&f-NoCache; +will also accept the return value of any of the construction environment +Builder methods. + +Calling +&f-NoCache; +on directories and other non-File Node types has no effect because +only File Nodes are cached. + +Examples: + + +NoCache('foo.elf') +NoCache(env.Program('hello', 'hello.c')) + + + + + + +(target, ...) + + +Specifies a list of files or directories which should +not +be removed whenever the targets (or their dependencies) +are specified with the + +command line option. +The specified targets may be a list +or an individual target. +Multiple calls to +&f-NoClean; +are legal, +and prevent each specified target +from being removed by calls to the + +option. + +Multiple files or directories should be specified +either as separate arguments to the +&f-NoClean; +method, or as a list. +&f-NoClean; +will also accept the return value of any of the construction environment +Builder methods. + +Calling +&f-NoClean; +for a target overrides calling +&f-link-Clean; +for the same target, +and any targets passed to both functions will +not +be removed by the + +option. + +Examples: + + +NoClean('foo.elf') +NoClean(env.Program('hello', 'hello.c')) + + + + + + +(command, [function, unique]) + + +Calls the specified +function +to modify the environment as specified by the output of +command. +The default +function +is +&f-link-env-MergeFlags;, +which expects the output of a typical +*-config +command +(for example, +gtk-config) +and adds the options +to the appropriate construction variables. +By default, +duplicate values are not +added to any construction variables; +you can specify +unique=0 +to allow duplicate +values to be added. + +Interpreted options +and the construction variables they affect +are as specified for the +&f-link-env-ParseFlags; +method (which this method calls). +See that method's description, below, +for a table of options and construction variables. + + + + + +(filename, [must_exist, only_one]) + + +Parses the contents of the specified +filename +as a list of dependencies in the style of +&Make; +or +mkdep, +and explicitly establishes all of the listed dependencies. + +By default, +it is not an error +if the specified +filename +does not exist. +The optional +must_exist +argument may be set to a non-zero +value to have +scons +throw an exception and +generate an error if the file does not exist, +or is otherwise inaccessible. + +The optional +only_one +argument may be set to a non-zero +value to have +scons +thrown an exception and +generate an error +if the file contains dependency +information for more than one target. +This can provide a small sanity check +for files intended to be generated +by, for example, the +gcc -M +flag, +which should typically only +write dependency information for +one output file into a corresponding +.d +file. + +The +filename +and all of the files listed therein +will be interpreted relative to +the directory of the +&SConscript; +file which calls the +&f-ParseDepends; +function. + + + + + +(flags, ...) + + +Parses one or more strings containing +typical command-line flags for GCC tool chains +and returns a dictionary with the flag values +separated into the appropriate SCons construction variables. +This is intended as a companion to the +&f-link-env-MergeFlags; +method, but allows for the values in the returned dictionary +to be modified, if necessary, +before merging them into the construction environment. +(Note that +&f-env-MergeFlags; +will call this method if its argument is not a dictionary, +so it is usually not necessary to call +&f-link-env-ParseFlags; +directly unless you want to manipulate the values.) + +If the first character in any string is +an exclamation mark (!), +the rest of the string is executed as a command, +and the output from the command is +parsed as GCC tool chain command-line flags +and added to the resulting dictionary. + +Flag values are translated accordig to the prefix found, +and added to the following construction variables: + + +-arch CCFLAGS, LINKFLAGS +-D CPPDEFINES +-framework FRAMEWORKS +-frameworkdir= FRAMEWORKPATH +-include CCFLAGS +-isysroot CCFLAGS, LINKFLAGS +-I CPPPATH +-l LIBS +-L LIBPATH +-mno-cygwin CCFLAGS, LINKFLAGS +-mwindows LINKFLAGS +-pthread CCFLAGS, LINKFLAGS +-std= CFLAGS +-Wa, ASFLAGS, CCFLAGS +-Wl,-rpath= RPATH +-Wl,-R, RPATH +-Wl,-R RPATH +-Wl, LINKFLAGS +-Wp, CPPFLAGS +- CCFLAGS ++ CCFLAGS, LINKFLAGS + + +Any other strings not associated with options +are assumed to be the names of libraries +and added to the +&cv-LIBS; +construction variable. + +Examples (all of which produce the same result): + + +dict = env.ParseFlags('-O2 -Dfoo -Dbar=1') +dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1') +dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1']) +dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') + + + + + + +(string) + + +The +&f-Platform; +form returns a callable object +that can be used to initialize +a construction environment using the +platform keyword of the +&f-Environment; +function. + +Example: + + +env = Environment(platform = Platform('win32')) + + +The +&f-env-Platform; +form applies the callable object for the specified platform +string +to the environment through which the method was called. + + +env.Platform('posix') + + +Note that the +win32 +platform adds the +SystemDrive +and +SystemRoot +variables from the user's external environment +to the construction environment's +&cv-link-ENV; +dictionary. +This is so that any executed commands +that use sockets to connect with other systems +(such as fetching source files from +external CVS repository specifications like +:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) +will work on Windows systems. + + + + + +(key=val, [...]) + + +Appends the specified keyword arguments +to the beginning of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the values of the construction variable +and the keyword argument are the same type, +then the two values will be simply added together. +Otherwise, the construction variable +and the value of the keyword argument +are both coerced to lists, +and the lists are added together. +(See also the Append method, above.) + +Example: + + +env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) + + + + + + +(name, newpath, [envname, sep, delete_existing]) + + +This appends new path elements to the given path in the +specified external environment +(&cv-ENV; +by default). +This will only add +any particular path once (leaving the first one it encounters and +ignoring the rest, to preserve path order), +and to help assure this, +will normalize all paths (using +os.path.normpath +and +os.path.normcase). +This can also handle the +case where the given old path variable is a list instead of a +string, in which case a list will be returned instead of a string. + +If +delete_existing +is 0, then adding a path that already exists +will not move it to the beginning; +it will stay where it is in the list. + +Example: + + +print 'before:',env['ENV']['INCLUDE'] +include_path = '/foo/bar:/foo' +env.PrependENVPath('INCLUDE', include_path) +print 'after:',env['ENV']['INCLUDE'] + + +The above example will print: + + +before: /biz:/foo +after: /foo/bar:/foo:/biz + + + + + + +(key=val, delete_existing=0, [...]) + + +Appends the specified keyword arguments +to the beginning of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the construction variable being appended to is a list, +then any value(s) that already exist in the +construction variable will +not +be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the front of the list. + +Example: + + +env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) + + + + + + +(key=val, [...]) + + +Replaces construction variables in the Environment +with the specified keyword arguments. + +Example: + + +env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') + + + + + + +(directory) + + +Specifies that +directory +is a repository to be searched for files. +Multiple calls to +&f-Repository; +are legal, +and each one adds to the list of +repositories that will be searched. + +To +&scons;, +a repository is a copy of the source tree, +from the top-level directory on down, +which may contain +both source files and derived files +that can be used to build targets in +the local source tree. +The canonical example would be an +official source tree maintained by an integrator. +If the repository contains derived files, +then the derived files should have been built using +&scons;, +so that the repository contains the necessary +signature information to allow +&scons; +to figure out when it is appropriate to +use the repository copy of a derived file, +instead of building one locally. + +Note that if an up-to-date derived file +already exists in a repository, +&scons; +will +not +make a copy in the local directory tree. +In order to guarantee that a local copy +will be made, +use the +&f-link-Local; +method. + + + + + +(target, prerequisite) + + +Specifies an order-only relationship +between the specified target file(s) +and the specified prerequisite file(s). +The prerequisite file(s) +will be (re)built, if necessary, +before +the target file(s), +but the target file(s) do not actually +depend on the prerequisites +and will not be rebuilt simply because +the prerequisite file(s) change. + +Example: + + +env.Requires('foo', 'file-that-must-be-built-before-foo') + + + + + + +(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive]) + + +Creates a Scanner object for +the specified +function. +See the section "Scanner Objects," +below, for a complete explanation of the arguments and behavior. + + + + + +(value) + + +By default, +&scons; +changes its working directory +to the directory in which each +subsidiary SConscript file lives. +This behavior may be disabled +by specifying either: + + +SConscriptChdir(0) +env.SConscriptChdir(0) + + +in which case +&scons; +will stay in the top-level directory +while reading all SConscript files. +(This may be necessary when building from repositories, +when all the directories in which SConscript files may be found +don't necessarily exist locally.) +You may enable and disable +this ability by calling +SConscriptChdir() +multiple times. + +Example: + + +env = Environment() +SConscriptChdir(0) +SConscript('foo/SConscript') # will not chdir to foo +env.SConscriptChdir(1) +SConscript('bar/SConscript') # will chdir to bar + + + + + + +([file, dbm_module]) + + +This tells +&scons; +to store all file signatures +in the specified database +file. +If the +file +name is omitted, +.sconsign +is used by default. +(The actual file name(s) stored on disk +may have an appropriated suffix appended +by the + dbm_module.) +If +file +is not an absolute path name, +the file is placed in the same directory as the top-level +&SConstruct; +file. + +If +file +is +None, +then +&scons; +will store file signatures +in a separate +.sconsign +file in each directory, +not in one global database file. +(This was the default behavior +prior to SCons 0.96.91 and 0.97.) + +The optional +dbm_module +argument can be used to specify +which Python database module +The default is to use a custom +SCons.dblite +module that uses pickled +Python data structures, +and which works on all Python versions. + +Examples: + + +# Explicitly stores signatures in ".sconsign.dblite" +# in the top-level SConstruct directory (the +# default behavior). +SConsignFile() + +# Stores signatures in the file "etc/scons-signatures" +# relative to the top-level SConstruct directory. +SConsignFile("etc/scons-signatures") + +# Stores signatures in the specified absolute file name. +SConsignFile("/home/me/SCons/signatures") + +# Stores signatures in a separate .sconsign file +# in each directory. +SConsignFile(None) + + + + + + +(key=val, [...]) + + +Sets construction variables to default values specified with the keyword +arguments if (and only if) the variables are not already set. +The following statements are equivalent: + + +env.SetDefault(FOO = 'foo') + +if 'FOO' not in env: env['FOO'] = 'foo' + + + + + + +(side_effect, target) + + +Declares +side_effect +as a side effect of building +target. +Both +side_effect +and +target +can be a list, a file name, or a node. +A side effect is a target file that is created or updated +as a side effect of building other targets. +For example, a Windows PDB +file is created as a side effect of building the .obj +files for a static library, +and various log files are created updated +as side effects of various TeX commands. +If a target is a side effect of multiple build commands, +&scons; +will ensure that only one set of commands +is executed at a time. +Consequently, you only need to use this method +for side-effect targets that are built as a result of +multiple build commands. + +Because multiple build commands may update +the same side effect file, +by default the +side_effect +target is +not +automatically removed +when the +target +is removed by the + +option. +(Note, however, that the +side_effect +might be removed as part of +cleaning the directory in which it lives.) +If you want to make sure the +side_effect +is cleaned whenever a specific +target +is cleaned, +you must specify this explicitly +with the +&f-link-Clean; +or +&f-env-Clean; +function. + + + + + +(entries, builder) + + +This function and its associate factory functions are deprecated. +There is no replacement. +The intended use was to keep a local tree in sync with an archive, +but in actuality the function only causes the archive +to be fetched on the first run. +Synchronizing with the archive is best done external to &SCons;. + +Arrange for non-existent source files to +be fetched from a source code management system +using the specified +builder. +The specified +entries +may be a Node, string or list of both, +and may represent either individual +source files or directories in which +source files can be found. + +For any non-existent source files, +&scons; +will search up the directory tree +and use the first +&f-SourceCode; +builder it finds. +The specified +builder +may be +None, +in which case +&scons; +will not use a builder to fetch +source files for the specified +entries, +even if a +&f-SourceCode; +builder has been specified +for a directory higher up the tree. + +&scons; +will, by default, +fetch files from SCCS or RCS subdirectories +without explicit configuration. +This takes some extra processing time +to search for the necessary +source code management files on disk. +You can avoid these extra searches +and speed up your build a little +by disabling these searches as follows: + + +env.SourceCode('.', None) + + +Note that if the specified +builder +is one you create by hand, +it must have an associated +construction environment to use +when fetching a source file. + +&scons; +provides a set of canned factory +functions that return appropriate +Builders for various popular +source code management systems. +Canonical examples of invocation include: + + +env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) +env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) +env.SourceCode('/', env.RCS()) +env.SourceCode(['f1.c', 'f2.c'], env.SCCS()) +env.SourceCode('no_source.c', None) + + + + + + + +(type) + + +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +&f-link-Decider; +function for a more flexible and straightforward way +to configure SCons' decision-making. + +The +&f-SourceSignatures; +function tells +&scons; +how to decide if a source file +(a file that is not built from any other files) +has changed since the last time it +was used to build a particular target file. +Legal values are +MD5 +or +timestamp. + +If the environment method is used, +the specified type of source signature +is only used when deciding whether targets +built with that environment are up-to-date or must be rebuilt. +If the global function is used, +the specified type of source signature becomes the default +used for all decisions +about whether targets are up-to-date. + +MD5 +means +&scons; +decides that a source file has changed +if the MD5 checksum of its contents has changed since +the last time it was used to rebuild a particular target file. + +timestamp +means +&scons; +decides that a source file has changed +if its timestamp (modification time) has changed since +the last time it was used to rebuild a particular target file. +(Note that although this is similar to the behavior of Make, +by default it will also rebuild if the dependency is +older +than the last time it was used to rebuild the target file.) + +There is no different between the two behaviors +for Python +&f-Value; +node objects. + +MD5 +signatures take longer to compute, +but are more accurate than +timestamp +signatures. +The default value is +MD5. + +Note that the default +&f-link-TargetSignatures; +setting (see below) +is to use this +&f-SourceSignatures; +setting for any target files that are used +to build other target files. +Consequently, changing the value of +&f-SourceSignatures; +will, by default, +affect the up-to-date decision for all files in the build +(or all files built with a specific construction environment +when +&f-env-SourceSignatures; +is used). + + + + + +(arg) + + +Returns a list of file names or other objects. +If arg is a string, +it will be split on strings of white-space characters +within the string, +making it easier to write long lists of file names. +If arg is already a list, +the list will be returned untouched. +If arg is any other type of object, +it will be returned as a list +containing just the object. + +Example: + + +files = Split("f1.c f2.c f3.c") +files = env.Split("f4.c f5.c f6.c") +files = Split(""" + f7.c + f8.c + f9.c +""") + + + + + + +(input, [raw, target, source, conv]) + + +Performs construction variable interpolation +on the specified string or sequence argument +input. + +By default, +leading or trailing white space will +be removed from the result. +and all sequences of white space +will be compressed to a single space character. +Additionally, any +$( +and +$) +character sequences will be stripped from the returned string, +The optional +raw +argument may be set to +1 +if you want to preserve white space and +$(-$) +sequences. +The +raw +argument may be set to +2 +if you want to strip +all characters between +any +$( +and +$) +pairs +(as is done for signature calculation). + +If the input is a sequence +(list or tuple), +the individual elements of +the sequence will be expanded, +and the results will be returned as a list. + +The optional +target +and +source +keyword arguments +must be set to lists of +target and source nodes, respectively, +if you want the +&cv-TARGET;, +&cv-TARGETS;, +&cv-SOURCE; +and +&cv-SOURCES; +to be available for expansion. +This is usually necessary if you are +calling +&f-env-subst; +from within a Python function used +as an SCons action. + +Returned string values or sequence elements +are converted to their string representation by default. +The optional +conv +argument +may specify a conversion function +that will be used in place of +the default. +For example, if you want Python objects +(including SCons Nodes) +to be returned as Python objects, +you can use the Python +λ +idiom to pass in an unnamed function +that simply returns its unconverted argument. + +Example: + + +print env.subst("The C compiler is: $CC") + +def compile(target, source, env): + sourceDir = env.subst("${SOURCE.srcdir}", + target=target, + source=source) + +source_nodes = env.subst('$EXPAND_TO_NODELIST', + conv=lambda x: x) + + + + + + +(type) + + +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +&f-link-Decider; +function for a more flexible and straightforward way +to configure SCons' decision-making. + +The +&f-TargetSignatures; +function tells +&scons; +how to decide if a target file +(a file that +is +built from any other files) +has changed since the last time it +was used to build some other target file. +Legal values are +"build"; +"content" +(or its synonym +"MD5"); +"timestamp"; +or +"source". + +If the environment method is used, +the specified type of target signature is only used +for targets built with that environment. +If the global function is used, +the specified type of signature becomes the default +used for all target files that +don't have an explicit target signature type +specified for their environments. + +"content" +(or its synonym +"MD5") +means +&scons; +decides that a target file has changed +if the MD5 checksum of its contents has changed since +the last time it was used to rebuild some other target file. +This means +&scons; +will open up +MD5 sum the contents +of target files after they're built, +and may decide that it does not need to rebuild +"downstream" target files if a file was +rebuilt with exactly the same contents as the last time. + +"timestamp" +means +&scons; +decides that a target file has changed +if its timestamp (modification time) has changed since +the last time it was used to rebuild some other target file. +(Note that although this is similar to the behavior of Make, +by default it will also rebuild if the dependency is +older +than the last time it was used to rebuild the target file.) + +"source" +means +&scons; +decides that a target file has changed +as specified by the corresponding +&f-SourceSignatures; +setting +("MD5" +or +"timestamp"). +This means that +&scons; +will treat all input files to a target the same way, +regardless of whether they are source files +or have been built from other files. + +"build" +means +&scons; +decides that a target file has changed +if it has been rebuilt in this invocation +or if its content or timestamp have changed +as specified by the corresponding +&f-SourceSignatures; +setting. +This "propagates" the status of a rebuilt file +so that other "downstream" target files +will always be rebuilt, +even if the contents or the timestamp +have not changed. + +"build" +signatures are fastest because +"content" +(or +"MD5") +signatures take longer to compute, +but are more accurate than +"timestamp" +signatures, +and can prevent unnecessary "downstream" rebuilds +when a target file is rebuilt to the exact same contents +as the previous build. +The +"source" +setting provides the most consistent behavior +when other target files may be rebuilt from +both source and target input files. +The default value is +"source". + +Because the default setting is +"source", +using +&f-SourceSignatures; +is generally preferable to +&f-TargetSignatures;, +so that the up-to-date decision +will be consistent for all files +(or all files built with a specific construction environment). +Use of +&f-TargetSignatures; +provides specific control for how built target files +affect their "downstream" dependencies. + + + + + +(string, [toolpath, **kw]) + + +The +&f-Tool; +form of the function +returns a callable object +that can be used to initialize +a construction environment using the +tools keyword of the Environment() method. +The object may be called with a construction +environment as an argument, +in which case the object will +add the necessary variables +to the construction environment +and the name of the tool will be added to the +&cv-link-TOOLS; +construction variable. + +Additional keyword arguments are passed to the tool's +generate() +method. + +Examples: + + +env = Environment(tools = [ Tool('msvc') ]) + +env = Environment() +t = Tool('msvc') +t(env) # adds 'msvc' to the TOOLS variable +u = Tool('opengl', toolpath = ['tools']) +u(env) # adds 'opengl' to the TOOLS variable + + +The +&f-env-Tool; +form of the function +applies the callable object for the specified tool +string +to the environment through which the method was called. + +Additional keyword arguments are passed to the tool's +generate() +method. + + +env.Tool('gcc') +env.Tool('opengl', toolpath = ['build/tools']) + + + + + + +(value, [built_value]) + + +Returns a Node object representing the specified Python value. Value +Nodes can be used as dependencies of targets. If the result of +calling +str(value) +changes between SCons runs, any targets depending on +Value(value) +will be rebuilt. +(This is true even when using timestamps to decide if +files are up-to-date.) +When using timestamp source signatures, Value Nodes' +timestamps are equal to the system time when the Node is created. + +The returned Value Node object has a +write() +method that can be used to "build" a Value Node +by setting a new value. +The optional +built_value +argument can be specified +when the Value Node is created +to indicate the Node should already be considered +"built." +There is a corresponding +read() +method that will return the built value of the Node. + +Examples: + + +env = Environment() + +def create(target, source, env): + # A function that will write a 'prefix=$SOURCE' + # string into the file name specified as the + # $TARGET. + f = open(str(target[0]), 'wb') + f.write('prefix=' + source[0].get_contents()) + +# Fetch the prefix= argument, if any, from the command +# line, and use /usr/local as the default. +prefix = ARGUMENTS.get('prefix', '/usr/local') + +# Attach a .Config() builder for the above function action +# to the construction environment. +env['BUILDERS']['Config'] = Builder(action = create) +env.Config(target = 'package-config', source = Value(prefix)) + +def build_value(target, source, env): + # A function that "builds" a Python Value by updating + # the the Python value with the contents of the file + # specified as the source of the Builder call ($SOURCE). + target[0].write(source[0].get_contents()) + +output = env.Value('before') +input = env.Value('after') + +# Attach a .UpdateValue() builder for the above function +# action to the construction environment. +env['BUILDERS']['UpdateValue'] = Builder(action = build_value) +env.UpdateValue(target = Value(output), source = Value(input)) + + + + + + +(variant_dir, src_dir, [duplicate]) + + +Use the +&f-VariantDir; +function to create a copy of your sources in another location: +if a name under +variant_dir +is not found but exists under +src_dir, +the file or directory is copied to +variant_dir. +Target files can be built in a different directory +than the original sources by simply refering to the sources (and targets) +within the variant tree. + +&f-VariantDir; +can be called multiple times with the same +src_dir +to set up multiple builds with different options +(variants). +The +src_dir +location must be in or underneath the SConstruct file's directory, and +variant_dir +may not be underneath +src_dir. + + +The default behavior is for +&scons; +to physically duplicate the source files in 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 +intermediate source files are generated during the build, +or preprocessors or other scanners search for included files +relative to the source file, +or individual compilers or other invoked tools are hard-coded +to put derived files in the same directory as source files. + +If possible on the platform, +the duplication is performed by linking rather than copying; +see also the + +command-line option. +Moreover, only the files needed for the build are duplicated; +files and directories that are not used are not present in +variant_dir. + +Duplicating the source tree may be disabled by setting the +duplicate +argument to +0 +(zero). +This will cause +&scons; +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 always more efficient than +duplicate=1, +and is usually safe for most builds +(but see above for cases that may cause problems). + +Note that +&f-VariantDir; +works most naturally with a subsidiary SConscript file. +However, you would then call the subsidiary SConscript file +not in the source directory, but in the +variant_dir, +regardless of the value of +duplicate. +This is how you tell +&scons; +which variant of a source tree to build: + + +# run src/SConscript in two variant directories +VariantDir('build/variant1', 'src') +SConscript('build/variant1/SConscript') +VariantDir('build/variant2', 'src') +SConscript('build/variant2/SConscript') + + +See also the +&f-link-SConscript; +function, described above, +for another way to specify a variant directory +in conjunction with calling a subsidiary SConscript file. + +Examples: + + +# use names in the build directory, not the source directory +VariantDir('build', 'src', duplicate=0) +Program('build/prog', 'build/source.c') + + + +# this builds both the source and docs in a separate subtree +VariantDir('build', '.', duplicate=0) +SConscript(dirs=['build/src','build/doc']) + + + +# same as previous example, but only uses SConscript +SConscript(dirs='src', variant_dir='build/src', duplicate=0) +SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) + + + + + + +(program, [path, pathext, reject]) + + +Searches for the specified executable +program, +returning the full path name to the program +if it is found, +and returning None if not. +Searches the specified +path, +the value of the calling environment's PATH +(env['ENV']['PATH']), +or the user's current external PATH +(os.environ['PATH']) +by default. +On Windows systems, searches for executable +programs with any of the file extensions +listed in the specified +pathext, +the calling environment's PATHEXT +(env['ENV']['PATHEXT']) +or the user's current PATHEXT +(os.environ['PATHEXT']) +by default. +Will not select any +path name or names +in the specified +reject +list, if any. + + -- cgit v1.2.3