.fi
.RE
..
-.TH SCONS 1 "December 2005"
+.TH SCONS 1 "__MONTH_YEAR__"
.SH NAME
scons \- a software construction tool
.SH SYNOPSIS
.TP
--debug=memoizer
-Prints a summary of hits and misses in the Memoizer,
-the internal SCons subsystem for caching
-various values in memory instead of
-recomputing them each time they're needed.
+Prints a summary of hits and misses using the Memoizer,
+an internal subsystem that counts
+how often SCons uses cached values in memory
+instead of recomputing them each time they're needed.
+Only available when using Python 2.2 or later.
.TP
--debug=memory
.TP
--debug=nomemoizer
-Disables use of the Memoizer,
-the internal SCons subsystem for caching
-various values in memory instead of
-recomputing them each time they're needed.
-This provides more accurate counts of the
-underlying function calls in the
-Python profiler output when using the
-.RI --profile=
-option.
-(When the Memoizer is used,
-the profiler counts all
-memoized functions as being executed
-by the Memoizer's wrapper calls.)
+A deprecated option preserved for backwards compatibility.
.TP
--debug=objects
.ES
$ scons --debug=presub
Building myprog.o with action(s):
- $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
+ $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
...
.EE
env.Program('bar.c')
.EE
+As a convenience, a
+.B srcdir
+keyword argument may be specified
+when calling a Builder.
+When specified,
+all source file strings that are not absolute paths
+will be interpreted relative to the specified
+.BR srcdir .
+The following example will build the
+.B build/prog
+(or
+.B build/prog.exe
+on Windows)
+program from the files
+.B src/f1.c
+and
+.BR src/f2.c :
+
+.ES
+env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
+.EE
+
It is possible to override or add construction variables when calling a
builder method by passing additional keyword arguments.
These overridden or added
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 ", ...)"
foo = env.FindFile('foo', ['dir1', 'dir2'])
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.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 BuildDir ()
+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 )
-mno-cygwin CCFLAGS, LINKFLAGS
-mwindows LINKFLAGS
-pthread CCFLAGS, LINKFLAGS
+-std= CFLAGS
-Wa, ASFLAGS, CCFLAGS
-Wl,-rpath= RPATH
-Wl,-R, RPATH
to raise an exception (see example below).
.I converter
is called to convert the value before putting it in the environment, and
-should take a single argument: value.
+should take either a value, or the value and environment, as parameters.
The
.I converter
must return a value,
${SOURCE.rsrcdir} => /usr/repository/src
.EE
+Note that curly braces braces may also be used
+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,
+for more thorough examples of
+how this can be used.
+
Lastly, a variable name
may be a callable Python function
associated with a
echo Last build occurred . > $TARGET
.EE
+.SS Python Code Substitution
+
+Any python code within
+.BR "${" - "}"
+pairs gets evaluated by python 'eval', with the python globals set to
+the current environment's set of construction variables.
+So in the following case:
+.ES
+env['COND'] = 0
+env.Command('foo.out', 'foo.in',
+ '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
+.EE
+the command executed will be either
+.ES
+echo FOO > foo.out
+.EE
+or
+.ES
+echo BAR > foo.out
+.EE
+according to the current value of env['COND'] when the command is
+executed. The evaluation occurs when the target is being
+built, not when the SConscript is being read. So if env['COND'] is changed
+later in the SConscript, the final value will be used.
+
+Here's a more interesting example. Note that all of COND, FOO, and
+BAR are environment variables, and their values are substituted into
+the final command. FOO is a list, so its elements are interpolated
+separated by spaces.
+
+.ES
+env=Environment()
+env['COND'] = 0
+env['FOO'] = ['foo1', 'foo2']
+env['BAR'] = 'barbar'
+env.Command('foo.out', 'foo.in',
+ 'echo ${COND==1 and FOO or BAR} > $TARGET')
+
+# Will execute this:
+# echo foo1 foo2 > foo.out
+.EE
+
SCons uses the following rules when converting construction variables into
command lines:
returns a tuple of directories
that can be searched for files to be returned
by this Scanner object.
+(Note that the
+.BR FindPathDirs ()
+function can be used to return a ready-made
+.B path_function
+for a given construction variable name,
+instead of having to write your own function from scratch.)
.IP node_class
The class of Node that should be returned
.SS Defining Your Own Scanner Object
+The following example shows an extremely simple scanner (the
+.BR kfile_scan ()
+function)
+that doesn't use a search path at all
+and simply returns the
+file names present on any
+.B include
+lines in the scanned file.
+This would implicitly assume that all included
+files live in the top-level directory:
+
.ES
import re
bar_in.target_scanner = kscan
.EE
+Here is a similar but more complete example that searches
+a path of directories
+(specified as the
+.B MYPATH
+construction variable)
+for files that actually exist:
+
+.ES
+include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
+
+def my_scan(node, env, path, arg):
+ contents = node.get_contents()
+ includes = include_re.findall(contents)
+ if includes == []:
+ return []
+ results = []
+ for inc in includes:
+ for dir in path:
+ file = dir + os.sep + inc
+ if os.path.exists(file):
+ results.append(file)
+ break
+ return results
+
+scanner = Scanner(name = 'myscanner',
+ function = my_scan,
+ argument = None,
+ skeys = ['.x'],
+ path_function = FindPathDirs('MYPATH'),
+ )
+scanners = Environment().Dictionary('SCANNERS')
+env = Environment(SCANNERS = scanners + [scanner])
+.EE
+
+The
+.BR FindPathDirs ()
+function used in the previous example returns a function
+(actually a callable Python object)
+that will return a list of directories
+specified in the
+.B $MYPATH
+construction variable.
+If you need to customize how the search path is derived,
+you would provide your own
+.B path_function
+argument when creating the Scanner object,
+as follows:
+
+.ES
+# MYPATH is a list of directories to search for files in
+def pf(env, dir, target, source, arg):
+ top_dir = Dir('#').abspath
+ results = []
+ if env.has_key('MYPATH'):
+ for p in env['MYPATH']:
+ results.append(top_dir + os.sep + p)
+ return results
+
+scanner = Scanner(name = 'myscanner',
+ function = my_scan,
+ argument = None,
+ skeys = ['.x'],
+ path_function = pf,
+ )
+.EE
+
.SS Creating a Hierarchical Build
Notice that the file names specified in a subdirectory's
projects / scons.git / blobdiff