.fi
.RE
..
-.TH SCONS 1 "August 2004"
+.TH SCONS 1 "__MONTH_YEAR__"
.SH NAME
scons \- a software construction tool
.SH SYNOPSIS
env = Environment(ENV = {'PATH' : os.environ['PATH']})
.EE
+Similarly, if the commands use external environment variables
+like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
+these variables can also be explicitly propagated:
+
+.ES
+import os
+env = Environment(ENV = {'PATH' : os.environ['PATH'],
+ 'HOME' : os.environ['HOME']})
+.EE
+
+Or you may explicitly propagate the invoking user's
+complete external environment:
+
+.ES
+import os
+env = Environment(ENV = os.environ['PATH'])
+.EE
+
+This comes at the expense of making your build
+dependent on the user's environment being set correctly,
+but it may be more convenient for many configurations.
+
.B scons
can scan known input files automatically for dependency
information (for example, #include statements
to remove target files under build and export.
Additional files or directories to remove can be specified using the
-Clean() function.
+.BR Clean()
+function.
+Conversely, targets that would normally be removed by the
+.B -c
+invocation
+can be prevented from being removed by using the
+.BR NoClean ()
+function.
A subset of a hierarchical tree may be built by
remaining at the top-level directory (where the
.B scons
knows how to search for available programming tools
on various systems.
-On WIN32 systems,
+On Windows systems,
.B scons
searches in order for the
Microsoft Visual C++ tools,
Clean up by removing all target files for which a construction
command is specified.
Also remove any files or directories associated to the construction command
-using the Clean() function.
+using the
+.BR Clean ()
+function.
+Will not remove any targets specified by the
+.BR NoClean ()
+function.
+
+.TP
+.RI --cache-debug= file
+Print debug information about the
+.BR CacheDir ()
+derived-file caching
+to the specified
+.IR file .
+If
+.I file
+is
+.B \-
+(a hyphen),
+the debug information are printed to the standard output.
+The printed messages describe what signature file names are
+being looked for in, retrieved from, or written to the
+.BR CacheDir ()
+directory tree.
.TP
--cache-disable, --no-cache
regardless of whether a target
file was rebuilt or retrieved from the cache.
+.TP
+.RI --config= mode
+This specifies how the
+.B Configure
+call should use or generate the
+results of configuration tests.
+The option should be specified from
+among the following choices:
+
+.TP
+--config=auto
+scons will use its normal dependency mechanisms
+to decide if a test must be rebuilt or not.
+This saves time by not running the same configuration tests
+every time you invoke scons,
+but will overlook changes in system header files
+or external commands (such as compilers)
+if you don't specify those dependecies explicitly.
+This is the default behavior.
+
+.TP
+--config=force
+If this option is specified,
+all configuration tests will be re-run
+regardless of whether the
+cached results are out of date.
+This can be used to explicitly
+force the configuration tests to be updated
+in response to an otherwise unconfigured change
+in a system header file or compiler.
+
+.TP
+--config=cache
+If this option is specified,
+no configuration tests will be rerun
+and all results will be taken from cache.
+Note that scons will still consider it an error
+if --config=cache is specified
+and a necessary test does not
+yet have any results in the cache.
+
.TP
.RI "-C" " directory" ", --directory=" directory
Change to the specified
.TP
--debug=count
-Print a count of how many objects are created
-of the various classes used internally by SCons.
+Print how many objects are created
+of the various classes used internally by SCons
+before and after reading the SConscript files
+and before and after building targets.
This only works when run under Python 2.1 or later.
.TP
Print the dependency tree
after each top-level target is built. This prints out only derived files.
+.TP
+--debug=explain
+Print an explanation of precisely why
+.B scons
+is deciding to (re-)build any targets.
+(Note: this does not print anything
+for targets that are
+.I not
+rebuilt.)
+
+.TP
+--debug=findlibs
+Instruct the scanner that searches for libraries
+to print a message about each potential library
+name it is searching for,
+and about the actual libraries it finds.
+
.TP
--debug=includes
Print the include tree after each top-level target is built.
$ scons --debug=includes foo.o
.EE
+.TP
+--debug=memoizer
+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
Prints how much memory SCons uses
before and after reading the SConscript files
-and before and after building.
+and before and after building targets.
+
+.TP
+--debug=nomemoizer
+A deprecated option preserved for backwards compatibility.
.TP
--debug=objects
Re-run SCons under the control of the
.RI pdb
Python debugger.
-.EE
.TP
--debug=presub
.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
+.TP
+--debug=stacktrace
+Prints an internal Python stack trace
+when encountering an otherwise unexplained error.
+
+.TP
+--debug=stree
+Print the dependency tree along with status information. This is the
+same as the debug=tree option, but additional status information is
+provided for each node in the tree.
+
.TP
--debug=time
Prints various time profiling information: the time spent
dependency tree including implicit dependencies and ignored
dependencies.
+.TP
+.RI --diskcheck= types
+Enable specific checks for
+whether or not there is a file on disk
+where the SCons configuration expects a directory
+(or vice versa),
+and whether or not RCS or SCCS sources exist
+when searching for source and include files.
+The
+.I types
+argument can be set to:
+.BR all ,
+to enable all checks explicitly
+(the default behavior);
+.BR none ,
+to disable all such checks;
+.BR match ,
+to check that files and directories on disk
+match SCons' expected configuration;
+.BR rcs ,
+to check for the existence of an RCS source
+for any missing source or include files;
+.BR sccs ,
+to check for the existence of an SCCS source
+for any missing source or include files.
+Multiple checks can be specified separated by commas;
+for example,
+.B --diskcheck=sccs,rcs
+would still check for SCCS and RCS sources,
+but disable the check for on-disk matches of files and directories.
+Disabling some or all of these checks
+can provide a performance boost for large configurations,
+or when the configuration will check for files and/or directories
+across networked or shared file systems,
+at the slight increased risk of an incorrect build
+or of not handling errors gracefully
+(if include files really should be
+found in SCCS or RCS, for example,
+or if a file really does exist
+where the SCons configuration expects a directory).
+
.\" .TP
.\" -e, --environment-overrides
.\" Variables from the execution environment override construction
.RI --max-drift= SECONDS
Set the maximum expected drift in the modification time of files to
.IR SECONDS .
-This value determines how old a file must be before its content signature
-is cached. The default value is 2 days, which means a file must have a
-modification time of at least two days ago in order to have its content
-signature cached. A negative value means to never cache the content
+This value determines how long a file must be unmodified
+before its cached content signature
+will be used instead of
+calculating a new content signature (MD5 checksum)
+of the file's contents.
+The default value is 2 days, which means a file must have a
+modification time of at least two days ago in order to have its
+cached content signature used.
+A negative value means to never cache the content
signature and to ignore the cached value if there already is one. A value
-of 0 means to always cache the signature, no matter how old the file is.
+of 0 means to always use the cached signature,
+no matter how old the file is.
.TP
-n, --just-print, --dry-run, --recon
.IR file .
The results may be analyzed using the Python
pstats module.
+
.TP
-q, --question
Do not run any commands, or print anything. Just return an exit
Ignored for compatibility with GNU
.BR make .
-.TP
-.RI --save-explain-info= 0|1
-By default,
-scons will save additional information about the build
-that is used by the
-.B --debug=explain
-option.
-Setting
-.B --save-explain-info=0
-will tell scons to speed up the build
-by not saving this information.
-
.TP
-t, --touch
Ignored for compatibility with GNU
appear up-to-date is unnecessary when using
.BR scons .)
+.TP
+.RI --taskmastertrace= file
+Prints trace information to the specified
+.I file
+about how the internal Taskmaster object
+evaluates and controls the order in which Nodes are built.
+A file name of
+.B -
+may be used to specify the standard output.
+
.TP
-u, --up, --search-up
Walks up the directory structure until an
Note that the
.B win32
platform adds the
+.B SYSTEMDRIVE
+and
.B SYSTEMROOT
-variable from the user's external environment
+variables from the user's external environment
to the construction environment's
.B ENV
dictionary.
(such as fetching source files from
external CVS repository specifications like
.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Win32 systems.
+will work on Windows systems.
The platform argument may be function or callable object,
in which case the Environment() method
Non-built-in tools may be specified using the toolpath argument:
.ES
-env = Environment(tools = ['foo'], toolpath = ['tools'])
+env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
.EE
-This looks for a tool specification in tools/foo.py. foo.py should
-have two functions: generate(env) and exists(env). generate()
-modifies the passed in environment and exists() should return a true
-value if the tool is available. Tools in the toolpath are used before
+This looks for a tool specification in tools/foo.py (as well as
+using the ordinary default tools for the platform). foo.py should
+have two functions: generate(env, **kw) and exists(env).
+The
+.B generate()
+function
+modifies the passed-in environment
+to set up variables so that the tool
+can be executed;
+it may use any keyword arguments
+that the user supplies (see below)
+to vary its initialization.
+The
+.B exists()
+function should return a true
+value if the tool is available.
+Tools in the toolpath are used before
any of the built-in ones. For example, adding gcc.py to the toolpath
would override the built-in gcc tool.
+Also note that the toolpath is
+stored in the environment for use
+by later calls to
+.BR Clone ()
+and
+.BR Tool ()
+methods:
+
+.ES
+base = Environment(toolpath=['custom_path'])
+derived = base.Clone(tools=['custom_tool'])
+derived.CustomBuilder()
+.EE
The elements of the tools list may also
be functions or callable objects,
env = Environment(tools = [my_tool])
.EE
+The individual elements of the tools list
+may also themselves be two-element lists of the form
+.RI ( toolname ", " kw_dict ).
+SCons searches for the
+.I toolname
+specification file as described above, and
+passes
+.IR kw_dict ,
+which must be a dictionary, as keyword arguments to the tool's
+.B generate
+function.
+The
+.B generate
+function can use the arguments to modify the tool's behavior
+by setting up the environment in different ways
+or otherwise changing its initialization.
+
+.ES
+# in tools/my_tool.py:
+def generate(env, **kw):
+ # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
+ env['MY_TOOL'] = kw.get('arg1', '1')
+def exists(env):
+ return 1
+
+# in SConstruct:
+env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
+ toolpath=['tools'])
+.EE
+
The tool definition (i.e. my_tool()) can use the PLATFORM variable from
the environment it receives to customize the tool for different platforms.
ifort
ilink
ilink32
+intelc
jar
javac
javah
mslink
msvc
msvs
+mwcc
+mwld
nasm
pdflatex
pdftex
qt
rmic
+rpcgen
sgiar
sgic++
sgicc
On posix and cygwin platforms
the GNU tools (e.g. gcc) are preferred by SCons,
-on win32 the Microsoft tools (e.g. msvc)
+on Windows the Microsoft tools (e.g. msvc)
followed by MinGW are preferred by SCons,
and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
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.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
.EE
-or generate a shared library with a nonstandard suffix:
+or generate a shared library with a non-standard suffix:
.ES
-env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
+env.SharedLibrary('word', 'word.cpp',
+ SHLIBSUFFIX='.ocx',
+ LIBSUFFIXES=['.ocx'])
.EE
+(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
+if you want SCons to search automatically
+for dependencies on the non-standard library names;
+see the descriptions of these variables, below, for more information.)
+
Although the builder methods defined by
.B scons
are, in fact,
.B scons
has determined are appropriate for the local system.
+Builder methods that can be called without an explicit
+environment may be called from custom Python modules that you
+import into an SConscript file by adding the following
+to the Python module:
+
+.ES
+from SCons.Script import *
+.EE
+
All builder methods return a list of Nodes
that represent the target or targets that will be built.
A
flag when compiling one specific object file:
.ES
-bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
+bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
.EE
function:
.ES
-bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
+bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
print "The path to bar_obj is:", str(bar_obj_list[0])
.EE
to get at the Node that actually represents
the object file.
-.B scons
-provides the following builder methods:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CFile()
-.IP env.CFile()
-Builds a C source file given a lex (.l) or yacc (.y) input file.
-The suffix specified by the $CFILESUFFIX construction variable
-(.c by default)
-is automatically added to the target
-if it is not already present. Example:
-
-.ES
-# builds foo.c
-env.CFile(target = 'foo.c', source = 'foo.l')
-# builds bar.c
-env.CFile(target = 'bar', source = 'bar.y')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CXXFile()
-.IP env.CXXFile()
-Builds a C++ source file given a lex (.ll) or yacc (.yy)
-input file.
-The suffix specified by the $CXXFILESUFFIX construction variable
-(.cc by default)
-is automatically added to the target
-if it is not already present. Example:
+Builder calls support a
+.B chdir
+keyword argument that
+specifies that the Builder's action(s)
+should be executed
+after changing directory.
+If the
+.B chdir
+argument is
+a string or a directory Node,
+scons will change to the specified directory.
+If the
+.B chdir
+is not a string or Node
+and is non-zero,
+then scons will change to the
+target file's directory.
.ES
-# builds foo.cc
-env.CXXFile(target = 'foo.cc', source = 'foo.ll')
-# builds bar.cc
-env.CXXFile(target = 'bar', source = 'bar.yy')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP DVI()
-.IP env.DVI()
-Builds a .dvi file from a .tex, .ltx or .latex input file.
-If the source file suffix is .tex,
-.B scons
-will examine the contents of the file;
-if the string
-.B \\documentclass
-or
-.B \\documentstyle
-is found, the file is assumed to be a LaTeX file and
-the target is built by invoking the $LATEXCOM command line;
-otherwise, the $TEXCOM command line is used.
-If the file is a LaTeX file,
-the
-.B DVI
-builder method will also examine the contents
-of the
-.B .aux file
-and invoke the $BIBTEX command line
-if the string
-.B bibdata
-is found,
-and will examine the contents
-.B .log
-file and re-run the $LATEXCOM command
-if the log file says it is necessary.
-
-The suffix .dvi
-(hard-coded within TeX itself)
-is automatically added to the target
-if it is not already present. Examples:
-
-.ES
-# builds from aaa.tex
-env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
-# builds bbb.dvi
-env.DVI(target = 'bbb', source = 'bbb.ltx')
-# builds from ccc.latex
-env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Jar()
-.IP env.Jar()
-Builds a Java archive (.jar) file
-from a source tree of .class files.
-If the $JARCHDIR value is set, the
-.B jar
-command will change to the specified directory using the
-.B \-C
-option.
-If the contents any of the source files begin with the string
-.BR Manifest-Version ,
-the file is assumed to be a manifest
-and is passed to the
-.B jar
-command with the
-.B m
-option set.
+# scons will change to the "sub" subdirectory
+# before executing the "cp" command.
+env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
+ "cp dir/foo.in dir/foo.out",
+ chdir='sub')
-.ES
-env.Jar(target = 'foo.jar', source = 'classes')
+# Because chdir is not a string, scons will change to the
+# target's directory ("sub/dir") before executing the
+# "cp" command.
+env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
+ "cp foo.in foo.out",
+ chdir=1)
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Java()
-.IP env.Java()
-Builds one or more Java class files
-from one or more source trees of .java files.
-The class files will be placed underneath
-the specified target directory.
-SCons will parse each source .java file
-to find the classes
-(including inner classes)
-defined within that file,
-and from that figure out the
-target .class files that will be created.
-SCons will also search each Java file
-for the Java package name,
-which it assumes can be found on a line
-beginning with the string
-.B package
-in the first column;
-the resulting .class files
-will be placed in a directory reflecting
-the specified package name.
-For example,
-the file
-.I Foo.java
-defining a single public
-.I Foo
-class and
-containing a package name of
-.I sub.dir
-will generate a corresponding
-.IR sub/dir/Foo.class
-class file.
-
-Example:
+Note that scons will
+.I not
+automatically modify
+its expansion of
+construction variables like
+.B $TARGET
+and
+.B $SOURCE
+when using the chdir
+keyword argument--that is,
+the expanded file names
+will still be relative to
+the top-level SConstruct directory,
+and consequently incorrect
+relative to the chdir directory.
+If you use the chdir keyword argument,
+you will typically need to supply a different
+command line using
+expansions like
+.B ${TARGET.file}
+and
+.B ${SOURCE.file}
+to use just the filename portion of the
+targets and source.
-.ES
-env.Java(target = 'classes', source = 'src')
-env.Java(target = 'classes', source = ['src1', 'src2'])
-.EE
+.B scons
+provides the following builder methods:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP JavaH()
-.IP env.JavaH()
-Builds C header and source files for
-implementing Java native methods.
-The target can be either a directory
-in which the header files will be written,
-or a header file name which
-will contain all of the definitions.
-The source can be either the names of .class files,
-or the objects returned from the
-.B Java
-builder method.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B JavaH
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class file names.
-
-Examples:
-
-.ES
-# builds java_native.h
-classes = env.Java(target = 'classdir', source = 'src')
-env.JavaH(target = 'java_native.h', source = classes)
-
-# builds include/package_foo.h and include/package_bar.h
-env.JavaH(target = 'include',
- source = ['package/foo.class', 'package/bar.class'])
-
-# builds export/foo.h and export/bar.h
-env.JavaH(target = 'export',
- source = ['classes/foo.class', 'classes/bar.class'],
- JAVACLASSDIR = 'classes')
-.EE
-
+'\" BEGIN GENERATED BUILDER DESCRIPTIONS
+'\"
+'\" The descriptions below of the various SCons Builders 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.
+'\"
+'\" BEGIN GENERATED BUILDER DESCRIPTIONS
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Library()
-.IP env.Library()
-A synonym for the
-.B StaticLibrary
-builder method.
-
+.so builders.man
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP M4()
-.IP env.M4()
-Builds an output file from an M4 input file.
-This uses a default $M4FLAGS value of
-.BR -E ,
-which considers all warnings to be fatal
-and stops on the first warning
-when using the GNU version of m4.
-Example:
-
-.ES
-env.M4(target = 'foo.c', source = 'foo.c.m4')
-.EE
-
+'\" END GENERATED BUILDER DESCRIPTIONS
+'\"
+'\" The descriptions above of the various SCons Builders 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 BUILDER DESCRIPTIONS
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Moc()
-.IP env.Moc()
-Builds an output file from a moc input file. Moc input files are either
-header files or cxx files. This builder is only available after using the
-tool 'qt'. See the QTDIR variable for more information.
-Example:
-.ES
-env.Moc('foo.h') # generates moc_foo.cc
-env.Moc('foo.cpp') # generates foo.moc
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP MSVSProject()
-.IP env.MSVSProject()
-Builds Microsoft Visual Studio project files.
-This builds a Visual Studio project file, based on the version of
-Visual Studio that is configured (either the latest installed version,
-or the version set by
-.B MSVS_VERSION
-in the Environment constructor).
-For VS 6, it will generate
-.B .dsp
-and
-.B .dsw
-files, for VS 7, it will
-generate
-.B .vcproj
-and
-.B .sln
-files.
+All
+targets of builder methods automatically depend on their sources.
+An explicit dependency can
+be specified using the
+.B Depends
+method of a construction environment (see below).
-It takes several lists of filenames to be placed into the project
-file, currently these are limited to
-.B srcs, incs, localincs, resources,
+In addition,
+.B scons
+automatically scans
+source files for various programming languages,
+so the dependencies do not need to be specified explicitly.
+By default, SCons can
+C source files,
+C++ source files,
+Fortran source files with
+.B .F
+(POSIX systems only),
+.B .fpp,
+or
+.B .FPP
+file extensions,
+and assembly language files with
+.B .S
+(POSIX systems only),
+.B .spp,
+or
+.B .SPP
+files extensions
+for C preprocessor dependencies.
+SCons also has default support
+for scanning D source files,
+You can also write your own Scanners
+to add support for additional source file types.
+These can be added to the default
+Scanner object used by
+the
+.BR Object ()
+.BR StaticObject ()
and
-.B misc.
-These are pretty self explanatory, but it
-should be noted that the 'srcs' list is NOT added to the $SOURCES
-environment variable. This is because it represents a list of files
-to be added to the project file, not the source used to build the
-project file (in this case, the 'source' is the SConscript file used
-to call MSVSProject).
-
-In addition to these values (which are all optional, although not
-specifying any of them results in an empty project file), the
-following values must be specified:
-
-target: The name of the target .dsp or .vcproj file. The correct
-suffix for the version of Visual Studio must be used, but the value
-
-env['MSVSPROJECTSUFFIX']
+.BR SharedObject ()
+Builders by adding them
+to the
+.B SourceFileScanner
+object as follows:
-will be defined to the correct value (see example below).
-
-variant: The name of this particular variant. These are typically
-things like "Debug" or "Release", but really can be anything you want.
-Multiple calls to MSVSProject with different variants are allowed: all
-variants will be added to the project file with their appropriate
-build targets and sources.
-
-buildtarget: A list of SCons.Node.FS objects which is returned from
-the command which builds the target. This is used to tell SCons what
-to build when the 'build' button is pressed inside of the IDE.
+See the section "Scanner Objects,"
+below, for a more information about
+defining your own Scanner objects.
-Example Usage:
+.SS Methods and Functions to Do Things
+In addition to Builder methods,
+.B scons
+provides a number of other construction environment methods
+and global functions to
+manipulate the build configuration.
+Usually, a construction environment method
+and global function with the same name both exist
+so that you don't have to remember whether
+to a specific bit of functionality
+must be called with or without a construction environment.
+In the following list,
+if you call something as a global function
+it looks like:
.ES
- barsrcs = ['bar.cpp'],
- barincs = ['bar.h'],
- barlocalincs = ['StdAfx.h']
- barresources = ['bar.rc','resource.h']
- barmisc = ['bar_readme.txt']
-
- dll = local.SharedLibrary(target = 'bar.dll',
- source = barsrcs)
-
- local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
- srcs = barsrcs,
- incs = barincs,
- localincs = barlocalincs,
- resources = barresources,
- misc = barmisc,
- buildtarget = dll,
- variant = 'Release')
+.RI Function( arguments )
.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Object()
-.IP env.Object()
-A synonym for the
-.B StaticObject
-builder method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PCH()
-.IP env.PCH()
-Builds a Microsoft Visual C++ precompiled header.
-Calling this builder method
-returns a list of two targets: the PCH as the first element, and the object
-file as the second element. Normally the object file is ignored.
-This builder method is only
-provided when Microsoft Visual C++ is being used as the compiler.
-The PCH builder method is generally used in
-conjuction with the PCH construction variable to force object files to use
-the precompiled header:
-
+and if you call something through a construction
+environment it looks like:
.ES
-env['PCH'] = env.PCH('StdAfx.cpp')[0]
+.RI env.Function( arguments )
.EE
+If you can call the functionality in both ways,
+then both forms are listed.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PDF()
-.IP env.PDF()
-Builds a .pdf file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PDFSUFFIX construction variable
-(.pdf by default)
-is added automatically to the target
-if it is not already present. Example:
+Global functions may be called from custom Python modules that you
+import into an SConscript file by adding the following
+to the Python module:
.ES
-# builds from aaa.tex
-env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
-# builds bbb.pdf from bbb.dvi
-env.PDF(target = 'bbb', source = 'bbb.dvi')
+from SCons.Script import *
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PostScript()
-.IP env.PostScript()
-Builds a .ps file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PSSUFFIX construction variable
-(.ps by default)
-is added automatically to the target
-if it is not already present. Example:
-
+Except where otherwise noted,
+the same-named
+construction environment method
+and global function
+provide the exact same functionality.
+The only difference is that,
+where appropriate,
+calling the functionality through a construction environment will
+substitute construction variables into
+any supplied strings.
+For example:
.ES
-# builds from aaa.tex
-env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
-# builds bbb.ps from bbb.dvi
-env.PostScript(target = 'bbb', source = 'bbb.dvi')
+env = Environment(FOO = 'foo')
+Default('$FOO')
+env.Default('$FOO')
.EE
+the first call to the global
+.B Default()
+function will actually add a target named
+.B $FOO
+to the list of default targets,
+while the second call to the
+.B env.Default()
+construction environment method
+will expand the value
+and add a target named
+.B foo
+to the list of default targets.
+For more on construction variable expansion,
+see the next section on
+construction variables.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Program()
-.IP env.Program()
-Builds an executable given one or more object files
-or C, C++, D, or Fortran source files.
-If any C, C++, D or Fortran source files are specified,
-then they will be automatically
-compiled to object files using the
-.B Object
-builder method;
-see that builder method's description for
-a list of legal source file suffixes
-and how they are interpreted.
-The target executable file prefix
-(specified by the $PROGPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $PROGSUFFIX construction variable;
-by default, .exe on Windows systems, nothing on POSIX systems)
-are automatically added to the target if not already present.
-Example:
-
-.ES
-env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
-.EE
+Construction environment methods
+and global functions supported by
+.B scons
+include:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RES()
-.IP env.RES()
-Builds a Microsoft Visual C++ resource file.
-This builder method is only provided
-when Microsoft Visual C++ or MinGW is being used as the compiler. The
-.I .res
-(or
-.I .o
-for MinGW) suffix is added to the target name if no other suffix is given. The source
-file is scanned for implicit dependencies as though it were a C file. Example:
+.TP
+.RI Action( action ", [" strfunction ", " varlist ])
+.TP
+.RI env.Action( action ", [" strfunction ", " varlist ])
+Creates an Action object for
+the specified
+.IR action .
+See the section "Action Objects,"
+below, for a complete explanation of the arguments and behavior.
-.ES
-env.RES('resource.rc')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RMIC()
-.IP env.RMIC()
-Builds stub and skeleton class files
-for remote objects
-from Java .class files.
-The target is a directory
-relative to which the stub
-and skeleton class files will be written.
-The source can be the names of .class files,
-or the objects return from the
-.B Java
-builder method.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B RMIC
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class file names.
-
-.ES
-classes = env.Java(target = 'classdir', source = 'src')
-env.RMIC(target = 'outdir1', source = classes)
-
-env.RMIC(target = 'outdir2',
- source = ['package/foo.class', 'package/bar.class'])
-
-env.RMIC(target = 'outdir3',
- source = ['classes/foo.class', 'classes/bar.class'],
- JAVACLASSDIR = 'classes')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP SharedLibrary()
-.IP env.SharedLibrary()
-Builds a shared library
-(.so on a POSIX system, .dll on WIN32)
-given one or more object files
-or C, C++, D or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the $SHLIBPREFIX construction variable;
-by default, lib on POSIX systems, nothing on Windows systems)
-and suffix
-(specified by the $SHLIBSUFFIX construction variable;
-by default, .dll on Windows systems, .so on POSIX systems)
-are automatically added to the target if not already present.
-Example:
-
-.ES
-env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-.EE
-.IP
-On WIN32 systems, the
-.B SharedLibrary
-builder method will always build an import (.lib) library
-in addition to the shared (.dll) library,
-adding a .lib library with the same basename
-if there is not already a .lib file explicitly
-listed in the targets.
-
-Any object files listed in the
-.B source
-must have been built for a shared library
-(that is, using the
-.B SharedObject
-builder method).
-.B scons
-will raise an error if there is any mismatch.
-.IP
-On WIN32 systems, specifying "register=1" will cause the dll to be
-registered after it is built using REGSVR32. The command that is run
-("regsvr32" by default) is determined by $REGSVR construction
-variable, and the flags passed are determined by $REGSVRFLAGS. By
-default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
-up and requiring user attention when it is run. If you change
-$REGSVRFLAGS, be sure to include "/s". For example,
-
-.ES
-env.SharedLibrary(target = 'bar',
- source = ['bar.cxx', 'foo.obj'],
- register=1)
-.EE
-
-.IP
-will register "bar.dll" as a COM object when it is done linking it.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP SharedObject()
-.IP env.SharedObject()
-Builds an object file for
-inclusion in a shared library.
-Source files must have one of the same set of extensions
-specified above for the
-.B StaticObject
-builder method.
-On some platforms building a shared object requires additional
-compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
-The target object file prefix
-(specified by the $SHOBJPREFIX construction variable;
-by default, the same as $OBJPREFIX)
-and suffix
-(specified by the $SHOBJSUFFIX construction variable)
-are automatically added to the target if not already present.
-Examples:
-
-.ES
-env.SharedObject(target = 'ddd', source = 'ddd.c')
-env.SharedObject(target = 'eee.o', source = 'eee.cpp')
-env.SharedObject(target = 'fff.obj', source = 'fff.for')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP StaticLibrary()
-.IP env.StaticLibrary()
-Builds a static library given one or more object files
-or C, C++, D or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the $LIBPREFIX construction variable;
-by default, lib on POSIX systems, nothing on Windows systems)
-and suffix
-(specified by the $LIBSUFFIX construction variable;
-by default, .lib on Windows systems, .a on POSIX systems)
-are automatically added to the target if not already present.
-Example:
-
-.ES
-env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-.EE
-
-.IP
-Any object files listed in the
-.B source
-must have been built for a static library
-(that is, using the
-.B StaticObject
-builder method).
-.B scons
-will raise an error if there is any mismatch.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP StaticObject()
-.IP env.StaticObject()
-Builds a static object file
-from one or more C, C++, D, or Fortran source files.
-Source files must have one of the following extensions:
-
-.ES
- .asm assembly language file
- .ASM assembly language file
- .c C file
- .C WIN32: C file
- POSIX: C++ file
- .cc C++ file
- .cpp C++ file
- .cxx C++ file
- .cxx C++ file
- .c++ C++ file
- .C++ C++ file
- .d D file
- .f Fortran file
- .F WIN32: Fortran file
- POSIX: Fortran file + C pre-processor
- .for Fortran file
- .FOR Fortran file
- .fpp Fortran file + C pre-processor
- .FPP Fortran file + C pre-processor
- .s assembly language file
- .S WIN32: assembly language file
- POSIX: assembly language file + C pre-processor
- .spp assembly language file + C pre-processor
- .SPP assembly language file + C pre-processor
-.EE
-.IP
-The target object file prefix
-(specified by the $OBJPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $OBJSUFFIX construction variable;
-\.obj on Windows systems, .o on POSIX systems)
-are automatically added to the target if not already present.
-Examples:
-
-.ES
-env.StaticObject(target = 'aaa', source = 'aaa.c')
-env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
-env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Tar()
-.IP env.Tar()
-Builds a tar archive of the specified files
-and/or directories.
-Unlike most builder methods,
-the
-.B Tar
-builder method may be called multiple times
-for a given target;
-each additional call
-adds to the list of entries
-that will be built into the archive.
-
-.ES
-env.Tar('src.tar', 'src')
-
-# Create the stuff.tar file.
-env.Tar('stuff', ['subdir1', 'subdir2'])
-# Also add "another" to the stuff.tar file.
-env.Tar('stuff', 'another')
-
-# Set TARFLAGS to create a gzip-filtered archive.
-env = Environment(TARFLAGS = '-c -z')
-env.Tar('foo.tar.gz', 'foo')
-
-# Also set the suffix to .tgz.
-env = Environment(TARFLAGS = '-c -z',
- TARSUFFIX = '.tgz')
-env.Tar('foo')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP TypeLibrary()
-.IP env.TypeLibrary()
-Builds a Windows type library (.tlb) file from and input IDL file
-(.idl). In addition, it will build the associated inteface stub and
-proxy source files. It names them according to the base name of the .idl file.
-.IP
-For example,
-
-.ES
-env.TypeLibrary(source="foo.idl")
-.EE
-.IP
-Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Uic()
-.IP env.Uic()
-Builds a header file, an implementation file and a moc file from an ui file.
-and returns the corresponding nodes in the above order.
-This builder is only available after using the tool 'qt'. Note: you can
-specify .ui files directly as inputs for Program, Library and SharedLibrary
-without using this builder. Using the builder lets you override the standard
-naming conventions (be careful: prefixes are always prepended to names of
-built files; if you don't want prefixes, you may set them to ``).
-See the QTDIR variable for more information.
-Example:
-
-.ES
-env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
-env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
- source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Zip()
-.IP env.Zip()
-Builds a zip archive of the specified files
-and/or directories.
-Unlike most builder methods,
-the
-.B Zip
-builder method may be called multiple times
-for a given target;
-each additional call
-adds to the list of entries
-that will be built into the archive.
-
-.ES
-env.Zip('src.zip', 'src')
-
-# Create the stuff.zip file.
-env.Zip('stuff', ['subdir1', 'subdir2'])
-# Also add "another" to the stuff.tar file.
-env.Zip('stuff', 'another')
-.EE
-
-.B scons
-automatically scans
-C source files, C++ source files,
-Fortran source files with
-.B .F
-(POSIX systems only),
-.B .fpp,
-or
-.B .FPP
-file extensions,
-and assembly language files with
-.B .S
-(POSIX systems only),
-.B .spp,
-or
-.B .SPP
-files extensions
-for C preprocessor dependencies,
-so the dependencies do not need to be specified explicitly.
-In addition, all
-targets of builder methods automatically depend on their sources.
-An explicit dependency can
-be specified using the
-.B Depends
-method of a construction environment (see below).
-
-.SS Methods and Functions to Do Things
-In addition to Builder methods,
-.B scons
-provides a number of other construction environment methods
-and global functions to
-manipulate the build configuration.
-
-Usually, a construction environment method
-and global function with the same name both exist
-so that you don't have to remember whether
-to a specific bit of functionality
-must be called with or without a construction environment.
-In the following list,
-if you call something as a global function
-it looks like:
-.ES
-.RI Function( arguments )
-.EE
-and if you call something through a construction
-environment it looks like:
-.ES
-.RI env.Function( arguments )
-.EE
-If you can call the functionality in both ways,
-then both forms are listed.
-
-Except where otherwise noted,
-the same-named
-construction environment method
-and global function
-provide the exact same functionality.
-The only difference is that,
-where appropriate,
-calling the functionality through a construction environment will
-substitute construction variables into
-any supplied strings.
-For example:
-.ES
-env = Environment(FOO = 'foo')
-Default('$FOO')
-env.Default('$FOO')
-.EE
-the first call to the global
-.B Default()
-function will actually add a target named
-.B $FOO
-to the list of default targets,
-while the second call to the
-.B env.Default()
-construction environment method
-will expand the value
-and add a target named
-.B foo
-to the list of default targets.
-For more on construction variable expansion,
-see the next section on
-construction variables.
-
-Construction environment methods
-and global functions supported by
-.B scons
-include:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Action( action ", [" strfunction ", " varlist ])
-.TP
-.RI env.Action( action ", [" strfunction ", " varlist ])
-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 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.Action ()
+was called.
+The
+.BR Action ()
+form delays all variable expansion
+until the Action object is actually used.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Alias( alias ", [" targets ])
+.RI Alias( alias ", [" targets ", [" action ]])
.TP
-.RI env.Alias( alias ", [" targets ])
+.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,
including another alias.
.B Alias
can be called multiple times for the same
-alias to add additional targets to the alias.
+alias to add additional targets to the alias,
+or additional actions to the list for this alias.
.ES
Alias('install')
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
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.ES
print 'before:',env['ENV']['INCLUDE']
include_path = '/foo/bar:/foo'
-env.PrependENVPath('INCLUDE', include_path)
+env.AppendENVPath('INCLUDE', include_path)
print 'after:',env['ENV']['INCLUDE']
yields:
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 )
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'))
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Command( target ", " source ", " commands ", [" key = val ", ...])"
+.RI Command( target ", " source ", " action ", [" key = val ", ...])"
.TP
-.RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
+.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.
-Any keyword arguments specified override any
+
+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.
-Note that an action can be an external command,
+An action can be an external command,
specified as a string,
or a callable Python object;
-see "Action Objects," below.
+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
rename ])
.EE
+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:
+
+.ES
+env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
+
+env['DISTDIR'] = 'destination/directory'
+env.Command(env.Dir('$DISTDIR')), None, make_distdir)
+.EE
+
+(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 ])
+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
+.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,"
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Copy([ key = val ", ...])"
+.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,
for the keywords.
.ES
-env2 = env.Copy()
-env3 = env.Copy(CCFLAGS = '-g')
+env2 = env.Clone()
+env3 = env.Clone(CCFLAGS = '-g')
.EE
.IP
Additionally, a list of tools and a toolpath may be specified, as in
.ES
def MyTool(env): env['FOO'] = 'bar'
-env4 = env.Copy(tools = ['msvc', MyTool])
+env4 = env.Clone(tools = ['msvc', MyTool])
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.Copy([ key = val ", ...])"
+A synonym for
+env.Clone().
+(This will probably be officially deprecated some day.)
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI env.CVS( repository ", " module )
.RI Dir( name ", [" directory ])
.TP
.RI env.Dir( name ", [" directory ])
-This returns an object that represents a given 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.
+
+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
+will print:
+.ES
+'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
+.EE
+
+.ES
+env=Environment()
+print env.Dump()
+.EE
+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
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI EnsureSConsVersion( major ", " minor )
+.RI EnsureSConsVersion( major ", " minor ", [" revision ])
.TP
-.RI env.EnsureSConsVersion( major ", " minor )
+.RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
Ensure that the SCons version is at least
-.IR major . minor .
+.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.
.ES
-EnsureSConsVersion(0,9)
+EnsureSConsVersion(0,14)
+
+EnsureSConsVersion(0,96,90)
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.RI File( name ", [" directory ])
.TP
.RI env.File( name ", [" directory ])
-This returns an object that represents a given file
+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.
+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 )
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 )
.B -h
argument is given to
.BR scons .
-.B scons
-will exit after printing out the help text.
+If
+.BR Help
+is called multiple times, the text is appended together in the order
+that
+.BR Help
+is called.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Install( dir ", " source )
.TP
.RI env.Install( dir ", " source )
-Installs one or more files in a destination directory.
-The file names remain the same.
+Installs one or more source files or directories
+in a destination directory
+.IR dir .
+The names of the specified source files or directories
+remain the same within the destination directory.
.ES
env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
.RI InstallAs( target ", " source )
.TP
.RI env.InstallAs( target ", " source )
-Installs one or more files as specific file names,
-allowing changing a file name as part of the
-installation.
-It is an error if the target and source
-list different numbers of files.
+Installs one or more source files or directories
+to specific names,
+allowing changing a file or directory name
+as part of the installation.
+It is an error if the
+.I target
+and
+.I source
+arguments list different numbers of files or directories.
.ES
env.InstallAs(target = '/usr/local/bin/foo',
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.ParseConfig( command ", [" function ])
-Calls the specified
-.I function
-to modify the environment as specified by the output of
+.RI env.MergeFlags( arg ", [" unique ])
+Merges the specified
+.I arg
+values to the construction envrionment'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'])
+
+env.MergeFlags(['-O3',
+ '!pkg-config gtk+-2.0 --cflags --libs',
+ '!pkg-config libpng12 --cflags --libs'])
+.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
-expects the output of a typical
+is
+.BR env.MergeFlags (),
+which expects the output of a typical
.I *-config command
(for example,
.BR gtk-config )
-and parses the returned
-.BR -L ,
-.BR -l ,
-.BR -Wa ,
-.BR -Wl ,
-.BR -Wp ,
-.B -I
-and other options
-into the
-.BR LIBPATH ,
-.BR LIBS ,
-.BR ASFLAGS ,
-.BR LINKFLAGS ,
-.BR CPPFLAGS ,
-.B CPPPATH
-and
-.B CCFLAGS
-variables,
-respectively.
+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 thie method calls).
+See that method's description, below,
+for a table of options and construction variables.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI ParseDepends( filename ", [" must_exist ])
+.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_exit
+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
+
+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
Note that the
.B win32
platform adds the
+.B SYSTEMDRIVE
+and
.B SYSTEMROOT
-variable from the user's external environment
+variables from the user's external environment
to the construction environment's
.B ENV
dictionary.
(such as fetching source files from
external CVS repository specifications like
.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Win32 systems.
+will work on Windows systems.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.AppendUnique( key = val ", [...])"
+.RI env.PrependUnique( key = val ", [...])"
Appends the specified keyword arguments
to the beginning of construction variables in the environment.
If the Environment does not have
resides should actually
be built in
.IR build_dir .
+.I build_dir
+is interpreted relative to the directory
+of the calling SConscript file.
The optional
.I src_dir
the target files should be built
can be found in
.IR src_dir .
+.I src_dir
+is interpreted relative to the directory
+of the calling SConscript file.
By default,
.B scons
This tells
.B scons
to store all file signatures
-in the specified
+in the specified database
.IR file .
If the
.I file
-is omitted,
-.B .sconsign.dbm
+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,
.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
Examples:
.ES
-# Stores signatures in ".sconsign.dbm"
-# in the top-level SConstruct directory.
+# Explicitly stores signatures in ".sconsign.dblite"
+# in the top-level SConstruct directory (the
+# default behavior).
SConsignFile()
# Stores signatures in the file "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 not env.has_key('FOO'): env['FOO'] = 'foo'
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.B max_drift
which corresponds to --max-drift;
.B num_jobs
-which corresponds to -j and --jobs;
-.B save_explain_info
-which corresponds to --save-explain-info.
+which corresponds to -j and --jobs.
See the documentation for the
corresponding command line object for information about each specific
option. Example:
env.SourceCode('no_source.c', None)
.EE
'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
-'\"
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
+Performs construction variable interpolation
+on the specified string argument.
+
+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).
+
+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.
+
+By default,
+all returned values are converted
+to their string representation.
+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.
+
+.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 )
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Tool( string, toolpath=[] )
+.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 be
+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.
+
.ES
env = Environment(tools = [ Tool('msvc') ])
u(env) # adds 'opengl' to the TOOLS variable
.EE
.TP
-.RI env.Tool( string [, toolpath] )
+.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'])
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Value( value )
+.RI Value( value ", [" built_value ])
.TP
-.RI env.Value( value )
+.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
+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. When using timestamp source signatures, Value nodes'
-timestamps are equal to the system time when the node is created.
+will be rebuilt. 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.
.ES
def create(target, source, env):
env = Environment()
env['BUILDERS']['Config'] = Builder(action = create)
env.Config(target = 'package-config', source = Value(prefix))
+
+def build_value(target, source, env):
+ target[0].write(source[0].get_contents())
+
+output = env.Value('before')
+input = env.Value('after')
+
+env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
+env.UpdateValue(target = Value(output), source = Value(input))
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
or the user's current external PATH
(os.environ['PATH'])
by default.
-On Win32 systems, searches for executable
+On Windows systems, searches for executable
programs with any of the file extensions
listed in the specified
.I pathext,
supports a number of Python variables
that can be used in SConscript files
to affect how you want the build to be performed.
+These variables may be accessed from custom Python modules that you
+import into an SConscript file by adding the following
+to the Python module:
+
+.ES
+from SCons.Script import *
+.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
.\" env["CC"] = "c68x"
.\" env["CFLAGS"] = "-ps -qq -mr"
-.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
-.\" Default:
-.\" (I dunno what this is ;-)
-A construction environment has an associated dictionary of
-.I construction variables
-that are used by built-in or user-supplied build rules.
-Construction variables must follow the same rules for
-Python identifiers:
-the initial character must be an underscore or letter,
-followed by any number of underscores, letters, or digits.
-
-A number of useful construction variables are automatically defined by
-scons for each supported platform, and additional construction variables
-can be defined by the user. The following is a list of the automatically
-defined construction variables:
-
-.IP AR
-The static library archiver.
-
-.IP ARCOM
-The command line used to generate a static library from object files.
-
-.IP ARFLAGS
-General options passed to the static library archiver.
-
-.IP AS
-The assembler.
-
-.IP ASCOM
-The command line used to generate an object file
-from an assembly-language source file.
-
-.IP ASFLAGS
-General options passed to the assembler.
-
-.IP ASPPCOM
-The command line used to assemble an assembly-language
-source file into an object file
-after first running the file through the C preprocessor.
-Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP BIBTEX
-The bibliography generator for the TeX formatter and typesetter and the
-LaTeX structured formatter and typesetter.
-
-.IP BIBTEXCOM
-The command line used to call the bibliography generator for the
-TeX formatter and typesetter and the LaTeX structured formatter and
-typesetter.
-
-.IP BIBTEXFLAGS
-General options passed to the bibliography generator for the TeX formatter
-and typesetter and the LaTeX structured formatter and typesetter.
-
-.IP BITKEEPER
-The BitKeeper executable.
-
-.IP BITKEEPERCOM
-The command line for
-fetching source files using BitKEeper.
-
-.IP BITKEEPERGET
-The command ($BITKEEPER) and subcommand
-for fetching source files using BitKeeper.
-
-.IP BITKEEPERGETFLAGS
-Options that are passed to the BitKeeper
-.B get
-subcommand.
-
-.IP BUILDERS
-A dictionary mapping the names of the builders
-available through this environment
-to underlying Builder objects.
-Builders named
-Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
-are available by default.
-If you initialize this variable when an
-Environment is created:
-
-.ES
-env = Environment(BUILDERS = {'NewBuilder' : foo})
-.EE
-.IP
-the default Builders will no longer be available.
-To use a new Builder object in addition to the default Builders,
-add your new Builder object like this:
-
-.ES
-env = Environment()
-env.Append(BUILDERS = {'NewBuilder' : foo})
-.EE
-.IP
-or this:
-
-.ES
-env = Environment()
-env['BUILDERS]['NewBuilder'] = foo
-.EE
-
-.IP CC
-The C compiler.
-
-.IP CCCOM
-The command line used to compile a C source file to a (static) object file.
-Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP CCFLAGS
-General options that are passed to the C compiler.
-
-.IP CFILESUFFIX
-The suffix for C source files.
-This is used by the internal CFile builder
-when generating C files from Lex (.l) or YACC (.y) input files.
-The default suffix, of course, is
-.I .c
-(lower case).
-On case-insensitive systems (like Win32),
-SCons also treats
-.I .C
-(upper case) files
-as C files.
-
-.IP CCVERSION
-The version number of the C compiler.
-This may or may not be set,
-depending on the specific C compiler being used.
-
-.IP _concat
-A function used to produce variables like $_CPPINCFLAGS. It takes
-four or five
-arguments: a prefix to concatenate onto each element, a list of
-elements, a suffix to concatenate onto each element, an environment
-for variable interpolation, and an optional function that will be
-called to transform the list before concatenation.
-
-.ES
-env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
-.EE
-
-.IP CPPDEFINES
-A platform independent specification of C preprocessor definitions.
-The definitions will be added to command lines
-through the automatically-generated
-$_CPPDEFFLAGS construction variable (see below),
-which is constructed according to
-the type of value of $CPPDEFINES:
-
-.IP
-If $CPPDEFINES is a string,
-the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be added to the beginning and end.
-
-.ES
-# Will add -Dxyz to POSIX compiler command lines,
-# and /Dxyz to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES='xyz')
-.EE
-
-.IP
-If $CPPDEFINES is a list,
-the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be appended to the beginning and end
-of each element in the list.
-If any element is a list or tuple,
-then the first item is the name being
-defined and the second item is its value:
-
-.ES
-# Will add -DB=2 -DA to POSIX compiler command lines,
-# and /DB=2 /DA to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES=[('B', 2), 'A'])
-.EE
-
-.IP
-If $CPPDEFINES is a dictionary,
-the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be appended to the beginning and end
-of each item from the dictionary.
-The key of each dictionary item
-is a name being defined
-to the dictionary item's corresponding value;
-if the value is
-.BR None ,
-then the name is defined without an explicit value.
-Note that the resulting flags are sorted by keyword
-to ensure that the order of the options on the
-command line is consistent each time
-.B scons
- is run.
-
-.ES
-# Will add -DA -DB=2 to POSIX compiler command lines,
-# and /DA /DB=2 to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES={'B':2, 'A':None})
-.EE
-
-.IP _CPPDEFFLAGS
-An automatically-generated construction variable
-containing the C preprocessor command-line options
-to define values.
-The value of $_CPPDEFFLAGS is created
-by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
-to the beginning and end
-of each directory in $CPPDEFINES.
-
-.IP CPPDEFPREFIX
-The prefix used to specify preprocessor definitions
-on the C compiler command line.
-This will be appended to the beginning of each definition
-in the $CPPDEFINES construction variable
-when the $_CPPDEFFLAGS variable is automatically generated.
-
-.IP CPPDEFSUFFIX
-The suffix used to specify preprocessor definitions
-on the C compiler command line.
-This will be appended to the end of each definition
-in the $CPPDEFINES construction variable
-when the $_CPPDEFFLAGS variable is automatically generated.
-
-.IP CPPFLAGS
-User-specified C preprocessor options.
-These will be included in any command that uses the C preprocessor,
-including not just compilation of C and C++ source files
-via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
-but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
-$F77PPCOM and $SHF77PPCOM command lines
-used to compile a Fortran source file,
-and the $ASPPCOM command line
-used to assemble an assembly language source file,
-after first running each file through the C preprocessor.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $CPPPATH.
-See
-.BR _CPPINCFLAGS ,
-below,
-for the variable that expands to those options.
-
-.IP _CPPINCFLAGS
-An automatically-generated construction variable
-containing the C preprocessor command-line options
-for specifying directories to be searched for include files.
-The value of $_CPPINCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $CPPPATH.
-
-.IP CPPPATH
-The list of directories that the C preprocessor will search for include
-directories. The C/C++ implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in CPPPATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(CPPPATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(CPPPATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_CPPINCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $CPPPATH.
-Any command lines you define that need
-the CPPPATH directory list should
-include $_CPPINCFLAGS:
-
-.ES
-env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP CPPSUFFIXES
-The list of suffixes of files that will be scanned
-for C preprocessor implicit dependencies
-(#include lines).
-The default list is:
-
-.ES
-[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
- ".h", ".H", ".hxx", ".hpp", ".hh",
- ".F", ".fpp", ".FPP",
- ".S", ".spp", ".SPP"]
-.EE
-
-.IP CVS
-The CVS executable.
-
-.IP CVSCOFLAGS
-Options that are passed to the CVS checkout subcommand.
-
-.IP CVSCOM
-The command line used to
-fetch source files from a CVS repository.
-
-.IP CVSFLAGS
-General options that are passed to CVS.
-By default, this is set to
-"-d $CVSREPOSITORY"
-to specify from where the files must be fetched.
-
-.IP CVSREPOSITORY
-The path to the CVS repository.
-This is referenced in the default
-$CVSFLAGS value.
-
-.IP CXX
-The C++ compiler.
-
-.IP CXXFILESUFFIX
-The suffix for C++ source files.
-This is used by the internal CXXFile builder
-when generating C++ files from Lex (.ll) or YACC (.yy) input files.
-The default suffix is
-.IR .cc .
-SCons also treats files with the suffixes
-.IR .cpp ,
-.IR .cxx ,
-.IR .c++ ,
-and
-.I .C++
-as C++ files.
-On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
-SCons also treats
-.I .C
-(upper case) files
-as C++ files.
-
-.IP CXXCOM
-The command line used to compile a C++ source file to an object file.
-Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP CXXFLAGS
-General options that are passed to the C++ compiler.
-
-.IP CXXVERSION
-The version number of the C++ compiler.
-This may or may not be set,
-depending on the specific C++ compiler being used.
-
-.IP Dir
-A function that converts a file name into a Dir instance relative to the
-target being built.
-
-.IP DSUFFIXES
-The list of suffixes of files that will be scanned
-for imported D package files.
-The default list is:
-
-.ES
-['.d']
-.EE
-
-.IP DVIPDF
-The TeX DVI file to PDF file converter.
-
-.IP DVIPDFFLAGS
-General options passed to the TeX DVI file to PDF file converter.
-
-.IP DVIPDFCOM
-The command line used to convert TeX DVI files into a PDF file.
-
-.IP DVIPS
-The TeX DVI file to PostScript converter.
-
-.IP DVIPSFLAGS
-General options passed to the TeX DVI file to PostScript converter.
-
-.IP ENV
-A dictionary of environment variables
-to use when invoking commands. When ENV is used in a command all list
-values will be joined using the path separator and any other non-string
-values will simply be coerced to a string.
-Note that, by default,
-.B scons
-does
-.I not
-propagate the environment in force when you
-execute
-.B scons
-to the commands used to build target files.
-This is so that builds will be guaranteed
-repeatable regardless of the environment
-variables set at the time
-.B scons
-is invoked.
-
-If you want to propagate your
-environment variables
-to the commands executed
-to build target files,
-you must do so explicitly:
-
-.ES
-import os
-env = Environment(ENV = os.environ)
-.EE
-
-.RS
-Note that you can choose only to propagate
-certain environment variables.
-A common example is
-the system
-.B PATH
-environment variable,
-so that
-.B scons
-uses the same utilities
-as the invoking shell (or other process):
-.RE
-
-.ES
-import os
-env = Environment(ENV = {'PATH' : os.environ['PATH']})
-.EE
-
-.IP ESCAPE
-A function that will be called to escape shell special characters in
-command lines. The function should take one argument: the command line
-string to escape; and should return the escaped command line.
-
-.IP F77
-The Fortran 77 compiler.
-You should normally set the $FORTRAN variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $F77 if you need to use a specific compiler
-or compiler version for Fortran 77 files.
-
-.IP F77COM
-The command line used to compile a Fortran 77 source file to an object file.
-You only need to set $F77COM if you need to use a specific
-command line for Fortran 77 files.
-You should normally set the $FORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F77FLAGS
-General user-specified options that are passed to the Fortran 77 compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $F77PATH.
-See
-.BR _F77INCFLAGS ,
-below,
-for the variable that expands to those options.
-You only need to set $F77FLAGS if you need to define specific
-user options for Fortran 77 files.
-You should normally set the $FORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F77INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 77 compiler command-line options
-for specifying directories to be searched for include files.
-The value of $_F77INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $F77PATH.
-
-.IP F77PATH
-The list of directories that the Fortran 77 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $F77FLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in $F77PATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set $F77PATH if you need to define a specific
-include path for Fortran 77 files.
-You should normally set the $FORTRANPATH variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F77PATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F77PATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_F77INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $F77PATH.
-Any command lines you define that need
-the F77PATH directory list should
-include $_F77INCFLAGS:
-
-.ES
-env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F77PPCOM
-The command line used to compile a Fortran 77 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $F77PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 77 files.
-You should normally set the $FORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP F90
-The Fortran 90 compiler.
-You should normally set the $FORTRAN variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $F90 if you need to use a specific compiler
-or compiler version for Fortran 90 files.
-
-.IP F90COM
-The command line used to compile a Fortran 90 source file to an object file.
-You only need to set $F90COM if you need to use a specific
-command line for Fortran 90 files.
-You should normally set the $FORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F90FLAGS
-General user-specified options that are passed to the Fortran 90 compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $F90PATH.
-See
-.BR _F90INCFLAGS ,
-below,
-for the variable that expands to those options.
-You only need to set $F90FLAGS if you need to define specific
-user options for Fortran 90 files.
-You should normally set the $FORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F90INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 90 compiler command-line options
-for specifying directories to be searched for include files.
-The value of $_F90INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $F90PATH.
-
-.IP F90PATH
-The list of directories that the Fortran 90 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $F90FLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in $F90PATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set $F90PATH if you need to define a specific
-include path for Fortran 90 files.
-You should normally set the $FORTRANPATH variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F90PATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F90PATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_F90INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $F90PATH.
-Any command lines you define that need
-the F90PATH directory list should
-include $_F90INCFLAGS:
-
-.ES
-env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F90PPCOM
-The command line used to compile a Fortran 90 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $F90PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 90 files.
-You should normally set the $FORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP F95
-The Fortran 95 compiler.
-You should normally set the $FORTRAN variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $F95 if you need to use a specific compiler
-or compiler version for Fortran 95 files.
-
-.IP F95COM
-The command line used to compile a Fortran 95 source file to an object file.
-You only need to set $F95COM if you need to use a specific
-command line for Fortran 95 files.
-You should normally set the $FORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F95FLAGS
-General user-specified options that are passed to the Fortran 95 compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $F95PATH.
-See
-.BR _F95INCFLAGS ,
-below,
-for the variable that expands to those options.
-You only need to set $F95FLAGS if you need to define specific
-user options for Fortran 95 files.
-You should normally set the $FORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F95INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 95 compiler command-line options
-for specifying directories to be searched for include files.
-The value of $_F95INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $F95PATH.
-
-.IP F95PATH
-The list of directories that the Fortran 95 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $F95FLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in $F95PATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set $F95PATH if you need to define a specific
-include path for Fortran 95 files.
-You should normally set the $FORTRANPATH variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F95PATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F95PATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_F95INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $F95PATH.
-Any command lines you define that need
-the F95PATH directory list should
-include $_F95INCFLAGS:
-
-.ES
-env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F95PPCOM
-The command line used to compile a Fortran 95 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $F95PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 95 files.
-You should normally set the $FORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP FORTRAN
-The default Fortran compiler
-for all versions of Fortran.
-
-.IP FORTRANCOM
-The command line used to compile a Fortran source file to an object file.
-By default, any options specified
-in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
-$_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
-are included on this command line.
-
-.IP FORTRANFLAGS
-General user-specified options that are passed to the Fortran compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include or module search path options
-that scons generates automatically from $FORTRANPATH.
-See
-.BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
-below,
-for the variables that expand those options.
-
-.IP _FORTRANINCFLAGS
-An automatically-generated construction variable
-containing the Fortran compiler command-line options
-for specifying directories to be searched for include
-files and module files.
-The value of $_FORTRANINCFLAGS is created
-by prepending/appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $FORTRANPATH.
-
-.IP FORTRANMODDIR
-Directory location where the Fortran compiler should place
-any module files it generates. This variable is empty, by default. Some
-Fortran compilers will internally append this directory in the search path
-for module files, as well
-
-.IP FORTRANMODDIRPREFIX
-The prefix used to specify a module directory on the Fortran compiler command
-line.
-This will be appended to the beginning of the directory
-in the $FORTRANMODDIR construction variables
-when the $_FORTRANMODFLAG variables is automatically generated.
-
-.IP FORTRANMODDIRSUFFIX
-The suffix used to specify a module directory on the Fortran compiler command
-line.
-This will be appended to the beginning of the directory
-in the $FORTRANMODDIR construction variables
-when the $_FORTRANMODFLAG variables is automatically generated.
-
-.IP FORTRANMODFLAG
-An automatically-generated construction variable
-containing the Fortran compiler command-line option
-for specifying the directory location where the Fortran
-compiler should place any module files that happen to get
-generated during compilation.
-The value of $_FORTRANMODFLAG is created
-by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
-to the beginning and end of the directory in $FORTRANMODDIR.
-
-.IP FORTRANMODPREFIX
-The module file prefix used by the Fortran compiler. SCons assumes that
-the Fortran compiler follows the quasi-standard naming convention for
-module files of
-.I <module_name>.mod.
-As a result, this variable is left empty, by default. For situations in
-which the compiler does not necessarily follow the normal convention,
-the user may use this variable. Its value will be appended to every
-module file name as scons attempts to resolve dependencies.
-
-.IP FORTRANMODSUFFIX
-The module file suffix used by the Fortran compiler. SCons assumes that
-the Fortran compiler follows the quasi-standard naming convention for
-module files of
-.I <module_name>.mod.
-As a result, this variable is set to ".mod", by default. For situations
-in which the compiler does not necessarily follow the normal convention,
-the user may use this variable. Its value will be appended to every
-module file name as scons attempts to resolve dependencies.
-
-.IP FORTRANPATH
-The list of directories that the Fortran compiler will search for
-include files and (for some compilers) module files. The Fortran implicit
-dependency scanner will search these directories for include files (but
-not module files since they are autogenerated and, as such, may not
-actually exist at the time the scan takes place). Don't explicitly put
-include directory arguments in FORTRANFLAGS because the result will be
-non-portable and the directories will not be searched by the dependency
-scanner. Note: directory names in FORTRANPATH will be looked-up relative
-to the SConscript directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(FORTRANPATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(FORTRANPATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_FORTRANINCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $FORTRANPATH.
-Any command lines you define that need
-the FORTRANPATH directory list should
-include $_FORTRANINCFLAGS:
-
-.ES
-env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP FORTRANPPCOM
-The command line used to compile a Fortran source file to an object file
-after first running the file through the C preprocessor.
-By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
-_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
-construction variables are included on this command line.
-
-.IP FORTRANSUFFIXES
-The list of suffixes of files that will be scanned
-for Fortran implicit dependencies
-(INCLUDE lines & USE statements).
-The default list is:
-
-.ES
-[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
-".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
-.EE
-
-.IP File
-A function that converts a file name into a File instance relative to the
-target being built.
-
-.IP GS
-The Ghostscript program used to convert PostScript to PDF files.
-
-.IP GSFLAGS
-General options passed to the Ghostscript program
-when converting PostScript to PDF files.
-
-.IP GSCOM
-The Ghostscript command line used to convert PostScript to PDF files.
-
-.IP IDLSUFFIXES
-The list of suffixes of files that will be scanned
-for IDL implicit dependencies
-(#include or import lines).
-The default list is:
-
-.ES
-[".idl", ".IDL"]
-.EE
-
-.IP INCPREFIX
-The prefix used to specify an include directory on the C compiler command
-line.
-This will be appended to the beginning of each directory
-in the $CPPPATH and $FORTRANPATH construction variables
-when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
-variables are automatically generated.
-
-.IP INCSUFFIX
-The suffix used to specify an include directory on the C compiler command
-line.
-This will be appended to the end of each directory
-in the $CPPPATH and $FORTRANPATH construction variables
-when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
-variables are automatically generated.
-
-.IP INSTALL
-A function to be called to install a file into a
-destination file name.
-The default function copies the file into the destination
-(and sets the destination file's mode and permission bits
-to match the source file's).
-The function takes the following arguments:
-
-.ES
-def install(dest, source, env):
-.EE
-.IP
-.I dest
-is the path name of the destination file.
-.I source
-is the path name of the source file.
-.I env
-is the construction environment
-(a dictionary of construction values)
-in force for this file installation.
-
-.IP JAR
-The Java archive tool.
-
-.IP JARCHDIR
-The directory to which the Java archive tool should change
-(using the
-.B \-C
-option).
-
-.IP JARCOM
-The command line used to call the Java archive tool.
-
-.IP JARFLAGS
-General options passed to the Java archive tool.
-By default this is set to
-.B cf
-to create the necessary
-.I jar
-file.
-
-.IP JARSUFFIX
-The suffix for Java archives:
-.B .jar
-by default.
-
-.IP JAVAC
-The Java compiler.
-
-.IP JAVACCOM
-The command line used to compile a directory tree containing
-Java source files to
-corresponding Java class files.
-Any options specified in the $JAVACFLAGS construction variable
-are included on this command line.
-
-.IP JAVACFLAGS
-General options that are passed to the Java compiler.
-
-.IP JAVACLASSDIR
-The directory in which Java class files may be found.
-This is stripped from the beginning of any Java .class
-file names supplied to the
-.B JavaH
-builder.
-
-.IP JAVACLASSSUFFIX
-The suffix for Java class files;
-.B .class
-by default.
-
-.IP JAVAH
-The Java generator for C header and stub files.
-
-.IP JAVAHCOM
-The command line used to generate C header and stub files
-from Java classes.
-Any options specified in the $JAVAHFLAGS construction variable
-are included on this command line.
-
-.IP JAVAHFLAGS
-General options passed to the C header and stub file generator
-for Java classes.
-
-.IP JAVASUFFIX
-The suffix for Java files;
-.B .java
-by default.
-
-.IP LATEX
-The LaTeX structured formatter and typesetter.
-
-.IP LATEXCOM
-The command line used to call the LaTeX structured formatter and typesetter.
-
-.IP LATEXFLAGS
-General options passed to the LaTeX structured formatter and typesetter.
-
-.IP LEX
-The lexical analyzer generator.
-
-.IP LEXFLAGS
-General options passed to the lexical analyzer generator.
-
-.IP LEXCOM
-The command line used to call the lexical analyzer generator
-to generate a source file.
-
-.IP _LIBDIRFLAGS
-An automatically-generated construction variable
-containing the linker command-line options
-for specifying directories to be searched for library.
-The value of $_LIBDIRFLAGS is created
-by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
-to the beginning and end
-of each directory in $LIBPATH.
-
-.IP LIBDIRPREFIX
-The prefix used to specify a library directory on the linker command line.
-This will be appended to the beginning of each directory
-in the $LIBPATH construction variable
-when the $_LIBDIRFLAGS variable is automatically generated.
-
-.IP LIBDIRSUFFIX
-The suffix used to specify a library directory on the linker command line.
-This will be appended to the end of each directory
-in the $LIBPATH construction variable
-when the $_LIBDIRFLAGS variable is automatically generated.
-
-.IP _LIBFLAGS
-An automatically-generated construction variable
-containing the linker command-line options
-for specifying libraries to be linked with the resulting target.
-The value of $_LIBFLAGS is created
-by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
-to the beginning and end
-of each directory in $LIBS.
-
-.IP LIBLINKPREFIX
-The prefix used to specify a library to link on the linker command line.
-This will be appended to the beginning of each library
-in the $LIBS construction variable
-when the $_LIBFLAGS variable is automatically generated.
-
-.IP LIBLINKSUFFIX
-The suffix used to specify a library to link on the linker command line.
-This will be appended to the end of each library
-in the $LIBS construction variable
-when the $_LIBFLAGS variable is automatically generated.
-
-.IP LIBPATH
-The list of directories that will be searched for libraries.
-The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $LINKFLAGS or $SHLINKFLAGS
-because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in LIBPATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(LIBPATH='#/libs')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-libs = Dir('libs')
-env = Environment(LIBPATH=libs)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_LIBDIRFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$LIBDIRPREFIX and $LIBDIRSUFFIX
-construction variables
-to the beginning and end
-of each directory in $LIBPATH.
-Any command lines you define that need
-the LIBPATH directory list should
-include $_LIBDIRFLAGS:
-
-.ES
-env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-.EE
-
-.IP LIBPREFIX
-The prefix used for (static) library file names.
-A default value is set for each platform
-(posix, win32, os2, etc.),
-but the value is overridden by individual tools
-(ar, mslib, sgiar, sunar, tlib, etc.)
-to reflect the names of the libraries they create.
-
-.IP LIBPREFIXES
-An array of legal prefixes for library file names.
-
-.IP LIBS
-A list of one or more libraries
-that will be linked with
-any executable programs
-created by this environment.
-
-.IP
-The library list will be added to command lines
-through the automatically-generated
-$_LIBFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$LIBLINKPREFIX and $LIBLINKSUFFIX
-construction variables
-to the beginning and end
-of each directory in $LIBS.
-Any command lines you define that need
-the LIBS library list should
-include $_LIBFLAGS:
-
-.ES
-env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-.EE
-
-.IP LIBSUFFIX
-The suffix used for (static) library file names.
-A default value is set for each platform
-(posix, win32, os2, etc.),
-but the value is overridden by individual tools
-(ar, mslib, sgiar, sunar, tlib, etc.)
-to reflect the names of the libraries they create.
-
-.IP LIBSUFFIXES
-An array of legal suffixes for library file names.
-
-.IP LINK
-The linker.
-
-.IP LINKFLAGS
-General user options passed to the linker.
-Note that this variable should
-.I not
-contain
-.B -l
-(or similar) options for linking with the libraries listed in $LIBS,
-nor
-.B -L
-(or similar) library search path options
-that scons generates automatically from $LIBPATH.
-See
-.BR _LIBFLAGS ,
-above,
-for the variable that expands to library-link options,
-and
-.BR _LIBDIRFLAGS ,
-above,
-for the variable that expands to library search path options.
-
-.IP LINKCOM
-The command line used to link object files into an executable.
-
-.IP M4
-The M4 macro preprocessor.
-
-.IP M4FLAGS
-General options passed to the M4 macro preprocessor.
-
-.IP M4COM
-The command line used to pass files through the macro preprocessor.
-
-.IP MAXLINELENGTH
-The maximum number of characters allowed on an external command line.
-On Win32 systems,
-link lines longer than this many characters
-are linke via a temporary file name.
-
-.IP MSVS
-When the Microsoft Visual Studio tools are initialized, they set up
-this dictionary with the following keys:
-
-.B VERSION:
-the version of MSVS being used (can be set via
-MSVS_VERSION)
-
-.B VERSIONS:
-the available versions of MSVS installed
-
-.B VCINSTALLDIR:
-installed directory of Visual C++
-
-.B VSINSTALLDIR:
-installed directory of Visual Studio
-
-.B FRAMEWORKDIR:
-installed directory of the .NET framework
-
-.B FRAMEWORKVERSIONS:
-list of installed versions of the .NET framework, sorted latest to oldest.
-
-.B FRAMEWORKVERSION:
-latest installed version of the .NET framework
-
-.B FRAMEWORKSDKDIR:
-installed location of the .NET SDK.
-
-.B PLATFORMSDKDIR:
-installed location of the Platform SDK.
-
-.B PLATFORMSDK_MODULES:
-dictionary of installed Platform SDK modules,
-where the dictionary keys are keywords for the various modules, and
-the values are 2-tuples where the first is the release date, and the
-second is the version number.
-
-If a value isn't set, it wasn't available in the registry.
-
-.IP MSVS_IGNORE_IDE_PATHS
-Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
-instead of the settings from the IDE.
-
-For Visual Studio, SCons will (by default) automatically determine
-where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
-set by the IDE. You can override this behavior by setting these
-variables after Environment initialization, or by setting
-.B MSVS_IGNORE_IDE_PATHS = 1
-in the Environment initialization.
-Specifying this will not leave these unset, but will set them to a
-minimal set of paths needed to run the tools successfully.
-
-.ES
-For VS6, the mininimal set is:
- INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
- LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
- PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
-For VS7, it is:
- INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
- LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
- PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
-.EE
-
-.IP
-Where '<VSDir>' is the installed location of Visual Studio.
-
-.IP MSVS_USE_MFC_DIRS
-Tells the MS Visual Studio tool(s) to use
-the MFC directories in its default paths
-for compiling and linking.
-Under MSVS version 6,
-setting
-.B MSVS_USE_MFC_DIRS
-to a non-zero value
-adds the
-.BR ATL\\include
-and
-.BR MFC\\include
-directories to
-the default
-.B INCLUDE
-external environment variable,
-and adds the
-.B MFC\\lib
-directory to
-the default
-.B LIB
-external environment variable.
-Under MSVS version 7,
-setting
-.B MSVS_USE_MFC_DIRS
-to a non-zero value
-adds the
-.BR atlmfc\\include
-directory to the default
-.B INCLUDE
-external environment variable,
-and adds the
-.BR atlmfc\\lib
-directory to the default
-.B LIB
-external environment variable.
-The current default value is
-.BR 1 ,
-which means these directories
-are added to the paths by default.
-This default value is likely to change
-in a future release,
-so users who want the ATL and MFC
-values included in their paths
-are encouraged to enable the
-.B MSVS_USE_MFC_DIRS
-value explicitly
-to avoid future incompatibility.
-This variable has no effect if the
-.BR INCLUDE
-or
-.BR LIB
-environment variables are set explictly.
-
-.IP MSVS_VERSION
-Sets the preferred version of MSVS to use.
-
-SCons will (by default) select the latest version of MSVS
-installed on your machine. So, if you have version 6 and version 7
-(MSVS .NET) installed, it will prefer version 7. You can override this by
-specifying the
-.B MSVS_VERSION
-variable in the Environment initialization, setting it to the
-appropriate version ('6.0' or '7.0', for example).
-If the given version isn't installed, tool initialization will fail.
-
-.IP MSVSPROJECTCOM
-The action used to generate Microsoft Visual Studio
-project and solution files.
-
-.IP MSVSPROJECTSUFFIX
-The suffix used for Microsoft Visual Studio project (DSP) files.
-The default value is
-.B .vcproj
-when using Visual Studio version 7.x (.NET),
-and
-.B .dsp
-when using earlier versions of Visual Studio.
-
-.IP MSVSSOLUTIONSUFFIX
-The suffix used for Microsoft Visual Studio solution (DSW) files.
-The default value is
-.B .sln
-when using Visual Studio version 7.x (.NET),
-and
-.B .dsw
-when using earlier versions of Visual Studio.
-
-.IP no_import_lib
-When set to non-zero,
-suppresses creation of a corresponding Win32 static import lib by the
-.B SharedLibrary
-builder when used with
-MinGW or Microsoft Visual Studio.
-This also suppresses creation
-of an export (.exp) file
-when using Microsoft Visual Studio.
-
-.IP OBJPREFIX
-The prefix used for (static) object file names.
-
-.IP OBJSUFFIX
-The suffix used for (static) object file names.
-
-.IP P4
-The Perforce executable.
-
-.IP P4COM
-The command line used to
-fetch source files from Perforce.
-
-.IP P4FLAGS
-General options that are passed to Perforce.
-
-.IP PCH
-The Microsoft Visual C++ precompiled header that will be used when compiling
-object files. This variable is ignored by tools other than Microsoft Visual C++.
-When this variable is
-defined SCons will add options to the compiler command line to
-cause it to use the precompiled header, and will also set up the
-dependencies for the PCH file. Example:
-
-.ES
-env['PCH'] = 'StdAfx.pch'
-.EE
-
-.IP PCHSTOP
-This variable specifies how much of a source file is precompiled. This
-variable is ignored by tools other than Microsoft Visual C++, or when
-the PCH variable is not being used. When this variable is define it
-must be a string that is the name of the header that
-is included at the end of the precompiled portion of the source files, or
-the empty string if the "#pragma hrdstop" construct is being used:
-
-.ES
-env['PCHSTOP'] = 'StdAfx.h'
-.EE
-
-.IP PDB
-The Microsoft Visual C++ PDB file that will store debugging information for
-object files, shared libraries, and programs. This variable is ignored by
-tools other than Microsoft Visual C++.
-When this variable is
-defined SCons will add options to the compiler and linker command line to
-cause them to generate external debugging information, and will also set up the
-dependencies for the PDB file. Example:
-
-.ES
-env['PDB'] = 'hello.pdb'
-.EE
-
-.IP PDFCOM
-A deprecated synonym for $DVIPDFCOM.
-
-.IP PDFPREFIX
-The prefix used for PDF file names.
-
-.IP PDFSUFFIX
-The suffix used for PDF file names.
-
-.IP PLATFORM
-The name of the platform used to create the Environment. If no platform is
-specified when the Environment is created,
-.B SCons
-autodetects the platform.
-
-.ES
-env = Environment(tools = [])
-if env['PLATFORM'] == 'cygwin':
- Tool('mingw')(env)
-else:
- Tool('msvc')(env)
-.EE
-
-.IP PROGPREFIX
-The prefix used for executable file names.
-
-.IP PROGSUFFIX
-The suffix used for executable file names.
-
-.IP PSCOM
-The command line used to convert TeX DVI files into a PostScript file.
-
-.IP PSPREFIX
-The prefix used for PostScript file names.
-
-.IP PSSUFFIX
-The prefix used for PostScript file names.
-
-.IP QTDIR
-The qt tool tries to take this from os.environ.
-It also initializes all QT_*
-construction variables listed below.
-(Note that all paths are constructed
-with python's os.path.join() method,
-but are listed here with the '/' separator
-for easier reading.)
-In addition, the construction environment
-variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER
-are modified. Because the build-performance is affected when using this tool,
-you have to explicitly specify it at Environment creation:
-
-.ES
-Environment(tools=['default','qt'])
-.EE
-
-The qt tool supports the following operations:
-
-.B Automatic moc file generation from header files.
-You do not have to specify moc files explicitly, the tool does it for you.
-However, there are a few preconditions to do so: Your header file must have
-the same filebase as your implementation file and must stay in the same
-directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
-can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
-See also the corresponding builder method
-.B Moc()
-
-.B Automatic moc file generation from cxx files.
-As stated in the qt documentation, include the moc file at the end of
-the cxx file. Note that you have to include the file, which is generated
-by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
-<basename>.moc. A warning is generated after building the moc file, if you
-do not include the correct file. If you are using BuildDir, you may
-need to specify duplicate=1. You can turn off automatic moc file generation
-by setting QT_AUTOSCAN to 0. See also the corresponding builder method
-.B Moc()
-
-.B Automatic handling of .ui files.
-The implementation files generated from .ui files are handled much the same
-as yacc or lex files. Each .ui file given as a source of Program, Library or
-SharedLibrary will generate three files, the declaration file, the
-implementation file and a moc file. Because there are also generated headers,
-you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
-.B Uic()
-
-.IP QT_AUTOSCAN
-Turn off scanning for mocable files. Use the Moc Builder to explicitely
-specify files to run moc on.
-
-.IP QT_DEBUG
-Prints lots of debugging information while scanning for moc files.
-
-.IP QT_LIB
-Default value is 'qt'. You may want to set this to 'qt-mt'.
-
-.IP QT_MOC
-Default value is '$QTDIR/bin/moc'.
-
-.IP QT_MOCCXXPREFIX
-Default value is ''. Prefix for moc output files, when source is a cxx file.
-
-.IP QT_MOCCXXSUFFIX
-Default value is '.moc'. Suffix for moc output files, when source is a cxx
-file.
-
-.IP QT_MOCFROMCPPFLAGS
-Default value is '-i'. These flags are passed to moc, when moccing a
-cpp file.
-
-.IP QT_MOCFROMCXXCOM
-Command to generate a moc file from a cpp file.
-
-.IP QT_MOCFROMHCOM
-Command to generate a moc file from a header.
-
-.IP QT_MOCFROMHFLAGS
-Default value is ''. These flags are passed to moc, when moccing a header
-file.
-
-.IP QT_MOCHPREFIX
-Default value is 'moc_'. Prefix for moc output files, when source is a header.
-
-.IP QT_MOCHSUFFIX
-Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
-a header.
-
-.IP QT_UIC
-Default value is '$QTDIR/bin/uic'.
-
-.IP QT_UICDECLCOM
-Command to generate header files from .ui files.
-
-.IP QT_UICDECLFLAGS
-Default value is ''. These flags are passed to uic, when creating a a h
-file from a .ui file.
-
-.IP QT_UICDECLPREFIX
-Default value is ''. Prefix for uic generated header files.
-
-.IP QT_UICDECLSUFFIX
-Default value is '.h'. Suffix for uic generated header files.
-
-.IP QT_UICIMPLCOM
-Command to generate cxx files from .ui files.
-
-.IP QT_UICIMPLFLAGS
-Default value is ''. These flags are passed to uic, when creating a cxx
-file from a .ui file.
-
-.IP QT_UICIMPLPREFIX
-Default value is 'uic_'. Prefix for uic generated implementation files.
-
-.IP QT_UICIMPLSUFFIX
-Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
-files.
-
-.IP QT_UISUFFIX
-Default value is '.ui'. Suffix of designer input files.
-
-.IP RANLIB
-The archive indexer.
-
-.IP RANLIBFLAGS
-General options passed to the archive indexer.
-
-.IP RC
-The resource compiler used by the RES builder.
-
-.IP RCCOM
-The command line used by the RES builder.
-
-.IP RCFLAGS
-The flags passed to the resource compiler by the RES builder.
-
-.IP RCS
-The RCS executable.
-Note that this variable is not actually used
-for the command to fetch source files from RCS;
-see the
-.B RCS_CO
-construction variable, below.
-
-.IP RCS_CO
-The RCS "checkout" executable,
-used to fetch source files from RCS.
-
-.IP RCS_COCOM
-The command line used to
-fetch (checkout) source files from RCS.
-
-.IP RCS_COFLAGS
-Options that are passed to the $RCS_CO command.
-
-.IP RDirs
-A function that converts a file name into a list of Dir instances by
-searching the repositories.
-
-.IP RMIC
-The Java RMI stub compiler.
-
-.IP RMICCOM
-The command line used to compile stub
-and skeleton class files
-from Java classes that contain RMI implementations.
-Any options specified in the $RMICFLAGS construction variable
-are included on this command line.
-
-.IP RMICFLAGS
-General options passed to the Java RMI stub compiler.
-
-.IP RPATH
-A list of paths to search for shared libraries when running programs.
-Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
-Ignored on platforms and toolchains that don't support it.
-Note that the paths added to RPATH
-are not transformed by
-.B scons
-in any way: if you want an absolute
-path, you must make it absolute yourself.
-
-.IP SCANNERS
-A list of the available implicit dependency scanners.
-New file scanners may be added by
-appending to this list,
-although the more flexible approach
-is to associate scanners
-with a specific Builder.
-See the sections "Builder Objects"
-and "Scanner Objects,"
-below, for more information.
-
-.IP SCCS
-The SCCS executable.
-
-.IP SCCSCOM
-The command line used to
-fetch source files from SCCS.
-
-.IP SCCSFLAGS
-General options that are passed to SCCS.
-
-.IP SCCSGETFLAGS
-Options that are passed specifically to the SCCS "get" subcommand.
-This can be set, for example, to
-.I -e
-to check out editable files from SCCS.
-
-.IP SHCC
-The C compiler used for generating shared-library objects.
-
-.IP SHCCCOM
-The command line used to compile a C source file
-to a shared-library object file.
-Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP SHCCFLAGS
-Options that are passed to the C compiler
-to generate shared-library objects.
-
-.IP SHCXX
-The C++ compiler used for generating shared-library objects.
-
-.IP SHCXXCOM
-The command line used to compile a C++ source file
-to a shared-library object file.
-Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP SHCXXFLAGS
-Options that are passed to the C++ compiler
-to generate shared-library objects.
-
-.IP SHELL
-A string naming the shell program that will be passed to the
-.I SPAWN
-function.
-See the
-.I SPAWN
-construction variable for more information.
-
-.IP SHF77
-The Fortran 77 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRANC variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $SHF77 if you need to use a specific compiler
-or compiler version for Fortran 77 files.
-
-.IP SHF77COM
-The command line used to compile a Fortran 77 source file
-to a shared-library object file.
-You only need to set $SHF77COM if you need to use a specific
-command line for Fortran 77 files.
-You should normally set the $SHFORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF77FLAGS
-Options that are passed to the Fortran 77 compiler
-to generated shared-library objects.
-You only need to set $SHF77FLAGS if you need to define specific
-user options for Fortran 77 files.
-You should normally set the $SHFORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF77PPCOM
-The command line used to compile a Fortran 77 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $SHF77PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 77 files.
-You should normally set the $SHFORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHF90
-The Fortran 90 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRANC variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $SHF90 if you need to use a specific compiler
-or compiler version for Fortran 90 files.
-
-.IP SHF90COM
-The command line used to compile a Fortran 90 source file
-to a shared-library object file.
-You only need to set $SHF90COM if you need to use a specific
-command line for Fortran 90 files.
-You should normally set the $SHFORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF90FLAGS
-Options that are passed to the Fortran 90 compiler
-to generated shared-library objects.
-You only need to set $SHF90FLAGS if you need to define specific
-user options for Fortran 90 files.
-You should normally set the $SHFORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF90PPCOM
-The command line used to compile a Fortran 90 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $SHF90PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 90 files.
-You should normally set the $SHFORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHF95
-The Fortran 95 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRANC variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $SHF95 if you need to use a specific compiler
-or compiler version for Fortran 95 files.
-
-.IP SHF95COM
-The command line used to compile a Fortran 95 source file
-to a shared-library object file.
-You only need to set $SHF95COM if you need to use a specific
-command line for Fortran 95 files.
-You should normally set the $SHFORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF95FLAGS
-Options that are passed to the Fortran 95 compiler
-to generated shared-library objects.
-You only need to set $SHF95FLAGS if you need to define specific
-user options for Fortran 95 files.
-You should normally set the $SHFORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF95PPCOM
-The command line used to compile a Fortran 95 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $SHF95PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 95 files.
-You should normally set the $SHFORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHFORTRAN
-The default Fortran compiler used for generating shared-library objects.
-
-.IP SHFORTRANCOM
-The command line used to compile a Fortran source file
-to a shared-library object file.
-
-.IP SHFORTRANFLAGS
-Options that are passed to the Fortran compiler
-to generate shared-library objects.
-
-.IP SHFORTRANPPCOM
-The command line used to compile a Fortran source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified
-in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP SHLIBPREFIX
-The prefix used for shared library file names.
-
-.IP SHLIBSUFFIX
-The suffix used for shared library file names.
-
-.IP SHLINK
-The linker for programs that use shared libraries.
-
-.IP SHLINKFLAGS
-General user options passed to the linker for programs using shared libraries.
-Note that this variable should
-.I not
-contain
-.B -l
-(or similar) options for linking with the libraries listed in $LIBS,
-nor
-.B -L
-(or similar) include search path options
-that scons generates automatically from $LIBPATH.
-See
-.BR _LIBFLAGS ,
-above,
-for the variable that expands to library-link options,
-and
-.BR _LIBDIRFLAGS ,
-above,
-for the variable that expands to library search path options.
-
-.IP SHOBJPREFIX
-The prefix used for shared object file names.
-
-.IP SHOBJSUFFIX
-The suffix used for shared object file names.
-
-.IP SOURCE
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP SOURCES
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
+.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
+.\" Default:
+.\" (I dunno what this is ;-)
+A construction environment has an associated dictionary of
+.I construction variables
+that are used by built-in or user-supplied build rules.
+Construction variables must follow the same rules for
+Python identifiers:
+the initial character must be an underscore or letter,
+followed by any number of underscores, letters, or digits.
-.IP SPAWN
-A command interpreter function that will be called to execute command line
-strings. The function must expect 4 arguments:
+A number of useful construction variables are automatically defined by
+scons for each supported platform, and additional construction variables
+can be defined by the user. The following is a list of the automatically
+defined construction variables:
-.ES
-def spawn(shell, escape, cmd, args, env):
-.EE
-.IP
-.I sh
-is a string naming the shell program to use.
-.I escape
-is a function that can be called to escape shell special characters in
-the command line.
-.I cmd
-is the path to the command to be executed.
-.I args
-is that arguments to the command.
-.I env
-is a dictionary of the environment variables
-in which the command should be executed.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
'\"
-'\".IP SVN
-'\"The Subversion executable (usually named
-'\".BR svn ).
+'\" The descriptions below of the various SCons contruction variables
+'\" 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.
'\"
-'\".IP SVNCOM
-'\"The command line used to
-'\"fetch source files from a Subversion repository.
+'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.so variables.man
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
'\"
-'\".IP SVNFLAGS
-'\"General options that are passed to Subversion.
-
-.IP SWIG
-The scripting language wrapper and interface generator.
-
-.IP SWIGCFILESUFFIX
-The suffix that will be used for intermediate C
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-.BR _wrap$CFILESUFFIX .
-By default, this value is used whenever the
-.B -c++
-option is
-.I not
-specified as part of the
-.B SWIGFLAGS
-construction variable.
-
-.IP SWIGCOM
-The command line used to call
-the scripting language wrapper and interface generator.
-
-.IP SWIGCXXFILESUFFIX
-The suffix that will be used for intermediate C++
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-.BR _wrap$CFILESUFFIX .
-By default, this value is used whenever the
-.B -c++
-option is specified as part of the
-.B SWIGFLAGS
-construction variable.
-
-.IP SWIGFLAGS
-General options passed to
-the scripting language wrapper and interface generator.
-This is where you should set
-.BR -python ,
-.BR -perl5 ,
-.BR -tcl ,
-or whatever other options you want to specify to SWIG.
-If you set the
-.B -c++
-option in this variable,
-.B scons
-will, by default,
-generate a C++ intermediate source file
-with the extension that is specified as the
-.B $CXXFILESUFFIX
-variable.
-
-.IP TAR
-The tar archiver.
-
-.IP TARCOM
-The command line used to call the tar archiver.
-
-.IP TARFLAGS
-General options passed to the tar archiver.
-
-.IP TARGET
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP TARGETS
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP TARSUFFIX
-The suffix used for tar file names.
-
-.IP TEX
-The TeX formatter and typesetter.
-
-.IP TEXCOM
-The command line used to call the TeX formatter and typesetter.
-
-.IP TEXFLAGS
-General options passed to the TeX formatter and typesetter.
-
-.IP TOOLS
-A list of the names of the Tool specifications
-that are part of this construction environment.
-
-.IP WIN32_INSERT_DEF
-When this is set to true,
-a library build of a WIN32 shared library (.dll file)
-will also build a corresponding .def file at the same time,
-if a .def file is not already listed as a build target.
-The default is 0 (do not build a .def file).
-
-.IP WIN32DEFPREFIX
-The prefix used for WIN32 .def file names.
-
-.IP WIN32DEFSUFFIX
-The suffix used for WIN32 .def file names.
-
-.IP YACC
-The parser generator.
-
-.IP YACCCOM
-The command line used to call the parser generator
-to generate a source file.
-
-.IP YACCFLAGS
-General options passed to the parser generator.
-If $YACCFLAGS contains a \-d option,
-SCons assumes that the call will also create a .h file
-(if the yacc source file ends in a .y suffix)
-or a .hpp file
-(if the yacc source file ends in a .yy suffix)
-
-.IP ZIP
-The zip compression and file packaging utility.
-
-.IP ZIPCOM
-The command line used to call the zip utility,
-or the internal Python function used to create a
-zip archive.
-
-.IP ZIPCOMPRESSION
-The
-.I compression
-flag
-from the Python
-.B zipfile
-module used by the internal Python function
-to control whether the zip archive
-is compressed or not.
-The default value is
-.BR zipfile.ZIP_DEFLATED ,
-which creates a compressed zip archive.
-This value has no effect when using Python 1.5.2
-or if the
-.B zipfile
-module is otherwise unavailable.
-
-.IP ZIPFLAGS
-General options passed to the zip utility.
+'\" The descriptions above of the various SCons contruction variables
+'\" 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 CONSTRUCTION VARIABLE DESCRIPTIONS
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.LP
Construction variables can be retrieved and set using the
.EE
or when copying a construction environment using the
-.B Copy
+.B Clone
method:
.ES
-env2 = env.Copy(CC="cl.exe")
+env2 = env.Clone(CC="cl.exe")
.EE
.SS Configure Contexts
.B scons
does not maintain an explicit cache of the tested values,
but uses its normal dependency tracking to keep the checked values
-up to date.
+up to date. However, users may override this behaviour with the
+.B --config
+command line option.
+
The following methods can be used to perform checks:
.TP
-.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
+.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
This creates a configure context, which can be used to perform checks.
.I env
specifies the environment for building the tests.
.B BuildDir
method,
you may want to specify a subdirectory under your build directory.
+.I config_h
+specifies a C header file where the results of tests
+will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
+The default is to not write a
+.B config.h
+file.
+You can specify the same
+.B config.h
+file in multiple calls to Configure,
+in which case
+.B scons
+will concatenate all results in the specified file.
+Note that SCons
+uses its normal dependency checking
+to decide if it's necessary to rebuild
+the specified
+.I config_h
+file.
+This means that the file is not necessarily re-built each
+time scons is run,
+but is only rebuilt if its contents will have changed
+and some target that depends on the
+.I config_h
+file is being built.
.EE
A created
Returns 1 on success and 0 on failure.
.TP
-.RI Configure.CheckFunc( self ", " function_name ", [" language ])
+.RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
Checks if the specified
-C or C+++ function is available.
+C or C++ function is available.
.I function_name
is the name of the function to check for.
The optional
+.I header
+argument is a string
+that will be
+placed at the top
+of the test file
+that will be compiled
+to check if the function exists;
+the default is:
+.ES
+#ifdef __cplusplus
+extern "C"
+#endif
+char function_name();
+.EE
+The optional
.I language
argument should be
.B C
the default is "C".
.TP
-.RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
+.RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
Checks if
.I library
provides
in which case each library in the list
will be checked for
.IR symbol .
-The default
+If
.I symbol
-is "main",
-which just check if
+is not set or is
+.BR None ,
+then
+.BR Configure.CheckLib ()
+just checks if
you can link against the specified
.IR library .
The optional
The default value for
.I autoadd
is 1.
-It is assumed, that the C-language is used.
This method returns 1 on success and 0 on error.
.TP
.I language
may be one of 'C','c','CXX','cxx','C++' and 'c++'.
.I call
-can be any valid expression (with a trailing ';'). The default is 'main();'.
+can be any valid expression (with a trailing ';').
+If
+.I call
+is not set,
+the default simply checks that you
+can link against the specified
+.IR library .
.I autoadd
specifies whether to add the library to the environment (only if the check
succeeds). This method returns 1 on success and 0 on error.
.I help
is the help text for the variable.
.I default
-is the default value of the variable.
+is the default value of the variable;
+if the default value is
+.B None
+and there is no explicit value specified,
+the construction variable will
+.I not
+be added to the construction environment.
.I validator
is called to validate the value of the variable, and should take three
-arguments: key, value, and environment
+arguments: key, value, and environment.
+The recommended way to handle an invalid value is
+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. Example:
+should take either a value, or the value and environment, as parameters.
+The
+.I converter
+must return a value,
+which will be converted into a string
+before being validated by the
+.I validator
+(if any)
+and then added to the environment.
+
+Examples:
.ES
opts.Add('CC', 'The C compiler')
+
+def validate_color(key, val, env):
+ if not val in ['red', 'blue', 'yellow']:
+ raise "Invalid color value '%s'" % val
+opts.Add('COLOR', validator=valid_color)
.EE
.TP
env = Environment(options=opts)
.EE
+.IP
+The text file(s) that were specified
+when the Options object was created
+are executed as Python scripts,
+and the values of (global) Python variables set in the file
+are added to the construction environment.
+Example:
+
+.ES
+CC = 'my_cc'
+.EE
+
.TP
.RI Save( filename ", " env )
This saves the currently set options into a script file named
Help(opts.GenerateHelpText(env, sort=cmp))
.EE
-The text based SConscript file is executed as a Python script, and the
-global variables are queried for customizable construction
-variables. Example:
+.TP
+.RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
+This method returns a formatted string
+containing the printable help text
+for one option.
+It is normally not called directly,
+but is called by the
+.IR GenerateHelpText ()
+method to create the returned help text.
+It may be overridden with your own
+function that takes the arguments specified above
+and returns a string of help text formatted to your liking.
+Note that the
+.IR GenerateHelpText ()
+will not put any blank lines or extra
+characters in between the entries,
+so you must add those characters to the returned
+string if you want the entries separated.
.ES
-CC = 'my_cc'
+def my_format(env, opt, help, default, actual):
+ fmt = "\n%s: default=%s actual=%s (%s)\n"
+ return fmt % (opt, default. actual, help)
+opts.FormatOptionHelpText = my_format
.EE
To make it more convenient to work with customizable Options,
converted to lower case.
.TP
-.RI ListOption( key ", " help ", " default ", " names )
+.RI ListOption( key ", " help ", " default ", " names ", [", map ])
Return a tuple of arguments
to set up an option
whose value may be one or more
list.
More than one value may be specified,
with all values separated by commas.
+The default may be a string of
+comma-separated default values,
+or a list of the default values.
+The optional
+.I map
+argument is a dictionary
+that can be used to convert
+input values into specific legal values
+in the
+.I names
+list.
.TP
.RI PackageOption( key ", " help ", " default )
that is being enabled).
The option will also support the values
.BR no ,
-.BR flase ,
+.BR false ,
.BR off
or
.BR disable
to disable use of the specified option.
.TP
-.RI PathOption( key ", " help ", " default )
+.RI PathOption( key ", " help ", " default ", [" validator ])
Return a tuple of arguments
to set up an option
whose value is expected to be a path name.
and display the specified
.I help
text.
+An additional
+.I validator
+may be specified
+that will be called to
+verify that the specified path
+is acceptable.
+SCons supplies the
+following ready-made validators:
+.BR PathOption.PathExists
+(the default),
+which verifies that the specified path exists;
+.BR PathOption.PathIsFile ,
+which verifies that the specified path is an existing file;
+.BR PathOption.PathIsDir ,
+which verifies that the specified path is an existing directory;
+and
+.BR PathOption.PathIsDirCreate ,
+which verifies that the specified path is a directory,
+and will create the specified directory if the path does not exist.
+You may supply your own
+.I validator
+function,
+which must take three arguments
+.RI ( key ,
+the name of the options variable to be set;
+.IR val ,
+the specified value being checked;
+and
+.IR env ,
+the construction environment)
+and should raise an exception
+if the specified value is not acceptable.
.RE
These functions make it
'use X11 installed here (yes = search some places)',
'yes'),
PathOption('qtdir', 'where the root of Qt is installed', qtdir),
+ PathOption('foopath', 'where the foo library is installed', foopath,
+ PathOption.PathIsDir),
+
)
.EE
+.SS File and Directory Nodes
+
+The
+.IR File ()
+and
+.IR Dir ()
+functions return
+.I File
+and
+.I Dir
+Nodes, respectively.
+python objects, respectively.
+Those objects have several user-visible attributes
+and methods that are often useful:
+
+.IP path
+The build path
+of the given
+file or directory.
+This path is relative to the top-level directory
+(where the
+.B SConstruct
+file is found).
+The build path is the same as the source path if
+.I build_dir
+is not being used.
+
+.IP abspath
+The absolute build path of the given file or directory.
+
+.IP srcnode()
+The
+.IR srcnode ()
+method
+returns another
+.I File
+or
+.I Dir
+object representing the
+.I source
+path of the given
+.I File
+or
+.IR Dir .
+The
+
+.ES
+# Get the current build dir's path, relative to top.
+Dir('.').path
+# Current dir's absolute path
+Dir('.').abspath
+# Next line is always '.', because it is the top dir's path relative to itself.
+Dir('#.').path
+File('foo.c').srcnode().path # source path of the given source file.
+
+# Builders also return File objects:
+foo = env.Program('foo.c')
+print "foo will be built in %s"%foo.path
+.EE
+
.SH EXTENDING SCONS
.SS Builder Objects
.B scons
(CC, LINK, etc.).
Builder objects are created
-using the
+using the
.B Builder
function.
The
.IP prefix
The prefix that will be prepended to the target file name.
-This may be a simple string, or a callable object that takes
-two arguments, a construction environment and a list of sources,
-and returns a prefix.
+This may be specified as a:
+
+.RS 10
+.HP 6
+*
+.IR string ,
+
+.HP 6
+*
+.I callable object
+- a function or other callable that takes
+two arguments (a construction environment and a list of sources)
+and returns a prefix,
+
+.HP 6
+*
+.I dictionary
+- specifies a mapping from a specific source suffix (of the first
+source specified) to a corresponding target prefix. Both the source
+suffix and target prefix specifications may use environment variable
+substitution, and the target prefix (the 'value' entries in the
+dictionary) may also be a callable object. The default target prefix
+may be indicated by a dictionary entry with a key value of None.
+.RE
+.P
.ES
b = Builder("build_it < $SOURCE > $TARGET"
def gen_prefix(env, sources):
return "file-" + env['PLATFORM'] + '-'
-b = Builder("build_it < $SOURCE > $TARGET"
+b = Builder("build_it < $SOURCE > $TARGET",
prefix = gen_prefix)
+
+b = Builder("build_it < $SOURCE > $TARGET",
+ suffix = { None: "file-",
+ "$SRC_SFX_A": gen_prefix })
.EE
.IP suffix
The suffix that will be appended to the target file name.
-This may be a simple string, or a callable object that takes
-two arguments, a construction environment and a list of sources,
-and returns a suffix.
+This may be specified in the same manner as the prefix above.
If the suffix is a string, then
.B scons
-will append a '.' to the beginning of the
-suffix if it's not already there.
-The string returned by callable object
-is untouched and must append its own '.'
-to the beginning if one is desired.
+will append a '.' to the beginning of the suffix if it's not already
+there. The string returned by callable object (or obtained from the
+dictionary) is untouched and must append its own '.' to the beginning
+if one is desired.
.ES
b = Builder("build_it < $SOURCE > $TARGET"
- suffix = "file-"
+ suffix = "-file")
def gen_suffix(env, sources):
return "." + env['PLATFORM'] + "-file"
-b = Builder("build_it < $SOURCE > $TARGET"
+b = Builder("build_it < $SOURCE > $TARGET",
suffix = gen_suffix)
+
+b = Builder("build_it < $SOURCE > $TARGET",
+ suffix = { None: ".sfx1",
+ "$SRC_SFX_A": gen_suffix })
.EE
.IP src_suffix
-The expected source file name suffix.
+The expected source file name suffix. This may be a string or a list
+of strings.
.IP target_scanner
A Scanner object that
find things like
.B #include
lines in source files.
+The pre-built
+.B DirScanner
+Scanner object may be used to
+indicate that this Builder
+should scan directory trees
+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,
-for information about creating Scanner objects.)
+for information about creating your own Scanner objects.)
.IP target_factory
A factory function that the Builder will use
MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
env = Environment()
env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
-env.MakeDirectory('new_directory')
+env.MakeDirectory('new_directory', [])
.EE
+Note that the call to the MakeDirectory Builder
+needs to specify an empty source list
+to make the string represent the builder's target;
+without that, it would assume the argument is the source,
+and would try to deduce the target name from it,
+which in the absence of an automatically-added prefix or suffix
+would lead to a matching target and source name
+and a circular dependency.
+
.IP source_factory
A factory function that the Builder will use
to turn any sources specified as strings into SCons Nodes.
emitter = {'.suf1' : e_suf1,
'.suf2' : e_suf2})
.EE
-.IP
-The
-.I generator
-and
-.I action
-arguments must not both be used for the same Builder.
.IP multi
Specifies whether this builder is allowed to be called multiple times for
b = Builder(generator=g)
.EE
+.IP
+The
+.I generator
+and
+.I action
+arguments must not both be used for the same Builder.
+
.IP src_builder
Specifies a builder to use when a source file name suffix does not match
any of the suffixes of the builder. Using this argument produces a
.I action
arguments must not both be used for the same Builder.
+.IP source_ext_match
+When the specified
+.I action
+argument is a dictionary,
+the default behavior when a builder is passed
+multiple source files is to make sure that the
+extensions of all the source files match.
+If it is legal for this builder to be
+called with a list of source files with different extensions,
+this check can be suppressed by setting
+.B source_ext_match
+to
+.B None
+or some other non-true value.
+When
+.B source_ext_match
+is disable,
+.B scons
+will use the suffix of the first specified
+source file to select the appropriate action from the
+.I action
+dictionary.
+
+In the following example,
+the setting of
+.B source_ext_match
+prevents
+.B scons
+from exiting with an error
+due to the mismatched suffixes of
+.B foo.in
+and
+.BR foo.extra .
+
+.ES
+b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
+ source_ext_match = None)
+
+env = Environment(BUILDERS = {'MyBuild':b})
+env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
+.EE
+
.IP env
A construction environment that can be used
to fetch source code using this Builder.
env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
.EE
+.IP chdir
+A directory from which scons
+will execute the
+action(s) specified
+for this Builder.
+If the
+.B chdir
+argument is
+a string or a directory Node,
+scons will change to the specified directory.
+If the
+.B chdir
+is not a string or Node
+and is non-zero,
+then scons will change to the
+target file's directory.
+
+Note that scons will
+.I not
+automatically modify
+its expansion of
+construction variables like
+.B $TARGET
+and
+.B $SOURCE
+when using the chdir
+keyword argument--that is,
+the expanded file names
+will still be relative to
+the top-level SConstruct directory,
+and consequently incorrect
+relative to the chdir directory.
+Builders created using chdir keyword argument,
+will need to use construction variable
+expansions like
+.B ${TARGET.file}
+and
+.B ${SOURCE.file}
+to use just the filename portion of the
+targets and source.
+
+.ES
+b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
+ chdir=1)
+env = Environment(BUILDERS = {'MyBuild' : b})
+env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
+.EE
+
+.B WARNING:
+Python only keeps one current directory
+location for all of the threads.
+This means that use of the
+.B chdir
+argument
+will
+.I not
+work with the SCons
+.B -j
+option,
+because individual worker threads spawned
+by SCons interfere with each other
+when they start changing directory.
+
.RE
Any additional keyword arguments supplied
when a Builder object is created
.IP String
If the first argument is a string,
a command-line Action is returned.
+Note that the command line string
+may be preceded by an
+.B @
+(at-sign)
+to suppress printing of the
+specified command line,
+or by a
+.B \-
+(hyphen)
+to ignore the exit status from
+the specified command.
+Examples:
.ES
Action('$CC -c -o $TARGET $SOURCES')
+
+# Doesn't print the line being executed.
+Action('@build $TARGET $SOURCES')
+
+# Ignores
+Action('-build $TARGET $SOURCES')
.EE
.\" XXX From Gary Ruben, 23 April 2002:
a = Action(build_it)
.EE
+If the action argument is not one of the above,
+None is returned.
+.PP
+
The second, optional argument
-is a Python function that returns
+is used to define the output which is printed
+when the Action is actually performed.
+In the absence of this parameter, or if it's an
+empty string, a default output depending on the type of the action
+is used. For example, a command-line action will print
+the executed command. The argument is either a python function
+or a string.
+
+In the first case, it's a function that returns
a string to be printed to describe the action being executed.
Like a function to build a file,
this function takes three arguments:
.B source
arguments may be lists of Node objects if there is
more than one target file or source file.
+
+In the second case, you provide the string itself.
+The string typically contains variables, notably
+$TARGET(S) and $SOURCE(S), or consists of just a single
+variable, which is optionally defined somewhere else.
+SCons itself heavily uses the latter variant.
+
Examples:
.ES
return "building '%s' from '%s'" % (target[0], source[0])
# Use a positional argument.
-a = Action(build_it, string_it)
+f = Action(build_it, string_it)
+s = Action(build_it, "building '$TARGET' from '$SOURCE'")
# Alternatively, use a keyword argument.
-a = Action(build_it, strfunction=string_it)
+f = Action(build_it, strfunction=string_it)
+s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
+
+# You can provide a configurable variable.
+l = Action(build_it, '$STRINGIT')
.EE
The third, also optional argument
open(target[0], 'w').write(env['XXX'])
return 0
-def string_it(target, source):
- return "building '%s' from '%s'" % (target[0], source[0])
-
# Use positional arguments.
-a = Action(build_it, string_it, ['XXX'])
+a = Action(build_it, '$STRINGIT', ['XXX'])
# Alternatively, use a keyword argument.
a = Action(build_it, varlist=['XXX'])
.EE
-.PP
-If the action argument is not one of the above,
-None is returned.
+
+The
+.BR Action ()
+global function
+also takes a
+.B chdir
+keyword argument
+which specifies that
+scons will execute the action
+after changing to the specified directory.
+If the chdir argument is
+a string or a directory Node,
+scons will change to the specified directory.
+If the chdir argument
+is not a string or Node
+and is non-zero,
+then scons will change to the
+target file's directory.
+
+Note that scons will
+.I not
+automatically modify
+its expansion of
+construction variables like
+.B $TARGET
+and
+.B $SOURCE
+when using the chdir
+keyword argument--that is,
+the expanded file names
+will still be relative to
+the top-level SConstruct directory,
+and consequently incorrect
+relative to the chdir directory.
+Builders created using chdir keyword argument,
+will need to use construction variable
+expansions like
+.B ${TARGET.file}
+and
+.B ${SOURCE.file}
+to use just the filename portion of the
+targets and source.
+
+.ES
+a = Action("build < ${SOURCE.file} > ${TARGET.file}",
+ chdir=1)
+.EE
+
+The
+.BR Action ()
+global function
+also takes an
+.B exitstatfunc
+keyword argument
+which specifies a function
+that is passed the exit status
+(or return value)
+from the specified action
+and can return an arbitrary
+or modified value.
+This can be used, for example,
+to specify that an Action object's
+return value should be ignored
+and SCons should, therefore,
+consider that the action always suceeds:
+
+.ES
+def always_succeed(s):
+ # Always return 0, which indicates success.
+ return 0
+a = Action("build < ${SOURCE.file} > ${TARGET.file}",
+ exitstatfunc=always_succeed)
+.EE
.SS Miscellaneous Action Functions
env = Environment(TMPBUILD = '/tmp/builddir')
env.Command('foo.out', 'foo.in',
[Mkdir('$TMPBUILD'),
- Copy('${SOURCE.dir}', '$TMPBUILD')
+ Copy('$TMPBUILD', '${SOURCE.dir}'),
"cd $TMPBUILD && make",
Delete('$TMPBUILD')])
.EE
.EE
.TP
-.RI Delete( entry )
+.RI Delete( entry ", [" must_exist ])
Returns an Action that
deletes the specified
.IR entry ,
If a directory is specified,
the entire directory tree
will be removed.
+If the
+.I must_exist
+flag is set,
+then a Python error will be thrown
+if the specified entry does not exist;
+the default is
+.BR must_exist=0 ,
+that is, the Action will silently do nothing
+if the entry does not exist.
Examples:
.ES
env.Command('foo.out', 'foo.in',
[Delete('${TARGET.dir}'),
MyBuildAction])
+
+Execute(Delete('file_that_must_exist', must_exist=1))
.EE
.TP
.B /
(forward slashes)
not backslashes.
-This is sometimes necessary on Win32 systems
+This is sometimes necessary on Windows systems
when a path references a file on other (POSIX) systems.
.IP srcpath
${TARGET.suffix} => .x
${TARGET.abspath} => /top/dir/sub/dir/file.x
-BuildDir('sub/dir','src')
+SConscript('src/SConscript', build_dir='sub/dir')
$SOURCE => sub/dir/file.x
${SOURCE.srcpath} => src/file.x
${SOURCE.srcdir} => src
${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:
to fetch the name of the file, and
.B node.get_contents()
to fetch contents of the file.
+Note that the file is
+.I not
+guaranteed to exist before the scanner is called,
+so the scanner function should check that
+if there's any chance that the scanned file
+might not exist
+(for example, if it's built from other files).
The
.B env
into a list by the current environment.
.IP path_function
-A Python function that takes
-two or three arguments:
-a construction environment, directory Node,
-and optional argument supplied
+A Python function that takes four or five arguments:
+a construction environment,
+a Node for the directory containing
+the SConscript file in which
+the first target was defined,
+a list of target nodes,
+a list of source nodes,
+and an optional argument supplied
when the scanner was created.
The
.B path_function
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
and not (for example) also on the files
specified by the #include lines
in the file being scanned.
+.I recursive
+may be a callable function,
+in which case it will be called with a list of
+Nodes found and
+should return a list of Nodes
+that should be scanned recursively;
+this can be used to select a specific subset of
+Nodes for additional scanning.
+
+Note that
+.B scons
+has a global
+.B SourceFileScanner
+object that is used by
+the
+.BR Object (),
+.BR SharedObject (),
+and
+.BR StaticObject ()
+builders to decide
+which scanner should be used
+for different file extensions.
+You can using the
+.BR SourceFileScanner.add_scanner ()
+method to add your own Scanner object
+to the
+.B scons
+infrastructure
+that builds target programs or
+libraries from a list of
+source files of different types:
+
+.ES
+def xyz_scan(node, env, path):
+ contents = node.get_contents()
+ # Scan the contents and return the included files.
+
+XYZScanner = Scanner(xyz_scan)
+
+SourceFileScanner.add_scanner('.xyx', XYZScanner)
+
+env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
+.EE
.SH SYSTEM-SPECIFIC BEHAVIOR
SCons and its configuration files are very portable,
suffix as a Fortran source file that should
.I not
be run through the C preprocessor.
-.SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
+.SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
Cygwin supplies a set of tools and utilities
that let users work on a
Windows system using a more POSIX-like environment.
(or some other Windows compiler)
use the python.org or ActiveState version of Python
to run SCons.
-.SS WIN32: scons.bat file
-On WIN32 systems,
+.SS Windows: scons.bat file
+On Windows systems,
SCons is executed via a wrapper
.B scons.bat
file.
.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
+'\" Note: the \\ in the following are for the benefit of nroff/troff,
+'\" not inappropriate doubled escape characters within the r'' raw string.
include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
def kfile_scan(node, env, path, arg):
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
.SS Building Multiple Variants From the Same Source
-Use the BuildDir() method to establish
+Use the build_dir keyword argument to
+the SConscript function to establish
one or more separate build directories for
-a given source directory,
-then use the SConscript() method
-to specify the SConscript files
-in the build directories:
+a given source directory:
.ES
SConstruct:
- ccflags = '-DFOO'
- Export("ccflags")
- BuildDir('foo', 'src')
- SConscript('foo/SConscript')
+ cppdefines = ['FOO']
+ Export("cppdefines")
+ SConscript('src/SConscript', build_dir='foo')
- ccflags = '-DBAR'
- Export("ccflags")
- BuildDir('bar', 'src')
- SConscript('bar/SConscript')
+ cppdefines = ['BAR']
+ Export("cppdefines")
+ SConscript('src/SConscript', build_dir='bar')
src/SConscript:
- Import("ccflags")
- env = Environment(CCFLAGS = ccflags)
+ Import("cppdefines")
+ env = Environment(CPPDEFINES = cppdefines)
env.Program(target = 'src', source = 'src.c')
.EE
Note the use of the Export() method
-to set the "ccflags" variable to a different
-value for each variant build.
+to set the "cppdefines" variable to a different
+value each time we call the SConscript function.
.SS Hierarchical Build of Two Libraries Linked With a Program
Main/SConscript:
Import('env')
- e = env.Copy(LIBS = ['a', ','b'])
+ e = env.Copy(LIBS = ['a', 'b'])
e.Program('foo', Split('m1.c m2.c m3.c'))
.EE
projects / scons.git / blobdiff