From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- doc/generated/functions.gen | 5120 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 5120 insertions(+) create mode 100644 doc/generated/functions.gen (limited to 'doc/generated/functions.gen') diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen new file mode 100644 index 0000000..072b91c --- /dev/null +++ b/doc/generated/functions.gen @@ -0,0 +1,5120 @@ + + + %scons; + + %builders-mod; + + %functions-mod; + + %tools-mod; + + %variables-mod; +]> + + + + + Action(action, [cmd/str/fun, [var, ...]] [option=value, ...]) + + + env.Action(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. + + + + + + AddMethod(object, function, [name]) + + + env.AddMethod(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') + + + + + + AddOption(arguments) + + + +This function adds a new command-line option to be recognized. +The specified +arguments +are the same as supported by the standard Python +optparse.add_option() +method (with a few additional capabilities noted below); +see the documentation for +optparse +for a thorough discussion of its option-processing capabities. + + + +In addition to the arguments and values supported by the +optparse.add_option() +method, +the SCons +AddOption +function allows you to set the +nargs +keyword value to +'?' +(a string with just the question mark) +to indicate that the specified long option(s) take(s) an +optional +argument. +When +nargs = '?' +is passed to the +AddOption +function, the +const +keyword argument +may be used to supply the "default" +value that should be used when the +option is specified on the command line +without an explicit argument. + + + +If no +default= +keyword argument is supplied when calling +AddOption, +the option will have a default value of +None. + + + +Once a new command-line option has been added with +AddOption, +the option value may be accessed using +GetOption +or +env.GetOption(). +The value may also be set, using +SetOption +or +env.SetOption(), +if conditions in a +SConscript +require overriding any default value. +Note, however, that a +value specified on the command line will +always +override a value set by any SConscript file. + + + +Any specified +help= +strings for the new option(s) +will be displayed by the + +or + +options +(the latter only if no other help text is +specified in the SConscript files). +The help text for the local options specified by +AddOption +will appear below the SCons options themselves, +under a separate +Local Options +heading. +The options will appear in the help text +in the order in which the +AddOption +calls occur. + + + +Example: + + + +AddOption('--prefix', + dest='prefix', + nargs=1, type='string', + action='store', + metavar='DIR', + help='installation prefix') +env = Environment(PREFIX = GetOption('prefix')) + + + + + + AddPostAction(target, action) + + + env.AddPostAction(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. + + + + + + AddPreAction(target, action) + + + env.AddPreAction(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(alias, [targets, [action]]) + + + env.Alias(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. +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") + + + + + + AllowSubstExceptions([exception, ...]) + + + +Specifies the exceptions that will be allowed +when expanding construction variables. +By default, +any construction variable expansions that generate a +NameError +or +IndexError +exception will expand to a +'' +(a null string) and not cause scons to fail. +All exceptions not in the specified list +will generate an error message +and terminate processing. + + + +If +AllowSubstExceptions +is called multiple times, +each call completely overwrites the previous list +of allowed exceptions. + + + +Example: + + + +# Requires that all construction variable names exist. +# (You may wish to do this if you want to enforce strictly +# that all construction variables must be defined before use.) +AllowSubstExceptions() + +# Also allow a string containing a zero-division expansion +# like '${1 / 0}' to evalute to ''. +AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) + + + + + + AlwaysBuild(target, ...) + + + env.AlwaysBuild(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 +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 +AlwaysBuild. + + + + + + env.Append(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']) + + + + + + env.AppendENVPath(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 + + + + + + env.AppendUnique(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']) + + + + + + env.BitKeeper() + + + +A factory function that +returns a Builder object +to be used to fetch source files +using BitKeeper. +The returned Builder +is intended to be passed to the +SourceCode +function. + + + +This function is deprecated. For details, see the entry for the +SourceCode +function. + + + +Example: + + + +env.SourceCode('.', env.BitKeeper()) + + + + + + BuildDir(build_dir, src_dir, [duplicate]) + + + env.BuildDir(build_dir, src_dir, [duplicate]) + + + +Deprecated synonyms for +VariantDir +and +env.VariantDir(). +The +build_dir +argument becomes the +variant_dir +argument of +VariantDir +or +env.VariantDir(). + + + + + + Builder(action, [arguments]) + + + env.Builder(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 +Builder +form delays all variable expansion +until after the Builder object is actually called. + + + + + + CacheDir(cache_dir) + + + env.CacheDir(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 +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 +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 +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 +CacheDir +is added to a build, +or after using the + +option. + + + +When using +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 +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. + + + + + + Clean(targets, files_or_dirs) + + + env.Clean(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 +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 +Clean +method, or as a list. +Clean +will also accept the return value of any of the construction environment +Builder methods. +Examples: + + + +The related +NoClean +function overrides calling +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)) + + + + + + env.Clone([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') + + + + + + Command(target, source, action, [key=val, ...]) + + + env.Command(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 +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 +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.) + + + + + + Configure(env, [custom_tests, conf_dir, log_file, config_h]) + + + env.Configure([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. + + + + + + env.Copy([key=val, ...]) + + + +A now-deprecated synonym for +env.Clone(). + + + + + + env.CVS(repository, module) + + + +A factory function that +returns a Builder object +to be used to fetch source files +from the specified +CVS +repository. +The returned Builder +is intended to be passed to the +SourceCode +function. + + + +This function is deprecated. For details, see the entry for the +SourceCode +function. + + + +The optional specified +module +will be added to the beginning +of all repository path names; +this can be used, in essence, +to strip initial directory names +from the repository path names, +so that you only have to +replicate part of the repository +directory hierarchy in your +local build directory. + + + +Examples: + + + +# Will fetch foo/bar/src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT')) + +# Will fetch bar/src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) + +# Will fetch src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) + + + + + + Decider(function) + + + env.Decider(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) + + + + + + Default(targets) + + + env.Default(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 +Default +are legal, +and add to the list of default targets. + + + +Multiple targets should be specified as +separate arguments to the +Default +method, or as a list. +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 +Default +of +None +will clear all default targets. +Later calls to +Default +will add to the (now empty) default-target list +like normal. + + + +The current list of targets added using the +Default +function or method is available in the +DEFAULT_TARGETS +list; +see below. + + + + + + DefaultEnvironment([args]) + + + +Creates and returns a default construction environment object. +This construction environment is used internally by SCons +in order to execute many of the global functions in this list, +and to fetch source files transparently +from source code management systems. + + + + + + Depends(target, dependency) + + + env.Depends(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) + + + + + + env.Dictionary([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') + + + + + + Dir(name, [directory]) + + + env.Dir(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. + + + + + + env.Dump([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': [], + ... + + + + + + EnsurePythonVersion(major, minor) + + + env.EnsurePythonVersion(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) + + + + + + EnsureSConsVersion(major, minor, [revision]) + + + env.EnsureSConsVersion(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) + + + + + + Environment([key=value, ...]) + + + env.Environment([key=value, ...]) + + + +Return a new construction environment +initialized with the specified +key=value +pairs. + + + + + + Execute(action, [strfunction, varlist]) + + + env.Execute(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 +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) + + + + + + Exit([value]) + + + env.Exit([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. + + + + + + Export(vars) + + + env.Export(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 +Export +will over-write previous exports that have the same name. +Multiple variable names can be passed to +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 +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 +SConscript +function, below. + + + + + + File(name, [directory]) + + + env.File(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. + + + + + + FindFile(file, dirs) + + + env.FindFile(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']) + + + + + + FindInstalledFiles() + + + env.FindInstalledFiles() + + + +Returns the list of targets set up by the +Install +or +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() + + + + + + FindPathDirs(variable) + + + +Returns a function +(actually a callable Python object) +intended to be used as the +path_function +of a Scanner object. +The returned object will look up the specified +variable +in a construction environment +and treat the construction variable's value as a list of +directory paths that should be searched +(like +$CPPPATH, +$LIBPATH, +etc.). + + + +Note that use of +FindPathDirs +is generally preferable to +writing your own +path_function +for the following reasons: +1) The returned list will contain all appropriate directories +found in source trees +(when +VariantDir +is used) +or in code repositories +(when +Repository +or the + +option are used). +2) scons will identify expansions of +variable +that evaluate to the same list of directories as, +in fact, the same list, +and avoid re-scanning the directories for files, +when possible. + + + +Example: + + + +def my_scan(node, env, path, arg): + # Code to scan file contents goes here... + return include_files + +scanner = Scanner(name = 'myscanner', + function = my_scan, + path_function = FindPathDirs('MYPATH')) + + + + + + FindSourceFiles(node='"."') + + + env.FindSourceFiles(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. + + + + + + Flatten(sequence) + + + env.Flatten(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) + + + + + + GetBuildFailures() + + + +Returns a list of exceptions for the +actions that failed while +attempting to build targets. +Each element in the returned list is a +BuildError +object +with the following attributes +that record various aspects +of the build failure: + + + +.node +The node that was being built +when the build failure occurred. + + + +.status +The numeric exit status +returned by the command or Python function +that failed when trying to build the +specified Node. + + + +.errstr +The SCons error string +describing the build failure. +(This is often a generic +message like "Error 2" +to indicate that an executed +command exited with a status of 2.) + + + +.filename +The name of the file or +directory that actually caused the failure. +This may be different from the +.node +attribute. +For example, +if an attempt to build a target named +sub/dir/target +fails because the +sub/dir +directory could not be created, +then the +.node +attribute will be +sub/dir/target +but the +.filename +attribute will be +sub/dir. + + + +.executor +The SCons Executor object +for the target Node +being built. +This can be used to retrieve +the construction environment used +for the failed action. + + + +.action +The actual SCons Action object that failed. +This will be one specific action +out of the possible list of +actions that would have been +executed to build the target. + + + +.command +The actual expanded command that was executed and failed, +after expansion of +$TARGET, +$SOURCE, +and other construction variables. + + + +Note that the +GetBuildFailures +function +will always return an empty list +until any build failure has occurred, +which means that +GetBuildFailures +will always return an empty list +while the +SConscript +files are being read. +Its primary intended use is +for functions that will be +executed before SCons exits +by passing them to the +standard Python +atexit.register() +function. +Example: + + + +import atexit + +def print_build_failures(): + from SCons.Script import GetBuildFailures + for bf in GetBuildFailures(): + print "%s failed: %s" % (bf.node, bf.errstr) + +atexit.register(print_build_failures) + + + + + + GetBuildPath(file, [...]) + + + env.GetBuildPath(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. + + + + + + GetLaunchDir() + + + env.GetLaunchDir() + + + +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. + + + + + + GetOption(name) + + + env.GetOption(name) + + + +This function provides a way to query the value of +SCons options set on scons command line +(or set using the +SetOption +function). +The options supported are: + + + + + +cache_debug + + +which corresponds to --cache-debug; + + + + +cache_disable + + +which corresponds to --cache-disable; + + + + +cache_force + + +which corresponds to --cache-force; + + + + +cache_show + + +which corresponds to --cache-show; + + + + +clean + + +which corresponds to -c, --clean and --remove; + + + + +config + + +which corresponds to --config; + + + + +directory + + +which corresponds to -C and --directory; + + + + +diskcheck + + +which corresponds to --diskcheck + + + + +duplicate + + +which corresponds to --duplicate; + + + + +file + + +which corresponds to -f, --file, --makefile and --sconstruct; + + + + +help + + +which corresponds to -h and --help; + + + + +ignore_errors + + +which corresponds to --ignore-errors; + + + + +implicit_cache + + +which corresponds to --implicit-cache; + + + + +implicit_deps_changed + + +which corresponds to --implicit-deps-changed; + + + + +implicit_deps_unchanged + + +which corresponds to --implicit-deps-unchanged; + + + + +interactive + + +which corresponds to --interact and --interactive; + + + + +keep_going + + +which corresponds to -k and --keep-going; + + + + +max_drift + + +which corresponds to --max-drift; + + + + +no_exec + + +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; + + + + +no_site_dir + + +which corresponds to --no-site-dir; + + + + +num_jobs + + +which corresponds to -j and --jobs; + + + + +profile_file + + +which corresponds to --profile; + + + + +question + + +which corresponds to -q and --question; + + + + +random + + +which corresponds to --random; + + + + +repository + + +which corresponds to -Y, --repository and --srcdir; + + + + +silent + + +which corresponds to -s, --silent and --quiet; + + + + +site_dir + + +which corresponds to --site-dir; + + + + +stack_size + + +which corresponds to --stack-size; + + + + +taskmastertrace_file + + +which corresponds to --taskmastertrace; and + + + + +warn + + +which corresponds to --warn and --warning. + + + + + + + +See the documentation for the +corresponding command line object for information about each specific +option. + + + + + + Glob(pattern, [ondisk, source, strings]) + + + env.Glob(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 +Glob +knows about +repositories +(see the +Repository +function) +and source directories +(see the +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 +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 +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('*')) + + + + + + Help(text) + + + env.Help(text) + + + +This specifies help text to be printed if the + +argument is given to +scons. +If +Help +is called multiple times, the text is appended together in the order +that +Help +is called. + + + + + + Ignore(target, dependency) + + + env.Ignore(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 +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') + + + + + + Import(vars) + + + env.Import(vars) + + + +This tells +scons +to import a list of variables into the current SConscript file. This +will import variables that were exported with +Export +or in the +exports +argument to +SConscript. +Variables exported by +SConscript +have precedence. +Multiple variable names can be passed to +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("*") + + + + + + Literal(string) + + + env.Literal(string) + + + +The specified +string +will be preserved as-is +and not have construction variables expanded. + + + + + + Local(targets) + + + env.Local(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. + + + + + + env.MergeFlags(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 +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 +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']) + + + + + + NoCache(target, ...) + + + env.NoCache(target, ...) + + + +Specifies a list of files which should +not +be cached whenever the +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 +NoCache +method, or as a list. +NoCache +will also accept the return value of any of the construction environment +Builder methods. + + + +Calling +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')) + + + + + + NoClean(target, ...) + + + env.NoClean(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 +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 +NoClean +method, or as a list. +NoClean +will also accept the return value of any of the construction environment +Builder methods. + + + +Calling +NoClean +for a target overrides calling +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')) + + + + + + env.ParseConfig(command, [function, unique]) + + + +Calls the specified +function +to modify the environment as specified by the output of +command. +The default +function +is +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 +env.ParseFlags +method (which this method calls). +See that method's description, below, +for a table of options and construction variables. + + + + + + ParseDepends(filename, [must_exist, only_one]) + + + env.ParseDepends(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 +ParseDepends +function. + + + + + + env.ParseFlags(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 +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 +env.MergeFlags +will call this method if its argument is not a dictionary, +so it is usually not necessary to call +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 +$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') + + + + + + env.Perforce() + + + +A factory function that +returns a Builder object +to be used to fetch source files +from the Perforce source code management system. +The returned Builder +is intended to be passed to the +SourceCode +function. + + + +This function is deprecated. For details, see the entry for the +SourceCode +function. + + + +Example: + + + +env.SourceCode('.', env.Perforce()) + + + +Perforce uses a number of external +environment variables for its operation. +Consequently, this function adds the +following variables from the user's external environment +to the construction environment's +ENV dictionary: +P4CHARSET, +P4CLIENT, +P4LANGUAGE, +P4PASSWD, +P4PORT, +P4USER, +SystemRoot, +USER, +and +USERNAME. + + + + + + Platform(string) + + + +The +Platform +form returns a callable object +that can be used to initialize +a construction environment using the +platform keyword of the +Environment +function. + + + +Example: + + + +env = Environment(platform = Platform('win32')) + + + +The +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 +$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. + + + + + + Precious(target, ...) + + + env.Precious(target, ...) + + + +Marks each given +target +as precious so it is not deleted before it is rebuilt. Normally +scons +deletes a target before building it. +Multiple targets can be passed in to a single call to +Precious. + + + + + + env.Prepend(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']) + + + + + + env.PrependENVPath(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 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 + + + + + + env.PrependUnique(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']) + + + + + + Progress(callable, [interval]) + + + Progress(string, [interval, file, overwrite]) + + + Progress(list_of_strings, [interval, file, overwrite]) + + + +Allows SCons to show progress made during the build +by displaying a string or calling a function while +evaluating Nodes (e.g. files). + + + +If the first specified argument is a Python callable +(a function or an object that has a +__call__() +method), +the function will be called +once every +interval +times a Node is evaluated. +The callable will be passed the evaluated Node +as its only argument. +(For future compatibility, +it's a good idea to also add +*args +and +**kw +as arguments to your function or method. +This will prevent the code from breaking +if SCons ever changes the interface +to call the function with additional arguments in the future.) + + + +An example of a simple custom progress function +that prints a string containing the Node name +every 10 Nodes: + + + +def my_progress_function(node, *args, **kw): + print 'Evaluating node %s!' % node +Progress(my_progress_function, interval=10) + + + +A more complicated example of a custom progress display object +that prints a string containing a count +every 100 evaluated Nodes. +Note the use of +\r +(a carriage return) +at the end so that the string +will overwrite itself on a display: + + + +import sys +class ProgressCounter(object): + count = 0 + def __call__(self, node, *args, **kw): + self.count += 100 + sys.stderr.write('Evaluated %s nodes\r' % self.count) +Progress(ProgressCounter(), interval=100) + + + +If the first argument +Progress +is a string, +the string will be displayed +every +interval +evaluated Nodes. +The default is to print the string on standard output; +an alternate output stream +may be specified with the +file= +argument. +The following will print a series of dots +on the error output, +one dot for every 100 evaluated Nodes: + + + +import sys +Progress('.', interval=100, file=sys.stderr) + + + +If the string contains the verbatim substring +$TARGET, +it will be replaced with the Node. +Note that, for performance reasons, this is +not +a regular SCons variable substition, +so you can not use other variables +or use curly braces. +The following example will print the name of +every evaluated Node, +using a +\r +(carriage return) to cause each line to overwritten by the next line, +and the +overwrite= +keyword argument to make sure the previously-printed +file name is overwritten with blank spaces: + + + +import sys +Progress('$TARGET\r', overwrite=True) + + + +If the first argument to +Progress +is a list of strings, +then each string in the list will be displayed +in rotating fashion every +interval +evaluated Nodes. +This can be used to implement a "spinner" +on the user's screen as follows: + + + +Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) + + + + + + Pseudo(target, ...) + + + env.Pseudo(target, ...) + + + +This indicates that each given +target +should not be created by the build rule, and if the target is created, +an error will be generated. This is similar to the gnu make .PHONY +target. However, in the vast majority of cases, an +Alias +is more appropriate. + +Multiple targets can be passed in to a single call to +Pseudo. + + + + + + env.RCS() + + + +A factory function that +returns a Builder object +to be used to fetch source files +from RCS. +The returned Builder +is intended to be passed to the +SourceCode +function: + + + +This function is deprecated. For details, see the entry for the +SourceCode +function. + + + +Examples: + + + +env.SourceCode('.', env.RCS()) + + + +Note that +scons +will fetch source files +from RCS subdirectories automatically, +so configuring RCS +as demonstrated in the above example +should only be necessary if +you are fetching from +RCS,v +files in the same +directory as the source files, +or if you need to explicitly specify RCS +for a specific subdirectory. + + + + + + env.Replace(key=val, [...]) + + + +Replaces construction variables in the Environment +with the specified keyword arguments. + + + +Example: + + + +env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') + + + + + + Repository(directory) + + + env.Repository(directory) + + + +Specifies that +directory +is a repository to be searched for files. +Multiple calls to +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 +Local +method. + + + + + + Requires(target, prerequisite) + + + env.Requires(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') + + + + + + Return([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 +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 +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 +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') + + + + + + Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive]) + + + env.Scanner(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. + + + + + + env.SCCS() + + + +A factory function that +returns a Builder object +to be used to fetch source files +from SCCS. +The returned Builder +is intended to be passed to the +SourceCode +function. + + + +Example: + + + +env.SourceCode('.', env.SCCS()) + + + +Note that +scons +will fetch source files +from SCCS subdirectories automatically, +so configuring SCCS +as demonstrated in the above example +should only be necessary if +you are fetching from +s.SCCS +files in the same +directory as the source files, +or if you need to explicitly specify SCCS +for a specific subdirectory. + + + + + + SConscript(scripts, [exports, variant_dir, duplicate]) + + + env.SConscript(scripts, [exports, variant_dir, duplicate]) + + + SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate]) + + + env.SConscript(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 +Return +will be returned by the call to +SConscript. +There are two ways to call the +SConscript +function. + + + +The first way you can call +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 +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 +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 +Export +function. + +The subsidiary +script(s) +must use the +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 +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 +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) + + + + + + SConscriptChdir(value) + + + env.SConscriptChdir(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 + + + + + + SConsignFile([file, dbm_module]) + + + env.SConsignFile([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) + + + + + + env.SetDefault(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' + + + + + + SetOption(name, value) + + + env.SetOption(name, value) + + + +This function provides a way to set a select subset of the scons command +line options from a SConscript file. The options supported are: + + + + + +clean + + +which corresponds to -c, --clean and --remove; + + + + +duplicate + + +which corresponds to --duplicate; + + + + +help + + +which corresponds to -h and --help; + + + + +implicit_cache + + +which corresponds to --implicit-cache; + + + + +max_drift + + +which corresponds to --max-drift; + + + + +no_exec + + +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; + + + + +num_jobs + + +which corresponds to -j and --jobs; + + + + +random + + +which corresponds to --random; and + + + + +stack_size + + +which corresponds to --stack-size. + + + + + + + +See the documentation for the +corresponding command line object for information about each specific +option. + + + +Example: + + + +SetOption('max_drift', 1) + + + + + + SideEffect(side_effect, target) + + + env.SideEffect(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 +Clean +or +env.Clean +function. + + + + + + SourceCode(entries, builder) + + + env.SourceCode(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 +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 +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) + + + + + + + + + SourceSignatures(type) + + + env.SourceSignatures(type) + + + +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +Decider +function for a more flexible and straightforward way +to configure SCons' decision-making. + + + +The +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 +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 +TargetSignatures +setting (see below) +is to use this +SourceSignatures +setting for any target files that are used +to build other target files. +Consequently, changing the value of +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 +env.SourceSignatures +is used). + + + + + + Split(arg) + + + env.Split(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 +""") + + + + + + env.subst(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 +$TARGET, +$TARGETS, +$SOURCE +and +$SOURCES +to be available for expansion. +This is usually necessary if you are +calling +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) + + + + + + Tag(node, tags) + + + +Annotates file or directory Nodes with +information about how the +Package +Builder should package those files or directories. +All tags are optional. + + + +Examples: + + + +# makes sure the built library will be installed with 0644 file +# access mode +Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) + +# marks file2.txt to be a documentation file +Tag( 'file2.txt', DOC ) + + + + + + TargetSignatures(type) + + + env.TargetSignatures(type) + + + +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +Decider +function for a more flexible and straightforward way +to configure SCons' decision-making. + + + +The +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 +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 +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 +SourceSignatures +is generally preferable to +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 +TargetSignatures +provides specific control for how built target files +affect their "downstream" dependencies. + + + + + + Tool(string, [toolpath, **kw]) + + + env.Tool(string, [toolpath, **kw]) + + + +The +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 +$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 +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(value, [built_value]) + + + env.Value(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)) + + + + + + VariantDir(variant_dir, src_dir, [duplicate]) + + + env.VariantDir(variant_dir, src_dir, [duplicate]) + + + +Use the +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. + + + +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 +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 +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) + + + + + + WhereIs(program, [path, pathext, reject]) + + + env.WhereIs(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