diff options
Diffstat (limited to 'doc/man/scons.1')
| -rw-r--r-- | doc/man/scons.1 | 4200 |
1 files changed, 132 insertions, 4068 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 5d2b795..bd0d965 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the @@ -19,9 +19,9 @@ .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .\" -.\" doc/man/scons.1 5134 2010/08/16 23:02:40 bdeegan +.\" doc/man/scons.1 5357 2011/09/09 21:31:03 bdeegan .\" -.TH SCONS 1 "August 2010" +.TH SCONS 1 "September 2011" .\" ES - Example Start - indents and turns off line fill .rm ES .de ES @@ -100,17 +100,17 @@ file, .B scons looks for a directory named .I site_scons -in the directory containing the +in various system directories (see below) and the directory containing the .I SConstruct -file; if it exists, +file; for each of those dirs which exists, .I site_scons -is added to sys.path, +is prepended to sys.path, the file .IR site_scons/site_init.py , is evaluated if it exists, and the directory .I site_scons/site_tools -is added to the default toolpath if it exist. +is prepended to the default toolpath if it exists. See the .I --no-site-dir and @@ -601,6 +601,12 @@ have been compiled with optimization files). .TP +--debug=duplicate +Print a line for each unlink/relink (or copy) of a variant file from +its source file. Includes debugging info for unlinking stale variant +files, as well as unlinking old targets before building them. + +.TP --debug=dtree A synonym for the newer .B --tree=derived @@ -664,6 +670,18 @@ Re-run SCons under the control of the Python debugger. .TP +--debug=prepare +Print a line each time any target (internal or external) +is prepared for building. +.B scons +prints this for each target it considers, even if that +target is up to date (see also --debug=explain). +This can help debug problems with targets that aren't being +built; it shows whether +.B scons +is at least considering them or not. + +.TP --debug=presub Print the raw command line used to build each target before the construction environment variables are substituted. @@ -1095,13 +1113,13 @@ any out-of-date target files, but do not execute the commands. .RI --no-site-dir Prevents the automatic addition of the standard .I site_scons -dir to +dirs to .IR sys.path . Also prevents loading the .I site_scons/site_init.py -module if it exists, and prevents adding +modules if they exist, and prevents adding their .I site_scons/site_tools -to the toolpath. +dirs to the toolpath. .\" .TP .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file @@ -1182,7 +1200,7 @@ Ignored for compatibility with GNU .RI --site-dir= dir Uses the named dir as the site dir rather than the default .I site_scons -dir. This dir will get prepended to +dirs. This dir will get prepended to .IR sys.path , the module .IR dir /site_init.py @@ -1190,6 +1208,48 @@ will get loaded if it exists, and .IR dir /site_tools will get added to the default toolpath. +The default set of +.I site_scons +dirs used when +.I --site-dir +is not specified depends on the system platform, as follows. Note +that the directories are examined in the order given, from most +generic to most specific, so the last-executed site_init.py file is +the most specific one (which gives it the chance to override +everything else), and the dirs are prepended to the paths, again so +the last dir examined comes first in the resulting path. + +.IP "Windows:" +.nf + %ALLUSERSPROFILE/Application Data/scons/site_scons + %USERPROFILE%/Local Settings/Application Data/scons/site_scons + %APPDATA%/scons/site_scons + %HOME%/.scons/site_scons + ./site_scons +.fi +.IP "Mac OS X:" +.nf + /Library/Application Support/SCons/site_scons + /opt/local/share/scons/site_scons (for MacPorts) + /sw/share/scons/site_scons (for Fink) + $HOME/Library/Application Support/SCons/site_scons + $HOME/.scons/site_scons + ./site_scons +.fi +.IP "Solaris:" +.nf + /opt/sfw/scons/site_scons + /usr/share/scons/site_scons + $HOME/.scons/site_scons + ./site_scons +.fi +.IP "Linux, HPUX, and other Posix-like systems:" +.nf + /usr/share/scons/site_scons + $HOME/.scons/site_scons + ./site_scons +.fi + .TP .RI --stack-size= KILOBYTES Set the size stack used to run threads to @@ -2269,7 +2329,7 @@ Builders by adding them to the .B SourceFileScanner object. -See the section "Scanner Objects," +See the section "Scanner Objects" below, for more information about defining your own Scanner objects and using the @@ -2351,4049 +2411,34 @@ and global functions supported by include: '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" -.TP -.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" -Creates an Action object for -the specified -.IR action . -See the section "Action Objects," -below, for a complete explanation of the arguments and behavior. - -Note that the -.BR env.Action () -form of the invocation will expand -construction variables in any argument strings, -including the -.I action -argument, at the time it is called -using the construction variables in the -.I env -construction environment through which -.BR env.Action () -was called. -The -.BR Action () -form delays all variable expansion -until the Action object is actually used. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddMethod( object, function ", [" name ]) -.TP -.RI env.AddMethod( function ", [" name ]) -When called with the -.BR AddMethod () -form, -adds the specified -.I function -to the specified -.I object -as the specified method -.IR name . -When called with the -.BR env.AddMethod () -form, -adds the specified -.I function -to the construction environment -.I env -as the specified method -.IR name . -In both cases, if -.I name -is omitted or -.BR None , -the name of the -specified -.I function -itself is used for the method name. - -Examples: - -.ES -# 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') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddOption( arguments ) -This function adds a new command-line option to be recognized. -The specified -.I arguments -are the same as supported by the standard Python -.BR optparse.add_option () -method (with a few additional capabilities noted below); -see the documentation for -.B optparse -for a thorough discussion of its option-processing capabities. - -In addition to the arguments and values supported by the -.B optparse.add_option () -method, -the SCons -.BR AddOption () -function allows you to set the -.B nargs -keyword value to -.B '?' -(a string with just the question mark) -to indicate that the specified long option(s) take(s) an -.I optional -argument. -When -.B "nargs = '?'" -is passed to the -.BR AddOption () -function, the -.B 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 -.B default= -keyword argument is supplied when calling -.BR AddOption (), -the option will have a default value of -.BR None . - -Once a new command-line option has been added with -.BR AddOption (), -the option value may be accessed using -.BR GetOption () -or -.BR env.GetOption (). -\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet. -\" Uncomment this when that works. See tigris issue 2105. -\" The value may also be set, using -\" .BR SetOption () -\" or -\" .BR env.SetOption (), -\" if conditions in a -\" .B SConscript -\" require overriding any default value. -\" Note, however, that a -\" value specified on the command line will -\" .I always -\" override a value set by any SConscript file. - -Any specified -.B help= -strings for the new option(s) -will be displayed by the -.B -H -or -.B -h -options -(the latter only if no other help text is -specified in the SConscript files). -The help text for the local options specified by -.BR AddOption () -will appear below the SCons options themselves, -under a separate -.B "Local Options" -heading. -The options will appear in the help text -in the order in which the -.BR AddOption () -calls occur. - -Example: - -.ES -AddOption('--prefix', - dest='prefix', - nargs=1, type='string', - action='store', - metavar='DIR', - help='installation prefix') -env = Environment(PREFIX = GetOption('prefix')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddPostAction( target ", " action ) -.TP -.RI env.AddPostAction( target ", " action ) -Arranges for the specified -.I action -to be performed -after the specified -.I 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddPreAction( target ", " action ) -.TP -.RI env.AddPreAction( target ", " action ) -Arranges for the specified -.I action -to be performed -before the specified -.I 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 -.B .c -file via an intermediate object file: - -.ES -foo = Program('foo.c') -AddPreAction(foo, 'pre_action') -.EE - -The specified -.B pre_action -would be executed before -.B scons -calls the link command that actually -generates the executable program binary -.BR foo , -not before compiling the -.B foo.c -file into an object file. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Alias( alias ", [" targets ", [" action ]]) -.TP -.RI env.Alias( alias ", [" targets ", [" action ]]) -Creates one or more phony targets that -expand to one or more other targets. -An optional -.I 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. -.B 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: - -.ES -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") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AllowSubstExceptions([ exception ", ...])" -Specifies the exceptions that will be allowed -when expanding construction variables. -By default, -any construction variable expansions that generate a -.B NameError -or -.BR IndexError -exception will expand to a -.B '' -(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 -.B AllowSubstExceptions -is called multiple times, -each call completely overwrites the previous list -of allowed exceptions. - -Example: - -.ES -# 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) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AlwaysBuild( target ", ...)" -.TP -.RI env.AlwaysBuild( target ", ...)" -Marks each given -.I target -so that it is always assumed to be out of date, -and will always be rebuilt if needed. -Note, however, that -.BR 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 -.I always -be built if so specified. -Multiple targets can be passed in to a single call to -.BR AlwaysBuild (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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: - -.ES -env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) -This appends new path elements to the given path in the -specified external environment -.RB ( 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 -.B os.path.normpath -and -.BR 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 -.I 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: - -.ES -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 -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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 -.I 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: - -.ES -env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -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 -.B SourceCode -function. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Example: - -.ES -env.SourceCode('.', env.BitKeeper()) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) -.TP -.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ]) -Deprecated synonyms for -.BR VariantDir () -and -.BR env.VariantDir (). -The -.I build_dir -argument becomes the -.I variant_dir -argument of -.BR VariantDir () -or -.BR env.VariantDir (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Builder( action ", [" arguments ]) -.TP -.RI env.Builder( action ", [" arguments ]) -Creates a Builder object for -the specified -.IR action . -See the section "Builder Objects," -below, for a complete explanation of the arguments and behavior. - -Note that the -.BR env.Builder () -form of the invocation will expand -construction variables in any arguments strings, -including the -.I action -argument, -at the time it is called -using the construction variables in the -.B env -construction environment through which -.BR env.Builder () -was called. -The -.BR Builder () -form delays all variable expansion -until after the Builder object is actually called. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI CacheDir( cache_dir ) -.TP -.RI env.CacheDir( cache_dir ) -Specifies that -.B scons -will maintain a cache of derived files in -.I cache_dir . -The derived files in the cache will be shared -among all the builds using the same -.BR CacheDir () -call. -Specifying a -.I cache_dir -of -.B None -disables derived file caching. - -Calling -.BR env.CacheDir () -will only affect targets built -through the specified construction environment. -Calling -.BR CacheDir () -sets a global default -that will be used by all targets built -through construction environments -that do -.I not -have an -.BR env.CacheDir () -specified. - -When a -.BR CacheDir () -is being used and -.B 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, -.B scons -will retrieve the file from the cache. -If the derived file is not present in the cache, -.B 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 -.BR CacheDir() -may be disabled for any invocation -by using the -.B --cache-disable -option. - -If the -.B --cache-force -option is used, -.B scons -will place a copy of -.I 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 -.BR CacheDir () -is added to a build, -or after using the -.B --cache-disable -option. - -When using -.BR CacheDir (), -.B scons -will report, -"Retrieved `file' from cache," -unless the -.B --cache-show -option is being used. -When the -.B --cache-show -option is used, -.B scons -will print the action that -.I 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 -.BR 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Clean( targets ", " files_or_dirs ) -.TP -.RI 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 -.B -c -command line option. -The specified targets may be a list -or an individual target. -Multiple calls to -.BR 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 -.BR Clean () -method, or as a list. -.BR Clean () -will also accept the return value of any of the construction environment -Builder methods. -Examples: - -The related -.BR NoClean () -function overrides calling -.BR Clean () -for the same target, -and any targets passed to both functions will -.I not -be removed by the -.B -c -option. - -Examples: - -.ES -Clean('foo', ['bar', 'baz']) -Clean('dist', env.Program('hello', 'hello.c')) -Clean(['foo', 'bar'], 'something_else_to_clean') -.EE - -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. -.ES -Clean(docdir, os.path.join(docdir, projectname)) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Command( target ", " source ", " action ", [" key = val ", ...])" -.TP -.RI 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 -.B source_scanner -keyword argument can -be used to specify -a Scanner object -that will be used to scan the sources. -(The global -.B 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 -.B @ -(at-sign) -to suppress printing the command in question, -or by a -.B \- -(hyphen) -to ignore the exit status of the external command. - -Examples: - -.ES -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 ]) -.EE - -.IP -Note that the -.BR 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 -.BR Dir () -or -.BR env.Dir () -functions. - -Examples: - -.ES -env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') - -env['DISTDIR'] = 'destination/directory' -env.Command(env.Dir('$DISTDIR')), None, make_distdir) -.EE - -.IP -(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.) - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ]) -.TP -.RI 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Clone([ key = val ", ...])" -Return 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: - -.ES -env2 = env.Clone() -env3 = env.Clone(CCFLAGS = '-g') -.EE -.IP -Additionally, a list of tools and a toolpath may be specified, as in -the Environment constructor: - -.ES -def MyTool(env): env['FOO'] = 'bar' -env4 = env.Clone(tools = ['msvc', MyTool]) -.EE - -The -.I parse_flags -keyword argument is also recognized: - -.ES -# create an environment for compiling programs that use wxWidgets -wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Copy([ key = val ", ...])" -A now-deprecated synonym for -.BR env.Clone() . - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.CVS( repository ", " module ) -A factory function that -returns a Builder object -to be used to fetch source files -from the specified -CVS -.IR repository . -The returned Builder -is intended to be passed to the -.B SourceCode -function. - -The optional specified -.I 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. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Examples: - -.ES -# 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')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Decider( function ) -.TP -.RI env.Decider( function ) -Specifies that all up-to-date decisions for -targets built through this construction environment -will be handled by the specified -.IR function . -The -.I function -can be one of the following strings -that specify the type of decision function -to be performed: - -.RS 10 -.HP 6 -.B 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 -.B make -can be used a synonym for -.BR timestamp-newer . - -.HP 6 -.B 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 -.I earlier -timestamp, such as can happen when restoring files from backup archives. - -.HP 6 -.B 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. -.B content -can be used as a synonym for -.BR MD5 . - -.HP 6 -.B 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 -.I not -rebuilt. -This provides behavior very similar -to the -.B 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 -.I 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. -.RE - -.IP -Examples: - -.ES -# 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') -.EE - -.IP -In addition to the above already-available functions, -the -.I function -argument may be an actual Python function -that takes the following three arguments: - -.RS 10 -.IP dependency -The Node (file) which -should cause the -.I target -to be rebuilt -if it has "changed" since the last tme -.I target was built. - -.IP target -The Node (file) being built. -In the normal case, -this is what should get rebuilt -if the -.I dependency -has "changed." - -.IP prev_ni -Stored information about the state of the -.I dependency -the last time the -.I target -was built. -This can be consulted to match various -file characteristics -such as the timestamp, -size, or content signature. -.RE - -.IP -The -.I function -should return a -.B True -(non-zero) -value if the -.I dependency -has "changed" since the last time -the -.I target -was built -(indicating that the target -.I should -be rebuilt), -and -.B False -(zero) -otherwise -(indicating that the target should -.I 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: - -.ES -def my_decider(dependency, target, prev_ni): - return not os.path.exists(str(target)) - -env.Decider(my_decider) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Default( targets ) -.TP -.RI env.Default( targets ) -This specifies a list of default targets, -which will be built by -.B scons -if no explicit targets are given on the command line. -Multiple calls to -.BR Default () -are legal, -and add to the list of default targets. - -Multiple targets should be specified as -separate arguments to the -.BR Default () -method, or as a list. -.BR Default () -will also accept the Node returned by any -of a construction environment's -builder methods. - -Examples: - -.ES -Default('foo', 'bar', 'baz') -env.Default(['a', 'b', 'c']) -hello = env.Program('hello', 'hello.c') -env.Default(hello) -.EE -.IP -An argument to -.BR Default () -of -.B None -will clear all default targets. -Later calls to -.BR Default () -will add to the (now empty) default-target list -like normal. - -The current list of targets added using the -.BR Default () -function or method is available in the -.B DEFAULT_TARGETS -list; -see below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Depends( target ", " dependency ) -.TP -.RI env.Depends( target ", " dependency ) -Specifies an explicit dependency; -the -.I target -will be rebuilt -whenever the -.I dependency -has changed. -Both the specified -.I target -and -.I 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: - -.ES -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) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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: - -.ES -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Dir( name ", [" directory ]) -.TP -.RI env.Dir( name ", [" directory ]) -This returns a Directory Node, -an object that represents the specified directory -.IR name . -.I name -can be a relative or absolute path. -.I directory -is an optional directory that will be used as the parent directory. -If no -.I directory -is specified, the current script's directory is used as the parent. - -If -.I name -is a list, SCons returns a list of Dir nodes. -Construction variables are expanded in -.IR 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Dump([ key ]) -Returns a pretty printable representation of the environment. -.IR key , -if not -.IR None , -should be a string containing the name of the variable of interest. - -This SConstruct: -.ES -env=Environment() -print env.Dump('CCCOM') -.EE -.IP -will print: -.ES -\&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' -.EE - -.ES -env=Environment() -print env.Dump() -.EE -.IP -will print: -.ES -{ 'AR': 'ar', - 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET', - 'ARFLAGS': ['r'], - 'AS': 'as', - 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', - 'ASFLAGS': [], - ... -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI EnsurePythonVersion( major ", " minor ) -.TP -.RI env.EnsurePythonVersion( major ", " minor ) -Ensure that the Python version is at least -.IR 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: - -.ES -EnsurePythonVersion(2,2) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI EnsureSConsVersion( major ", " minor ", [" revision ]) -.TP -.RI env.EnsureSConsVersion( major ", " minor ", [" revision ]) -Ensure that the SCons version is at least -.IR major.minor , -or -.IR major.minor.revision . -if -.I 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: - -.ES -EnsureSConsVersion(0,14) - -EnsureSConsVersion(0,96,90) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Environment([ key = value ", ...])" -.TP -.RI env.Environment([ key = value ", ...])" -Return a new construction environment -initialized with the specified -.IR key = value -pairs. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Execute( action ", [" strfunction ", " varlist ]) -.TP -.RI env.Execute( action ", [" strfunction ", " varlist ]) -Executes an Action object. -The specified -.IR 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 -.B scons -will print an error message if the executed -.I action -fails--that is, -exits with or returns a non-zero value. -.B scons -will -.I not , -however, -automatically terminate the build -if the specified -.I action -fails. -If you want the build to stop in response to a failed -.BR Execute () -call, -you must explicitly check for a non-zero return value: - -.ES -Execute(Copy('file.out', 'file.in')) - -if Execute("mkdir sub/dir/ectory"): - # The mkdir failed, don't try to build. - Exit(1) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Exit([ value ]) -.TP -.RI env.Exit([ value ]) -This tells -.B scons -to exit immediately -with the specified -.IR value . -A default exit value of -.B 0 -(zero) -is used if no value is specified. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Export( vars ) -.TP -.RI env.Export( vars ) -This tells -.B 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 -.BR Export () -will over-write previous exports that have the same name. -Multiple variable names can be passed to -.BR 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: - -.ES -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}) -.EE - -.IP -Note that the -.BR SConscript () -function supports an -.I 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 -.BR SConscript () -function, below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI File( name ", [" directory ]) -.TP -.RI env.File( name ", [" directory ]) -This returns a -File Node, -an object that represents the specified file -.IR name . -.I name -can be a relative or absolute path. -.I directory -is an optional directory that will be used as the parent directory. - -If -.I name -is a list, SCons returns a list of File nodes. -Construction variables are expanded in -.IR 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindFile( file ", " dirs ) -.TP -.RI env.FindFile( file ", " dirs ) -Search for -.I file -in the path specified by -.IR dirs . -.I 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: - -.ES -foo = env.FindFile('foo', ['dir1', 'dir2']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindInstalledFiles( ) -.TP -.RI env.FindInstalledFiles( ) -Returns the list of targets set up by the -.B Install() -or -.B InstallAs() -builders. - -This function serves as a convenient method to select the contents of -a binary package. - -Example: - -.ES -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() -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindSourceFiles( node = '"."' ) -.TP -.RI 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 -.B node -which defaults to the '"."'-node. It will then return all leaves of -.B 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: - -.ES -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' ) -.EE - -.IP -As you can see build support files (SConstruct in the above example) -will also be returned by this function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindPathDirs( variable ) -Returns a function -(actually a callable Python object) -intended to be used as the -.B path_function -of a Scanner object. -The returned object will look up the specified -.I variable -in a construction environment -and treat the construction variable's value as a list of -directory paths that should be searched -(like -.BR CPPPATH , -.BR LIBPATH , -etc.). - -Note that use of -.BR FindPathDirs () -is generally preferable to -writing your own -.B path_function -for the following reasons: -1) The returned list will contain all appropriate directories -found in source trees -(when -.BR VariantDir () -is used) -or in code repositories -(when -.BR Repository () -or the -.B \-Y -option are used). -2) scons will identify expansions of -.I 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: - -.ES -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')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Flatten( sequence ) -.TP -.RI 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: - -.ES -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) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetBuildFailures() -Returns a list of exceptions for the -actions that failed while -attempting to build targets. -Each element in the returned list is a -.B BuildError -object -with the following attributes -that record various aspects -of the build failure: - -.B .node -The node that was being built -when the build failure occurred. - -.B .status -The numeric exit status -returned by the command or Python function -that failed when trying to build the -specified Node. - -.B .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.) - -.B .filename -The name of the file or -directory that actually caused the failure. -This may be different from the -.B .node -attribute. -For example, -if an attempt to build a target named -.B sub/dir/target -fails because the -.B sub/dir -directory could not be created, -then the -.B .node -attribute will be -.B sub/dir/target -but the -.B .filename -attribute will be -.BR sub/dir . - -.B .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. - -.B .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. - -.B .command -The actual expanded command that was executed and failed, -after expansion of -.BR $TARGET , -.BR $SOURCE , -and other construction variables. - -Note that the -.BR GetBuildFailures () -function -will always return an empty list -until any build failure has occurred, -which means that -.BR GetBuildFailures () -will always return an empty list -while the -.B 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 -.BR atexit.register () -function. -Example: - -.ES -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) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetBuildPath( file ", [" ... ]) -.TP -.RI env.GetBuildPath( file ", [" ... ]) -Returns the -.B scons -path name (or names) for the specified -.I file -(or files). -The specified -.I file -or files -may be -.B scons -Nodes or strings representing path names. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetLaunchDir() -.TP -.RI env.GetLaunchDir() -Returns the absolute path name of the directory from which -.B scons -was initially invoked. -This can be useful when using the -.BR \-u , -.BR \-U -or -.BR \-D -options, which internally -change to the directory in which the -.B SConstruct -file is found. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetOption( name ) -.TP -.RI env.GetOption( name ) -This function provides a way to query the value of -SCons options set on scons command line -(or set using the -.IR SetOption () -function). -The options supported are: - -.RS 10 -.TP 6 -.B cache_debug -which corresponds to --cache-debug; -.TP 6 -.B cache_disable -which corresponds to --cache-disable; -.TP 6 -.B cache_force -which corresponds to --cache-force; -.TP 6 -.B cache_show -which corresponds to --cache-show; -.TP 6 -.B clean -which corresponds to -c, --clean and --remove; -.TP 6 -.B config -which corresponds to --config; -.TP 6 -.B directory -which corresponds to -C and --directory; -.TP 6 -.B diskcheck -which corresponds to --diskcheck -.TP 6 -.B duplicate -which corresponds to --duplicate; -.TP 6 -.B file -which corresponds to -f, --file, --makefile and --sconstruct; -.TP 6 -.B help -which corresponds to -h and --help; -.TP 6 -.B ignore_errors -which corresponds to --ignore-errors; -.TP 6 -.B implicit_cache -which corresponds to --implicit-cache; -.TP 6 -.B implicit_deps_changed -which corresponds to --implicit-deps-changed; -.TP 6 -.B implicit_deps_unchanged -which corresponds to --implicit-deps-unchanged; -.TP 6 -.B interactive -which corresponds to --interact and --interactive; -.TP 6 -.B keep_going -which corresponds to -k and --keep-going; -.TP 6 -.B max_drift -which corresponds to --max-drift; -.TP 6 -.B no_exec -which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; -.TP 6 -.B no_site_dir -which corresponds to --no-site-dir; -.TP 6 -.B num_jobs -which corresponds to -j and --jobs; -.TP 6 -.B profile_file -which corresponds to --profile; -.TP 6 -.B question -which corresponds to -q and --question; -.TP 6 -.B random -which corresponds to --random; -.TP 6 -.B repository -which corresponds to -Y, --repository and --srcdir; -.TP 6 -.B silent -which corresponds to -s, --silent and --quiet; -.TP 6 -.B site_dir -which corresponds to --site-dir; -.TP 6 -.B stack_size -which corresponds to --stack-size; -.TP 6 -.B taskmastertrace_file -which corresponds to --taskmastertrace; and -.TP 6 -.B warn -which corresponds to --warn and --warning. -.RE - -.IP -See the documentation for the -corresponding command line object for information about each specific -option. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Glob( pattern ", [" ondisk ", " source ", " strings ]) -.TP -.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ]) -Returns Nodes (or strings) that match the specified -.IR pattern , -relative to the directory of the current -.B SConscript -file. -The -.BR env.Glob () -form performs string substition on -.I pattern -and returns whatever matches -the resulting expanded pattern. - -The specified -.I pattern -uses Unix shell style metacharacters for matching: - -.ES - * matches everything - ? matches any single character - [seq] matches any character in seq - [!seq] matches any char not in seq -.EE - -.IP -If the first character of a filename is a dot, -it must be matched explicitly. -Character matches do -.I not -span directory separators. - -The -.BR Glob () -knows about -repositories -(see the -.BR Repository () -function) -and source directories -(see the -.BR 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 -.B ondisk -argument may be set to -.B 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 -.B source -argument may be set to -.B True -(or any equivalent value) -to specify that, -when the local directory is a -.BR VariantDir (), -the returned Nodes should be from the -corresponding source directory, -not the local directory. - -The -.B strings -argument may be set to -.B True -(or any equivalent value) -to have the -.BR 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 -.B SConscript -file, -any Node translation will be relative -to the other -.B SConscript -directory, -not the original -.B SConscript -directory.) - -Examples: - -.ES -Program('foo', Glob('*.c')) -Zip('/tmp/everything', Glob('.??*') + Glob('*')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\".TP -'\".RI GlobalBuilders( flag ) -'\"When -'\".B flag -'\"is non-zero, -'\"adds the names of the default builders -'\"(Program, Library, etc.) -'\"to the global name space -'\"so they can be called without an explicit construction environment. -'\"(This is the default.) -'\"When -'\".B -'\"flag is zero, -'\"the names of the default builders are removed -'\"from the global name space -'\"so that an explicit construction environment is required -'\"to call all builders. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Help( text ) -.TP -.RI env.Help( text ) -This specifies help text to be printed if the -.B -h -argument is given to -.BR scons . -If -.BR Help -is called multiple times, the text is appended together in the order -that -.BR Help -is called. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Ignore( target ", " dependency ) -.TP -.RI 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 -.BR 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: - -.ES -env.Ignore('foo', 'foo.c') -env.Ignore('bar', ['bar1.h', 'bar2.h']) -env.Ignore('.','foobar.obj') -env.Ignore('bar','bar/foobar.obj') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Import( vars ) -.TP -.RI env.Import( vars ) -This tells -.B scons -to import a list of variables into the current SConscript file. This -will import variables that were exported with -.BR Export () -or in the -.I exports -argument to -.BR SConscript (). -Variables exported by -.BR SConscript () -have precedence. -Multiple variable names can be passed to -.BR Import () -as separate arguments or as a list. The variable "*" can be used -to import all variables. - -Examples: - -.ES -Import("env") -Import("env", "variable") -Import(["env", "variable"]) -Import("*") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Literal( string ) -.TP -.RI env.Literal( string ) -The specified -.I string -will be preserved as-is -and not have construction variables expanded. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Local( targets ) -.TP -.RI env.Local( targets ) -The specified -.I 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -\" .TP -\" .RI env.MergeShellPaths( arg ", [" prepend ]) -\" Merges the elements of the specified -\" .IR arg , -\" which must be a dictionary, to the construction -\" environment's copy of the shell environment -\" in env['ENV']. -\" (This is the environment which is passed -\" to subshells spawned by SCons.) -\" Note that -\" .I arg -\" must be a single value, -\" so multiple strings must -\" be passed in as a list, -\" not as separate arguments to -\" .BR env.MergeShellPaths (). - -\" New values are prepended to the environment variable by default, -\" unless prepend=0 is specified. -\" Duplicate values are always eliminated, -\" since this function calls -\" .B AppendENVPath -\" or -\" .B PrependENVPath -\" depending on the -\" .I prepend -\" argument. See those functions for more details. - -\" Examples: - -\" .ES -\" # Prepend a path to the shell PATH. -\" env.MergeShellPaths({'PATH':'/usr/local/bin'} ) -\" # Append two dirs to the shell INCLUDE. -\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 ) - -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.MergeFlags( arg ", [" unique ]) -Merges the specified -.I arg -values to the construction environment's construction variables. -If the -.I arg -argument is not a dictionary, -it is converted to one by calling -.B env.ParseFlags() -on the argument -before the values are merged. -Note that -.I arg -must be a single value, -so multiple strings must -be passed in as a list, -not as separate arguments to -.BR env.MergeFlags (). - -By default, -duplicate values are eliminated; -you can, however, specify -.B unique=0 -to allow duplicate -values to be added. -When eliminating duplicate values, -any construction variables that end with -the string -.B PATH -keep the left-most unique value. -All other construction variables keep -the right-most unique value. - -Examples: - -.ES -# 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']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI NoCache( target ", ...)" -.TP -.RI env.NoCache( target ", ...)" -Specifies a list of files which should -.I not -be cached whenever the -.BR 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 -.BR NoCache () -method, or as a list. -.BR NoCache () -will also accept the return value of any of the construction environment -Builder methods. - -Calling -.BR NoCache () -on directories and other non-File Node types has no effect because -only File Nodes are cached. - -Examples: - -.ES -NoCache('foo.elf') -NoCache(env.Program('hello', 'hello.c')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI NoClean( target ", ...)" -.TP -.RI env.NoClean( target ", ...)" -Specifies a list of files or directories which should -.I not -be removed whenever the targets (or their dependencies) -are specified with the -.B -c -command line option. -The specified targets may be a list -or an individual target. -Multiple calls to -.BR NoClean () -are legal, -and prevent each specified target -from being removed by calls to the -.B -c -option. - -Multiple files or directories should be specified -either as separate arguments to the -.BR NoClean () -method, or as a list. -.BR NoClean () -will also accept the return value of any of the construction environment -Builder methods. - -Calling -.BR NoClean () -for a target overrides calling -.BR Clean () -for the same target, -and any targets passed to both functions will -.I not -be removed by the -.B -c -option. - -Examples: - -.ES -NoClean('foo.elf') -NoClean(env.Program('hello', 'hello.c')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.ParseConfig( command ", [" function ", " unique ]) -Calls the specified -.I function -to modify the environment as specified by the output of -.I command . -The default -.I function -is -.BR env.MergeFlags (), -which expects the output of a typical -.I *-config command -(for example, -.BR 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 -.B unique=0 -to allow duplicate -values to be added. - -Interpreted options -and the construction variables they affect -are as specified for the -.BR env.ParseFlags () -method (which this method calls). -See that method's description, below, -for a table of options and construction variables. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI ParseDepends( filename ", [" must_exist ", " only_one ]) -.TP -.RI env.ParseDepends( filename ", [" must_exist ", " only_one ]) -Parses the contents of the specified -.I filename -as a list of dependencies in the style of -.BR Make -or -.BR mkdep , -and explicitly establishes all of the listed dependencies. - -By default, -it is not an error -if the specified -.I filename -does not exist. -The optional -.I 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 -.I 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 -.B gcc -M -flag, -which should typically only -write dependency information for -one output file into a corresponding -.B .d -file. - -The -.I filename -and all of the files listed therein -will be interpreted relative to -the directory of the -.I SConscript -file which calls the -.B ParseDepends -function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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 -.BR 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 -.BR env.MergeFlags () -will call this method if its argument is not a dictionary, -so it is usually not necessary to call -.BR 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: - -.ES --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 -.EE - -.IP -Any other strings not associated with options -are assumed to be the names of libraries -and added to the -.B LIBS -construction variable. - -Examples (all of which produce the same result): - -.ES -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') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -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 -.B SourceCode -function. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Example: - -.ES -env.SourceCode('.', env.Perforce()) -.EE -.IP -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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Platform( string ) -Returns a callable object -that can be used to initialize -a construction environment using the -platform keyword of the Environment() method. - -Example: - -.ES -env = Environment(platform = Platform('win32')) -.EE -.TP -.RI env.Platform( string ) -Applies the callable object for the specified platform -.I string -to the environment through which the method was called. - -.ES -env.Platform('posix') -.EE -.IP -Note that the -.B win32 -platform adds the -.B SystemDrive -and -.B SystemRoot -variables from the user's external environment -to the construction environment's -.B 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 -.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) -will work on Windows systems. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Progress( callable ", [" interval ]) -.TP -.RI Progress( string ", [" interval ", " file ", " overwrite ]) -.TP -.RI 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 -.BR __call__ () -method), -the function will be called -once every -.I 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 -.B *args -and -.B **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: - -.ES -def my_progress_function(node, *args, **kw): - print 'Evaluating node %s!' % node -Progress(my_progress_function, interval=10) -.EE -.IP -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 -.B \\\\r -(a carriage return) -at the end so that the string -will overwrite itself on a display: - -.ES -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) -.EE -.IP -If the first argument -.BR Progress () -is a string, -the string will be displayed -every -.I interval -evaluated Nodes. -The default is to print the string on standard output; -an alternate output stream -may be specified with the -.B file= -argument. -The following will print a series of dots -on the error output, -one dot for every 100 evaluated Nodes: - -.ES -import sys -Progress('.', interval=100, file=sys.stderr) -.EE -.IP -If the string contains the verbatim substring -.B $TARGET, -it will be replaced with the Node. -Note that, for performance reasons, this is -.I 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 -.B \\\\r -(carriage return) to cause each line to overwritten by the next line, -and the -.B overwrite= -keyword argument to make sure the previously-printed -file name is overwritten with blank spaces: - -.ES -import sys -Progress('$TARGET\\r', overwrite=True) -.EE -.IP -If the first argument to -.BR Progress () -is a list of strings, -then each string in the list will be displayed -in rotating fashion every -.I interval -evaluated Nodes. -This can be used to implement a "spinner" -on the user's screen as follows: - -.ES -Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Precious( target ", ...)" -.TP -.RI env.Precious( target ", ...)" -Marks each given -.I target -as precious so it is not deleted before it is rebuilt. Normally -.B scons -deletes a target before building it. -Multiple targets can be passed in to a single call to -.BR Precious (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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: - -.ES -env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) -This appends new path elements to the given path in the -specified external environment -.RB ( 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 -.B os.path.normpath -and -.BR 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 -.I 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: - -.ES -print 'before:',env['ENV']['INCLUDE'] -include_path = '/foo/bar:/foo' -env.PrependENVPath('INCLUDE', include_path) -print 'after:',env['ENV']['INCLUDE'] -.EE - -The above exmaple will print: - -.ES -before: /biz:/foo -after: /foo/bar:/foo:/biz -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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 -.I 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: - -.ES -env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -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 -.B SourceCode -function: - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Examples: - -.ES -env.SourceCode('.', env.RCS()) -.EE -.IP -Note that -.B 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. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Replace( key = val ", [...])" -Replaces construction variables in the Environment -with the specified keyword arguments. - -Example: - -.ES -env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Repository( directory ) -.TP -.RI env.Repository( directory ) -Specifies that -.I directory -is a repository to be searched for files. -Multiple calls to -.BR Repository () -are legal, -and each one adds to the list of -repositories that will be searched. - -To -.BR 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 -.BR scons , -so that the repository contains the necessary -signature information to allow -.B 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, -.B scons -will -.I not -make a copy in the local directory tree. -In order to guarantee that a local copy -will be made, -use the -.B Local() -method. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Requires( target ", " prerequisite ) -.TP -.RI 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, -.I 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: - -.ES -env.Requires('foo', 'file-that-must-be-built-before-foo') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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 -.I vars -string arguments. -Multiple strings contaning variable names may be passed to -.BR Return (). -Any strings that contain white space - -The optional -.B stop= -keyword argument may be set to a false value -to continue processing the rest of the SConscript -file after the -.BR 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 -.I vars -at the point -.BR Return () -is called. - -Examples: - -.ES -# 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') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) -.TP -.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) -Creates a Scanner object for -the specified -.IR function . -See the section "Scanner Objects," -below, for a complete explanation of the arguments and behavior. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -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 -.B SourceCode -function. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Example: - -.ES -env.SourceCode('.', env.SCCS()) -.EE -.IP -Note that -.B 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 -.I s.SCCS -files in the same -directory as the source files, -or if you need to explicitly specify SCCS -for a specific subdirectory. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) -'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) -.TP -.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) -'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) -.TP -.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) -'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) -.TP -.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) -'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) -This tells -.B scons -to execute -one or more subsidiary SConscript (configuration) files. -Any variables returned by a called script using -.BR Return () -will be returned by the call to -.BR SConscript (). -There are two ways to call the -.BR SConscript () -function. - -The first way you can call -.BR SConscript () -is to explicitly specify one or more -.I 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 -.BR Split ()). -Examples: -.ES -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') -.EE - -The second way you can call -.BR SConscript () -is to specify a list of (sub)directory names -as a -.RI dirs= subdirs -keyword argument. -In this case, -.B scons -will, by default, -execute a subsidiary configuration file named -.B SConscript -in each of the specified directories. -You may specify a name other than -.B SConscript -by supplying an optional -.RI name= script -keyword argument. -The first three examples below have the same effect -as the first three examples above: -.ES -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') -.EE - -The optional -.I exports -argument provides a list of variable names or a dictionary of -named values to export to the -.IR script(s) . -These variables are locally exported only to the specified -.IR script(s) , -and do not affect the global pool of variables used by the -.BR Export () -function. -'\"If multiple dirs are provided, each script gets a fresh export. -The subsidiary -.I script(s) -must use the -.BR Import () -function to import the variables. -Examples: -.ES -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') -.EE - -If the optional -.I variant_dir -argument is present, it causes an effect equivalent to the -.BR VariantDir () -method described below. -(If -.I variant_dir -is not present, the -'\" .IR src_dir and -.I duplicate -'\" arguments are ignored.) -argument is ignored.) -The -.I variant_dir -'\" and -'\" .I src_dir -'\" arguments are interpreted relative to the directory of the calling -argument is interpreted relative to the directory of the calling -.B SConscript -file. -See the description of the -.BR VariantDir () -function below for additional details and restrictions. - -If -.I variant_dir -is present, -'\" but -'\" .IR src_dir " is not," -the source directory is the directory in which the -.B SConscript -file resides and the -.B SConscript -file is evaluated as if it were in the -.I variant_dir -directory: -.ES -SConscript('src/SConscript', variant_dir = 'build') -.EE -is equivalent to -.ES -VariantDir('build', 'src') -SConscript('build/SConscript') -.EE -This later paradigm is often used when the sources are -in the same directory as the -.BR SConstruct: -.ES -SConscript('SConscript', variant_dir = 'build') -.EE -is equivalent to -.ES -VariantDir('build', '.') -SConscript('build/SConscript') -.EE - -'\" If -'\" .IR variant_dir " and" -'\" .IR src_dir " are both present," -'\" xxxxx everything is in a state of confusion. -'\" .ES -'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.') -'\" runs src/SConscript in build/src, but -'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src') -'\" runs lib/SConscript (in lib!). However, -'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src') -'\" runs src/SConscript in build. Moreover, -'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src') -'\" runs src/lib/SConscript in build/lib. Moreover, -'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src') -'\" can't find build/src/lib/SConscript, even though it ought to exist. -'\" .EE -'\" is equivalent to -'\" .ES -'\" ???????????????? -'\" .EE -'\" and what about this alternative? -'\"TODO??? SConscript('build/SConscript', src_dir='src') - -Here are some composite examples: - -.ES -# 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') -.EE - -.ES -# 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) -.EE - -.ES -# 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) -.EE - -.ES -# 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) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConscriptChdir( value ) -.TP -.RI env.SConscriptChdir( value ) -By default, -.B scons -changes its working directory -to the directory in which each -subsidiary SConscript file lives. -This behavior may be disabled -by specifying either: - -.ES -SConscriptChdir(0) -env.SConscriptChdir(0) -.EE -.IP -in which case -.B 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: - -.ES -env = Environment() -SConscriptChdir(0) -SConscript('foo/SConscript') # will not chdir to foo -env.SConscriptChdir(1) -SConscript('bar/SConscript') # will chdir to bar -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConsignFile([ file , dbm_module ]) -.TP -.RI env.SConsignFile([ file , dbm_module ]) -This tells -.B scons -to store all file signatures -in the specified database -.IR file . -If the -.I file -name is omitted, -.B .sconsign -is used by default. -(The actual file name(s) stored on disk -may have an appropriated suffix appended -by the -.IR dbm_module .) -If -.I file -is not an absolute path name, -the file is placed in the same directory as the top-level -.B SConstruct -file. - -If -.I file -is -.BR None , -then -.B scons -will store file signatures -in a separate -.B .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 -.I dbm_module -argument can be used to specify -which Python database module -The default is to use a custom -.B SCons.dblite -module that uses pickled -Python data structures, -and which works on all Python versions. - -Examples: - -.ES -# 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) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI 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: - -.ES -env.SetDefault(FOO = 'foo') - -if 'FOO' not in env: env['FOO'] = 'foo' -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SetOption( name ", " value ) -.TP -.RI 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: - -.RS 10 -.TP 6 -.B clean -which corresponds to -c, --clean and --remove; -.TP 6 -.B duplicate -which corresponds to --duplicate; -.TP 6 -.B help -which corresponds to -h and --help; -.TP 6 -.B implicit_cache -which corresponds to --implicit-cache; -.TP 6 -.B max_drift -which corresponds to --max-drift; -.TP 6 -.B no_exec -which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; -.TP 6 -.B num_jobs -which corresponds to -j and --jobs; -.TP 6 -.B random -which corresponds to --random; and -.TP 6 -.B stack_size -which corresponds to --stack-size. -.RE - -.IP -See the documentation for the -corresponding command line object for information about each specific -option. - -Example: - -.ES -SetOption('max_drift', 1) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SideEffect( side_effect ", " target ) -.TP -.RI env.SideEffect( side_effect ", " target ) -Declares -.I side_effect -as a side effect of building -.IR target . -Both -.I side_effect -and -.I 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, -.B 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 -.I side_effect -target is -.I not -automatically removed -when the -.I target -is removed by the -.B -c -option. -(Note, however, that the -.I side_effect -might be removed as part of -cleaning the directory in which it lives.) -If you want to make sure the -.I side_effect -is cleaned whenever a specific -.I target -is cleaned, -you must specify this explicitly -with the -.BR Clean () -or -.BR env.Clean () -function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SourceCode( entries ", " builder ) -.TP -.RI 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 -.IR builder . -The specified -.I 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, -.B scons -will search up the directory tree -and use the first -.B SourceCode -builder it finds. -The specified -.I builder -may be -.BR None , -in which case -.B scons -will not use a builder to fetch -source files for the specified -.IR entries , -even if a -.B SourceCode -builder has been specified -for a directory higher up the tree. - -.B 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: - -.ES -env.SourceCode('.', None) -.EE - -.IP -Note that if the specified -.I builder -is one you create by hand, -it must have an associated -construction environment to use -when fetching a source file. - -.B scons -provides a set of canned factory -functions that return appropriate -Builders for various popular -source code management systems. -Canonical examples of invocation include: - -.ES -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) -.EE -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.subst( input ", [" raw ", " target ", " source ", " conv ]) -Performs construction variable interpolation -on the specified string or sequence argument -.IR 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 -.B $( -and -.B $) -character sequences will be stripped from the returned string, -The optional -.I raw -argument may be set to -.B 1 -if you want to preserve white space and -.BR $( - $) -sequences. -The -.I raw -argument may be set to -.B 2 -if you want to strip -all characters between -any -.B $( -and -.B $) -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 -.I target -and -.I source -keyword arguments -must be set to lists of -target and source nodes, respectively, -if you want the -.BR $TARGET , -.BR $TARGETS , -.BR $SOURCE -and -.BR $SOURCES -to be available for expansion. -This is usually necessary if you are -calling -.BR 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 -.I 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 -.B lambda -idiom to pass in an unnamed function -that simply returns its unconverted argument. - -Example: - -.ES -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) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\".TP -'\".RI Subversion( repository ", " module ) -'\"A factory function that -'\"returns a Builder object -'\"to be used to fetch source files -'\"from the specified Subversion -'\".IR repository . -'\"The returned Builder -'\"is intended to be passed to the -'\".B SourceCode -'\"function. -'\" -'\"The optional specified -'\".I 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. -'\" -'\"This function is deprecated. For details, see the entry for the -'\".B SourceCode -'\"function. -'\" -'\"Example: -'\" -'\".ES -'\"# Will fetch foo/bar/src.c -'\"# from /usr/local/Subversion/foo/bar/src.c. -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) +'\" BEGIN GENERATED FUNCTION DESCRIPTIONS '\" -'\"# Will fetch bar/src.c -'\"# from /usr/local/Subversion/foo/bar/src.c. -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo')) +'\" The descriptions below of the various SCons functions are generated +'\" from the .xml files that live next to the various Python modules in +'\" the build enginer library. If you're reading this [gnt]roff file +'\" with an eye towards patching this man page, you can still submit +'\" a diff against this text, but it will have to be translated to a +'\" diff against the underlying .xml file before the patch is actually +'\" accepted. If you do that yourself, it will make it easier to +'\" integrate the patch. '\" -'\"# Will fetch src.c -'\"# from /usr/local/Subversion/foo/bar/src.c. -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar')) -'\".EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SourceSignatures( type ) -.TP -.RI env.SourceSignatures( type ) -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -.BR Decider () -function for a more flexible and straightforward way -to configure SCons' decision-making. - -The -.BR SourceSignatures () -function tells -.B 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 -.B "MD5" -or -.BR "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. - -.B "MD5" -means -.B 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. - -.B "timestamp" -means -.B 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 -.I older -than the last time it was used to rebuild the target file.) - -There is no different between the two behaviors -for Python -.BR Value () -node objects. - -.B "MD5" -signatures take longer to compute, -but are more accurate than -.B "timestamp" -signatures. -The default value is -.BR "MD5" . - -Note that the default -.BR TargetSignatures () -setting (see below) -is to use this -.BR SourceSignatures () -setting for any target files that are used -to build other target files. -Consequently, changing the value of -.BR 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 -.BR env.SourceSignatures () -is used). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Split( arg ) -.TP -.RI 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: - -.ES -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 -""") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Tag( node ", " tags ) -Annotates file or directory Nodes with -information about how the -.BR Package () -Builder should package those files or directories. -All tags are optional. - -Examples: - -.ES -# 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 ) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI TargetSignatures( type ) -.TP -.RI env.TargetSignatures( type ) -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -.BR Decider () -function for a more flexible and straightforward way -to configure SCons' decision-making. - -The -.BR TargetSignatures () -function tells -.B scons -how to decide if a target file -(a file that -.I is -built from any other files) -has changed since the last time it -was used to build some other target file. -Legal values are -.BR "build" ; -.BR "content" -(or its synonym -.BR "MD5" ); -.BR "timestamp" ; -or -.BR "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. - -.B "content" -(or its synonym -.BR "MD5" ) -means -.B 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 -.B 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. - -.B "timestamp" -means -.B 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 -.I older -than the last time it was used to rebuild the target file.) - -.B "source" -means -.B scons -decides that a target file has changed -as specified by the corresponding -.BR SourceSignatures () -setting -.BR "" ( "MD5" -or -.BR "timestamp" ). -This means that -.B 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. - -.B "build" -means -.B 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 -.BR 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. - -.B "build" -signatures are fastest because -.B "content" -(or -.BR "MD5" ) -signatures take longer to compute, -but are more accurate than -.B "timestamp" -signatures, -and can prevent unnecessary "downstream" rebuilds -when a target file is rebuilt to the exact same contents -as the previous build. -The -.B "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 -.BR "source" . - -Because the default setting is -.BR "source" , -using -.BR SourceSignatures () -is generally preferable to -.BR 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 -.BR TargetSignatures () -provides specific control for how built target files -affect their "downstream" dependencies. - +'\" BEGIN GENERATED FUNCTION DESCRIPTIONS '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Tool( string [, toolpath ", " **kw ]) -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 -.B $TOOLS -construction variable. - -Additional keyword arguments are passed to the tool's -.B generate() -method. - -Examples: - -.ES -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 -.EE -.TP -.RI env.Tool( string [, toolpath ", " **kw ]) -Applies the callable object for the specified tool -.I string -to the environment through which the method was called. - -Additional keyword arguments are passed to the tool's -.B generate() -method. - -.ES -env.Tool('gcc') -env.Tool('opengl', toolpath = ['build/tools']) -.EE - +.so functions.man '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Value( value ", [" built_value ]) -.TP -.RI 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 -.BR str( value ) -changes between SCons runs, any targets depending on -.BR 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 -.BR write () -method that can be used to "build" a Value Node -by setting a new value. -The optional -.I 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 -.BR read () -method that will return the built value of the Node. - -Examples: - -.ES -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)) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ]) -.TP -.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ]) -Use the -.BR VariantDir () -function to create a copy of your sources in another location: -if a name under -.IR variant_dir -is not found but exists under -.IR src_dir , -the file or directory is copied to -.IR 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. - -.BR VariantDir () -can be called multiple times with the same -.I src_dir -to set up multiple builds with different options -.RI ( variants ). -The -.I src_dir -location must be in or underneath the SConstruct file's directory, and -.I variant_dir -may not be underneath -.IR src_dir . -'\"TODO: Can the above restrictions be clarified or relaxed? -'\"TODO: The latter restriction is clearly not completely right; -'\"TODO: src_dir = '.' works fine with a build dir under it. - -The default behavior is for -.B 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 -.IR --duplicate -command-line option. -Moreover, only the files needed for the build are duplicated; -files and directories that are not used are not present in -.IR variant_dir . - -Duplicating the source tree may be disabled by setting the -.I duplicate -argument to 0 (zero). -This will cause -.B scons -to invoke Builders using the path names of source files in -.I src_dir -and the path names of derived files within -.IR variant_dir . -This is always more efficient than -.IR duplicate =1, -and is usually safe for most builds -(but see above for cases that may cause problems). - -Note that -.BR 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 -.I variant_dir , -regardless of the value of -.IR duplicate . -This is how you tell -.B scons -which variant of a source tree to build: - -.ES -# run src/SConscript in two variant directories -VariantDir('build/variant1', 'src') -SConscript('build/variant1/SConscript') -VariantDir('build/variant2', 'src') -SConscript('build/variant2/SConscript') -.EE - -.IP -See also the -.BR SConscript () -function, described above, -for another way to specify a variant directory -in conjunction with calling a subsidiary SConscript file. - -Examples: - -.ES -# use names in the build directory, not the source directory -VariantDir('build', 'src', duplicate=0) -Program('build/prog', 'build/source.c') -.EE - -.ES -# this builds both the source and docs in a separate subtree -VariantDir('build', '.', duplicate=0) -SConscript(dirs=['build/src','build/doc']) -.EE - -.ES -# 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) -.EE - +'\" END GENERATED FUNCTION DESCRIPTIONS +'\" +'\" The descriptions above of the various SCons functions are generated +'\" from the .xml files that live next to the various Python modules in +'\" the build enginer library. If you're reading this [gnt]roff file +'\" with an eye towards patching this man page, you can still submit +'\" a diff against this text, but it will have to be translated to a +'\" diff against the underlying .xml file before the patch is actually +'\" accepted. If you do that yourself, it will make it easier to +'\" integrate the patch. +'\" +'\" END GENERATED FUNCTION DESCRIPTIONS '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI WhereIs( program ", [" path ", " pathext ", " reject ]) -.TP -.RI env.WhereIs( program ", [" path ", " pathext ", " reject ]) - -Searches for the specified executable -.I program, -returning the full path name to the program -if it is found, -and returning None if not. -Searches the specified -.I 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 -.I 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 -.I reject -list, if any. .SS SConscript Variables In addition to the global functions and methods, @@ -8105,14 +4150,14 @@ implicit dependencies based only on the target file and the construction environment, .I not -for implicit -(See the section "Scanner Objects," below, +for implicit dependencies based on source files. +(See the section "Scanner Objects" below, for information about creating Scanner objects.) .IP source_scanner A Scanner object that will be invoked to -find implicit dependences in +find implicit dependencies in any source files used to build this target file. This is where you would @@ -8129,7 +4174,7 @@ for on-disk changes to files that .B scons does not know about from other Builder or function calls. -(See the section "Scanner Objects," below, +(See the section "Scanner Objects" below, for information about creating your own Scanner objects.) .IP target_factory @@ -9234,7 +5279,7 @@ to enclose arbitrary Python code to be evaluated. (In fact, this is how the above modifiers are substituted, they are simply attributes of the Python objects that represent TARGET, SOURCES, etc.) -See the section "Python Code Substitution," below, +See the section "Python Code Substitution" below, for more thorough examples of how this can be used. @@ -9411,9 +5456,9 @@ function accepts the following arguments: This can be either: 1) a Python function that will process the Node (file) -and return a list of strings (file names) +and return a list of File Nodes representing the implicit -dependencies found in the contents; +dependencies (file names) found in the contents; or: 2) a dictionary that maps keys (typically the file suffix, but see below for more discussion) @@ -9587,7 +5632,7 @@ def xyz_scan(node, env, path): XYZScanner = Scanner(xyz_scan) -SourceFileScanner.add_scanner('.xyx', XYZScanner) +SourceFileScanner.add_scanner('.xyz', XYZScanner) env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) .EE @@ -9856,7 +5901,7 @@ include_re = re.compile(r'^include\\s+(\\S+)$', re.M) def kfile_scan(node, env, path, arg): contents = node.get_text_contents() includes = include_re.findall(contents) - return includes + return env.File(includes) kscan = Scanner(name = 'kfile', function = kfile_scan, @@ -9872,6 +5917,14 @@ env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') bar_in.target_scanner = kscan .EE +It is important to note that you +have to return a list of File nodes from the scan function, simple +strings for the file names won't do. As in the examples we are showing here, +you can use the +.BR File() +function of your current Environment in order to create nodes on the fly from +a sequence of file names with relative paths. + Here is a similar but more complete example that searches a path of directories (specified as the @@ -9880,30 +5933,35 @@ construction variable) for files that actually exist: .ES +import re +import os include_re = re.compile(r'^include\\s+(\\S+)$', re.M) def my_scan(node, env, path, arg): - contents = node.get_text_contents() - includes = include_re.findall(contents) - if includes == []: + contents = node.get_text_contents() + includes = include_re.findall(contents) + if includes == []: return [] results = [] for inc in includes: for dir in path: - file = dir + os.sep + inc + file = str(dir) + os.sep + inc if os.path.exists(file): results.append(file) break - return results + return env.File(results) scanner = Scanner(name = 'myscanner', function = my_scan, argument = None, skeys = ['.x'], - path_function = FindPathDirs('MYPATH'), + path_function = FindPathDirs('MYPATH') ) scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [scanner]) +env = Environment(SCANNERS = scanners + [scanner], + MYPATH = ['incs']) + +env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') .EE The @@ -9913,7 +5971,13 @@ function used in the previous example returns a function that will return a list of directories specified in the .B $MYPATH -construction variable. +construction variable. It lets SCons detect the file +.B incs/foo.inc +, even if +.B foo.x +contains the line +.B include foo.inc +only. If you need to customize how the search path is derived, you would provide your own .B path_function @@ -9934,7 +5998,7 @@ scanner = Scanner(name = 'myscanner', function = my_scan, argument = None, skeys = ['.x'], - path_function = pf, + path_function = pf ) .EE |