.\"
.\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
.\"
+.TH SCONS 1 "__MONTH_YEAR__"
.\" ES - Example Start - indents and turns off line fill
+.rm ES
.de ES
.RS
.nf
..
.\" EE - Example End - ends indent and turns line fill back on
+.rm EE
.de EE
.fi
.RE
..
-.TH SCONS 1 "__MONTH_YEAR__"
.SH NAME
scons \- a software construction tool
.SH SYNOPSIS
]
.SH DESCRIPTION
-The
-.B scons
+The
+.B scons
utility builds software (or other files) by determining which
component pieces must be rebuilt and executing the necessary commands to
rebuild them.
-By default,
-.B scons
-searches for a file named
+By default,
+.B scons
+searches for a file named
.IR SConstruct ,
.IR Sconstruct ,
or
(in that order) in the current directory and reads its
configuration from the first file found.
An alternate file name may be
-specified via the
+specified via the
.B -f
option.
can scan known input files automatically for dependency
information (for example, #include statements
in C or C++ files) and will rebuild dependent files appropriately
-whenever any "included" input file changes.
+whenever any "included" input file changes.
.B scons
supports the
ability to define new scanners for unknown input file types.
in which case only the specified targets will be built
(along with any derived files on which they depend).
-Specifying "cleanup" targets in SConscript files is not
-necessary. The
+Specifying "cleanup" targets in SConscript files is not usually necessary.
+The
.B -c
flag removes all files
necessary to build the specified target:
function.
A subset of a hierarchical tree may be built by
-remaining at the top-level directory (where the
+remaining at the top-level directory (where the
.I SConstruct
file lives) and specifying the subdirectory as the target to be
built:
or by changing directory and invoking scons with the
.B -u
option, which traverses up the directory
-hierarchy until it finds the
+hierarchy until it finds the
.I SConstruct
file, and then builds
targets relatively to the current subdirectory:
.B scons
can maintain a cache of target (derived) files that can
be shared between multiple builds. When caching is enabled in a
-SConscript file, any target files built by
+SConscript file, any target files built by
.B scons
will be copied
to the cache. If an up-to-date target file is found in the cache, it
will be retrieved from the cache instead of being rebuilt locally.
Caching behavior may be disabled and controlled in other ways by the
-.BR --cache-force ,
+.BR --cache-force ,
.BR --cache-disable ,
and
.B --cache-show
and the PharLap ETS compiler.
On OS/2 systems,
.B scons
-searches in order for the
+searches in order for the
OS/2 compiler,
the GCC tool chain,
and the Microsoft Visual C++ tools,
Environment construction variables.
.SH OPTIONS
-In general,
-.B scons
+In general,
+.B scons
supports the same command-line options as GNU
-.BR make ,
-and many of those supported by
+.BR make ,
+and many of those supported by
.BR cons .
.TP
and a necessary test does not
yet have any results in the cache.
-.TP
+.TP
.RI "-C" " directory" ", --directory=" directory
-Change to the specified
+Change to the specified
.I directory
-before searching for the
+before searching for the
.IR SConstruct ,
.IR Sconstruct ,
or
.I sconstruct
file, or doing anything
-else. Multiple
+else. Multiple
.B -C
options are interpreted
relative to the previous one, and the right-most
.B -C
option wins. (This option is nearly
-equivalent to
+equivalent to
.BR "-f directory/SConstruct" ,
except that it will search for
.IR SConstruct ,
-.IR Sconstruct ,
+.IR Sconstruct ,
or
.I sconstruct
in the specified directory.)
.TP
--debug=includes
-Print the include tree after each top-level target is built.
+Print the include tree after each top-level target is built.
This is generally used to find out what files are included by the sources
of a given derived file:
$ scons --debug=presub
Building myprog.o with action(s):
$SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
-...
+\&...
.EE
.TP
.TP
.RI --duplicate= ORDER
There are three ways to duplicate files in a build tree: hard links,
-soft (symbolic) links and copies. The default behaviour of SCons is to
+soft (symbolic) links and copies. The default behaviour of SCons is to
prefer hard links to soft links to copies. You can specify different
behaviours with this option.
-.IR ORDER
-must be one of
+.IR ORDER
+must be one of
.IR hard-soft-copy
(the default),
.IR soft-hard-copy ,
.TP
.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
-Use
-.I file
+Use
+.I file
as the initial SConscript file.
-.TP
+.TP
-h, --help
Print a local help message for this build, if one is defined in
-the SConscript file(s), plus a line that describes the
+the SConscript file(s), plus a line that describes the
.B -H
option for command-line option help. If no local help message
is defined, prints the standard help message about command-line
-i, --ignore-errors
Ignore all errors from commands executed to rebuild files.
-.TP
+.TP
.RI -I " directory" ", --include-dir=" directory
-Specifies a
+Specifies a
.I directory
to search for
-imported Python modules. If several
+imported Python modules. If several
.B -I
options
are used, the directories are searched in the order specified.
--implicit-deps-unchanged
Force SCons to ignore changes in the implicit dependencies.
This causes cached implicit dependencies to always be used.
-This implies
+This implies
.BR --implicit-cache .
+.TP
+--interactive
+Starts SCons in interactive mode.
+The SConscript files are read once and a
+.B "scons>>>"
+prompt is printed.
+Targets may now be rebuilt by typing commands at interactive prompt
+without having to re-read the SConscript files
+and re-initialize the dependency graph from scratch.
+
+SCons interactive mode supports the following commands:
+
+.RS 10
+.TP 6
+.BI build "[OPTIONS] [TARGETS] ..."
+Builds the specified
+.I TARGETS
+(and their dependencies)
+with the specified
+SCons command-line
+.IR OPTIONS .
+.B b
+and
+.B scons
+are synonyms.
+
+The following SCons command-line options affect the
+.B build
+command:
+
+.ES
+--cache-debug=FILE
+--cache-disable, --no-cache
+--cache-force, --cache-populate
+--cache-show
+--debug=TYPE
+-i, --ignore-errors
+-j N, --jobs=N
+-k, --keep-going
+-n, --no-exec, --just-print, --dry-run, --recon
+-Q
+-s, --silent, --quiet
+--taskmastertrace=FILE
+--tree=OPTIONS
+.EE
+
+.IP "" 6
+Any other SCons command-line options that are specified
+do not cause errors
+but have no effect on the
+.B build
+command
+(mainly because they affect how the SConscript files are read,
+which only happens once at the beginning of interactive mode).
+
+.TP 6
+.BI clean "[OPTIONS] [TARGETS] ..."
+Cleans the specified
+.I TARGETS
+(and their dependencies)
+with the specified options.
+.B c
+is a synonym.
+This command is itself a synonym for
+.B "build --clean"
+
+.TP 6
+.BI exit
+Exits SCons interactive mode.
+You can also exit by terminating input
+(CTRL+D on UNIX or Linux systems,
+CTRL+Z on Windows systems).
+
+.TP 6
+.BI help "[COMMAND]"
+Provides a help message about
+the commands available in SCons interactive mode.
+If
+.I COMMAND
+is specified,
+.B h
+and
+.B ?
+are synonyms.
+
+.TP 6
+.BI shell "[COMMANDLINE]"
+Executes the specified
+.I COMMANDLINE
+in a subshell.
+If no
+.I COMMANDLINE
+is specified,
+executes the interactive command interpreter
+specified in the
+.B SHELL
+environment variable
+(on UNIX and Linux systems)
+or the
+.B COMSPEC
+environment variable
+(on Windows systems).
+.B sh
+and
+.B !
+are synonyms.
+
+.TP 6
+.B version
+Prints SCons version information.
+.RE
+
+.IP
+An empty line repeats the last typed command.
+Command-line editing can be used if the
+.B readline
+module is available.
+
+.ES
+$ scons --interactive
+scons: Reading SConscript files ...
+scons: done reading SConscript files.
+scons>>> build -n prog
+scons>>> exit
+.EE
+
.TP
.RI -j " N" ", --jobs=" N
Specifies the number of jobs (commands) to run simultaneously.
-If there is more than one
-.B -j
+If there is more than one
+.B -j
option, the last one is effective.
-.\" ??? If the
-.\" .B -j
+.\" ??? If the
+.\" .B -j
.\" option
.\" is specified without an argument,
-.\" .B scons
+.\" .B scons
.\" will not limit the number of
.\" simultaneous jobs.
.\" .RI -l " N" ", --load-average=" N ", --max-load=" N
.\" No new jobs (commands) will be started if
.\" there are other jobs running and the system load
-.\" average is at least
+.\" average is at least
.\" .I N
.\" (a floating-point number).
.TP
.RI --max-drift= SECONDS
-Set the maximum expected drift in the modification time of files to
+Set the maximum expected drift in the modification time of files to
.IR SECONDS .
This value determines how long a file must be unmodified
before its cached content signature
No execute. Print the commands that would be executed to build
any out-of-date target files, but do not execute the commands.
-.TP
+.TP
.RI --no-site-dir
Prevents the automatic addition of the standard
.I site_scons
.\" .TP
.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
-.\" Do not rebuild
+.\" Do not rebuild
.\" .IR file ,
.\" and do
.\" not rebuild anything due to changes in the contents of
.\" .IR file .
-.\" .TP
+.\" .TP
.\" .RI --override " file"
.\" Read values to override specific build environment variables
-.\" from the specified
+.\" from the specified
.\" .IR file .
.\" .TP
.\" -p
.\" After printing, a normal build is performed
.\" as usual, as specified by other command-line options.
.\" This also prints version information
-.\" printed by the
+.\" printed by the
.\" .B -v
.\" option.
.\"
.TP
-S, --no-keep-going, --stop
-Ignored for compatibility with GNU
+Ignored for compatibility with GNU
.BR make .
-.TP
+.TP
.RI --site-dir= dir
Uses the named dir as the site dir rather than the default
.I site_scons
.IR dir /site_tools
will get added to the default toolpath.
+.TP
+.RI --stack-size= KILOBYTES
+Set the size stack used to run threads to
+.IR KILOBYTES .
+This value determines the stack size of the threads used to run jobs.
+These are the threads that execute the actions of the builders for the
+nodes that are out-of-date.
+Note that this option has no effect unless the
+.B num_jobs
+option, which corresponds to -j and --jobs, is larger than one. Using
+a stack size that is too small may cause stack overflow errors. This
+usually shows up as segmentation faults that cause scons to abort
+before building anything. Using a stack size that is too large will
+cause scons to use more memory than required and may slow down the entire
+build process.
+
+The default value is to use a stack size of 256 kilobytes, which should
+be appropriate for most uses. You should not need to increase this value
+unless you encounter stack overflow errors.
+
.TP
-t, --touch
Ignored for compatibility with GNU
-.BR make .
+.BR make .
(Touching a file to make it
-appear up-to-date is unnecessary when using
+appear up-to-date is unnecessary when using
.BR scons .)
.TP
.TP
-u, --up, --search-up
-Walks up the directory structure until an
+Walks up the directory structure until an
.I SConstruct ,
.I Sconstruct
-or
+or
.I sconstruct
file is found, and uses that
as the top of the directory tree.
.TP
-v, --version
-Print the
+Print the
.B scons
version, copyright information,
list of authors, and any other relevant information.
.TP
--warn=deprecated, --warn=no-deprecated
-Enables or disables warnings about use of deprecated features.
+Enables or disables all warnings about use of deprecated features.
These warnings are enabled by default.
+Warnings for some specific deprecated features
+may be enabled or disabled individually;
+see below.
+
+--warn=deprecated-copy, --warn=no-deprecated-copy
+Enables or disables warnings about use of the deprecated
+.B env.Copy()
+method.
+
+--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
+Enables or disables warnings about use of the deprecated
+SourceSignatures() function
+or
+.B env.SourceSignatures()
+method.
+
+--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
+Enables or disables warnings about use of the deprecated
+TargetSignatures() function
+or
+.B env.TargetSignatures()
+method.
.TP
--warn=duplicate-environment, --warn=no-duplicate-environment
-Enables or disables warnings about missing SConscript files.
+Enables or disables warnings about attempts to specify a build
+of a target with two different construction environments
+that use the same action.
+These warnings are enabled by default.
+
+.TP
+--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
+Enables or disables the specific warning about linking
+Fortran and C++ object files in a single executable,
+which can yield unpredictable behavior with some compilers.
+
+.TP
+--warn=link, --warn=no-link
+Enables or disables warnings about link steps.
.TP
--warn=misleading-keywords, --warn=no-misleading-keywords
.TP
--warn=missing-sconscript, --warn=no-missing-sconscript
-Enables or disables warnings about attempts to specify a build
-of a target with two different construction environments
-that use the same action.
+Enables or disables warnings about missing SConscript files.
These warnings are enabled by default.
.TP
option is used.
These warnings are enabled by default.
+.TP
+--warn=no-object-count, --warn=no-no-object-count
+Enables or disables warnings about the
+.B --debug=object
+feature not working when
+.B scons
+is run with the python
+.B \-O
+option or from optimized Python (.pyo) modules.
+
.TP
--warn=no-parallel-support, --warn=no-no-parallel-support
Enables or disables warnings about the version of Python
option is used.
These warnings are enabled by default.
+.TP
+--warn=python-version, --warn=no-python-version
+Enables or disables the warning about running
+SCons with a deprecated version of Python.
+These warnings are enabled by default.
+
.TP
--warn=reserved-variable, --warn=no-reserved-variable
Enables or disables warnings about attempts to set the
.BR SOURCES .
These warnings are disabled by default.
+.TP
+--warn=stack-size, --warn=no-stack-size
+Enables or disables warnings about requests to set the stack size
+that could not be honored.
+These warnings are enabled by default.
+
.\" .TP
.\" .RI --write-filenames= file
.\" Write all filenames considered into
.\"
.\" .TP
.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
-.\" Pretend that the target
-.\" .I file
+.\" Pretend that the target
+.\" .I file
.\" has been
-.\" modified. When used with the
+.\" modified. When used with the
.\" .B -n
.\" option, this
.\" show you what would be rebuilt if you were to modify that file.
-.\" Without
+.\" Without
.\" .B -n
.\" ... what? XXX
.\"
.\" --warn-undefined-variables
.\" Warn when an undefined variable is referenced.
-.TP
+.TP
.RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
Search the specified repository for any input and target
files not found in the local directory hierarchy. Multiple
.B -Y
-options may specified, in which case the
+options may be specified, in which case the
repositories are searched in the order specified.
.SH CONFIGURATION FILE REFERENCE
.\" XXX Adding this in the future would be a help.
.SS Construction Environments
A construction environment is the basic means by which the SConscript
-files communicate build information to
+files communicate build information to
.BR scons .
-A new construction environment is created using the
-.B Environment
+A new construction environment is created using the
+.B Environment
function:
.ES
env = Environment()
.EE
+Variables, called
+.I construction
+.IR variables ,
+may be set in a construction environment
+either by specifying them as keywords when the object is created
+or by assigning them a value after the object is created:
+
+.ES
+env = Environment(FOO = 'foo')
+env['BAR'] = 'bar'
+.EE
+
+As a convenience,
+construction variables may also be set or modified by the
+.I parse_flags
+keyword argument, which applies the
+.B ParseFlags
+method (described below) to the argument value
+after all other processing is completed.
+This is useful either if the exact content of the flags is unknown
+(for example, read from a control file)
+or if the flags are distributed to a number of construction variables.
+
+.ES
+env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
+.EE
+
+This example adds 'include' to
+.BR CPPPATH ,
+\'EBUG' to
+.BR CPPDEFINES ,
+and 'm' to
+.BR LIBS .
+
By default, a new construction environment is
initialized with a set of builder methods
and construction variables that are appropriate
This is so that any executed commands
that use sockets to connect with other systems
(such as fetching source files from
-external CVS repository specifications like
+external CVS repository specifications like
.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
will work on Windows systems.
Additionally, a specific set of tools
with which to initialize the environment
-may specified as an optional keyword argument:
+may be specified as an optional keyword argument:
.ES
env = Environment(tools = ['msvc', 'lex'])
g77
gas
gcc
+gfortran
gnulink
gs
hpc++
sunar
sunc++
suncc
+sunf77
+sunf90
+sunf95
sunlink
swig
tar
environment's builder methods.
The arguments to the builder methods are
.B target
-(a list of target files)
+(a list of targets to be built,
+usually file names)
and
.B source
-(a list of source files).
+(a list of sources to be built,
+usually file names).
Because long lists of file names
can lead to a lot of quoting,
env.Program('bar', source = string.split('bar.c foo.c'))
.EE
+Target and source file names
+that are not absolute path names
+(that is, do not begin with
+.B /
+on POSIX systems
+or
+.B \\
+on Windows systems,
+with or without
+an optional drive letter)
+are interpreted relative to the directory containing the
+.B SConscript
+file being read.
+An initial
+.B #
+(hash mark)
+on a path name means that the rest of the file name
+is interpreted relative to
+the directory containing
+the top-level
+.B SConstruct
+file,
+even if the
+.B #
+is followed by a directory separator character
+(slash or backslash).
+
+Examples:
+
+.ES
+# The comments describing the targets that will be built
+# assume these calls are in a SConscript file in the
+# a subdirectory named "subdir".
+
+# Builds the program "subdir/foo" from "subdir/foo.c":
+env.Program('foo', 'foo.c')
+
+# Builds the program "/tmp/bar" from "subdir/bar.c":
+env.Program('/tmp/bar', 'bar.c')
+
+# An initial '#' or '#/' are equivalent; the following
+# calls build the programs "foo" and "bar" (in the
+# top-level SConstruct directory) from "subdir/foo.c" and
+# "subdir/bar.c", respectively:
+env.Program('#foo', 'foo.c')
+env.Program('#/bar', 'bar.c')
+
+# Builds the program "other/foo" (relative to the top-level
+# SConstruct directory) from "subdir/foo.c":
+env.Program('#other/foo', 'foo.c')
+.EE
+
When the target shares the same base name
as the source and only the suffix varies,
and if the builder method has a suffix defined for the target file type,
executable program
.B bar
(on POSIX systems)
-or
+or
.B bar.exe
(on Windows systems)
from the bar.c source file:
for dependencies on the non-standard library names;
see the descriptions of these variables, below, for more information.)
+It is also possible to use the
+.I parse_flags
+keyword argument in an override:
+
+.ES
+env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
+.EE
+
+This example adds 'include' to
+.BR CPPPATH ,
+\'EBUG' to
+.BR CPPDEFINES ,
+and 'm' to
+.BR LIBS .
+
Although the builder methods defined by
.B scons
are, in fact,
from SCons.Script import *
.EE
-All builder methods return a list of Nodes
-that represent the target or targets that will be built.
+All builder methods return a list-like object
+containing Nodes that
+represent the target or targets that will be built.
A
.I Node
is an internal SCons object
which represents
build targets or sources.
-The returned Node(s)
+The returned Node-list object
can be passed to other builder methods as source(s)
or passed to any SCons function or method
where a filename would normally be accepted.
Or you can use the
.BR Flatten ()
-supplied by scons
+function supplied by scons
to create a list containing just the Nodes,
which may be more convenient:
print str(object)
.EE
+Note also that because Builder calls return
+a list-like object, not an actual Python list,
+you should
+.I not
+use the Python
+.B +=
+operator to append Builder results to a Python list.
+Because the list and the object are different types,
+Python will not update the original list in place,
+but will instead create a new Node-list object
+containing the concatenation of the list
+elements and the Builder results.
+This will cause problems for any other Python variables
+in your SCons configuration
+that still hold on to a reference to the original list.
+Instead, use the Python
+.B .extend()
+method to make sure the list is updated in-place.
+Example:
+
+.ES
+object_files = []
+
+# Do NOT use += as follows:
+#
+# object_files += Object('bar.c')
+#
+# It will not update the object_files list in place.
+#
+# Instead, use the .extend() method:
+object_files.extend(Object('bar.c'))
+
+.EE
+
The path name for a Node's file may be used
by passing the Node to the Python-builtin
.B str()
'\" END GENERATED BUILDER DESCRIPTIONS
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.P
All
targets of builder methods automatically depend on their sources.
An explicit dependency can
-be specified using the
-.B Depends
+be specified using the
+.B Depends
method of a construction environment (see below).
In addition,
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 ()
+Scanner object used by the
+.BR Object (),
+.BR StaticObject (),
and
.BR SharedObject ()
Builders by adding them
Except where otherwise noted,
the same-named
construction environment method
-and global function
+and global function
provide the exact same functionality.
The only difference is that,
where appropriate,
substitute construction variables into
any supplied strings.
For example:
+
.ES
env = Environment(FOO = 'foo')
Default('$FOO')
env.Default('$FOO')
.EE
+
+In the above example,
the first call to the global
.B Default()
function will actually add a target named
include:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Action( action ", [" strfunction ", " varlist ])
.TP
.RI env.Action( action ", [" strfunction ", " varlist ])
See the section "Action Objects,"
below, for a complete explanation of the arguments and behavior.
-Note that the
+Note that the
.BR env.Action ()
form of the invocation will expand
construction variables in any arguments strings,
until the Action object is actually used.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI AddMethod( object, function ", [" name ])
.TP
.RI env.AddMethod( function ", [" name ])
to indicate that the specified long option(s) take(s) an
.I optional
argument.
-When
+When
.B "nargs = '?'"
is passed to the
.BR AddOption ()
.BR GetOption ()
or
.BR env.GetOption ().
-The value may also be set, using
-.BR SetOption ()
-or
-.BR env.SetOption (),
-if conditions in a
-.B SConscript
-require overriding any default value.
-Note, however, that a
-value specified on the command line will
-.I always
-override a value set by any SConscript file.
+\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
+\" Uncomment this when that works. See tigris issue 2105.
+\" The value may also be set, using
+\" .BR SetOption ()
+\" or
+\" .BR env.SetOption (),
+\" if conditions in a
+\" .B SConscript
+\" require overriding any default value.
+\" Note, however, that a
+\" value specified on the command line will
+\" .I always
+\" override a value set by any SConscript file.
Any specified
.B help=
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI AddPostAction( target ", " action )
.TP
.RI env.AddPostAction( target ", " action )
can be converted into an Action object
(see below).
+When multiple targets are supplied,
+the action may be called multiple times,
+once after each action that generates
+one or more targets in the list.
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI AddPreAction( target ", " action )
.TP
.RI env.AddPreAction( target ", " action )
can be converted into an Action object
(see below).
+When multiple targets are specified,
+the action(s) may be called multiple times,
+once before each action that generates
+one or more targets in the list.
+
+Note that if any of the targets are built in multiple steps,
+the action will be invoked just
+before the "final" action that specifically
+generates the specified target(s).
+For example, when building an executable program
+from a specified source
+.B .c
+file via an intermediate object file:
+
+.ES
+foo = Program('foo.c')
+AddPreAction(foo, 'pre_action')
+.EE
+
+The specified
+.B pre_action
+would be executed before
+.B scons
+calls the link command that actually
+generates the executable program binary
+.BR foo ,
+not before compiling the
+.B foo.c
+file into an object file.
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Alias( alias ", [" targets ", [" action ]])
.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
.TP
.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
-This specifies a build directory
-.I build_dir
-in which to build all derived files
-that would normally be built under
-.IR src_dir .
-Multiple build directories can be set up for multiple build variants, for
-example.
-.I src_dir
-must be underneath the SConstruct file's directory,
+Synonyms for
+.BR VariantDir ()
and
+.BR env.VariantDir ().
+The
.I build_dir
-may not be underneath the
-.I src_dir .
-
-The default behavior is for
-.B scons
-to duplicate all of the files in the tree underneath
-.I src_dir
-into
-.IR build_dir ,
-and then build the derived files within the copied tree.
-(The duplication is performed by
-linking or copying,
-depending on the platform; see also the
-.IR --duplicate
-option.)
-This guarantees correct builds
-regardless of whether intermediate source files
-are generated during the build,
-where preprocessors or other scanners search
-for included files,
-or whether individual compilers or other invoked tools
-are hard-coded to put derived files in the same directory as source files.
-
-This behavior of making a complete copy of the source tree
-may be disabled by setting
-.I duplicate
-to 0.
-This will cause
-.B scons
-to invoke Builders using the
-path names of source files in
-.I src_dir
-and the path names of derived files within
-.IR build_dir .
-This is always more efficient than
-.IR duplicate =1,
-and is usually safe for most builds.
-Specifying
-.IR duplicate =0,
-however,
-may cause build problems
-if source files are generated during the build,
-if any invoked tools are hard-coded to
-put derived files in the same directory as the source files.
-
-Note that specifying a
-.B BuildDir
-works most naturally
-with a subsidiary SConscript file
-in the source directory.
-However,
-you would then call the subsidiary SConscript file
-not in the source directory,
-but in the
-.I build_dir ,
-as if
-.B scons
-had made a virtual copy of the source tree
-regardless of the value of
-.IR duplicate .
-This is how you tell
-.B scons
-which variant of a source tree to build.
-For example:
-
-.ES
-BuildDir('build-variant1', 'src')
-SConscript('build-variant1/SConscript')
-BuildDir('build-variant2', 'src')
-SConscript('build-variant2/SConscript')
-.EE
-
-.IP
-See also the
-.BR SConscript ()
-function, described below,
-for another way to
-specify a build directory
-in conjunction with calling a subsidiary
-SConscript file.)
+argument becomes the
+.I variant_dir
+argument of
+.BR VariantDir ()
+or
+.BR env.VariantDir ().
+(This will be officially deprecated some day.)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Builder( action ", [" arguments ])
-.TP
+.TP
.RI env.Builder( action ", [" arguments ])
Creates a Builder object for
the specified
See the section "Builder Objects,"
below, for a complete explanation of the arguments and behavior.
-Note that the
+Note that the
.BR env.Builder ()
form of the invocation will expand
construction variables in any arguments strings,
until after the Builder object is actually called.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI CacheDir( cache_dir )
-.TP
+.TP
.RI env.CacheDir( cache_dir )
Specifies that
.B scons
predict or prohibitively large.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Clean( targets ", " files_or_dirs )
-.TP
+.TP
.RI env.Clean( targets ", " files_or_dirs )
This specifies a list of files or directories which should be removed
whenever the targets are specified with the
Examples:
The related
-.BR NoClean ()
+.BR NoClean ()
function overrides calling
.BR Clean ()
for the same target,
env4 = env.Clone(tools = ['msvc', MyTool])
.EE
+The
+.I parse_flags
+keyword argument is also recognized:
+
+.ES
+# create an environment for compiling programs that use wxWidgets
+wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI env.Copy([ key = val ", ...])"
-A synonym for
+A now-deprecated synonym for
.BR env.Clone() .
-(This will probably be officially deprecated some day.)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Decider( function )
.TP
.RI env.Decider( function )
to be performed:
.RS 10
+.HP 6
.B timestamp-newer
Specifies that a target shall be considered out of date and rebuilt
if the dependency's timestamp is newer than the target file's timestamp.
all within a single second.
.RE
+.IP
Examples:
.ES
env.Decider('content')
.EE
+.IP
In addition to the above already-available functions,
the
.I function
argument may be an actual Python function
that takes the following three arguments:
+.RS 10
.IP dependency
The Node (file) which
should cause the
file characteristics
such as the timestamp,
size, or content signature.
+.RE
+.IP
The
.I function
should return a
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Default( targets )
.TP
.RI env.Default( targets )
.TP
.RI env.Depends( target ", " dependency )
Specifies an explicit dependency;
-the target file(s) will be rebuilt
-whenever the dependency file(s) has changed.
+the
+.I target
+will be rebuilt
+whenever the
+.I dependency
+has changed.
+Both the specified
+.I target
+and
+.I dependency
+can be a string
+(usually the path name of a file or directory)
+or Node objects,
+or a list of strings or Node objects
+(such as returned by a Builder call).
This should only be necessary
for cases where the dependency
is not caught by a Scanner
.ES
env.Depends('foo', 'other-input-file-for-foo')
+
+mylib = env.Library('mylib.c')
+installed_lib = env.Install('lib', mylib)
+bar = env.Program('bar.c')
+
+# Arrange for the library to be copied into the installation
+# directory before trying to build the "bar" program.
+# (Note that this is for example only. A "real" library
+# dependency would normally be configured through the $LIBS
+# and $LIBPATH variables, not using an env.Depends() call.)
+
+env.Depends(bar, installed_lib)
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.RI env.Dir( name ", [" directory ])
This returns a Directory Node,
an object that represents the specified directory
-.IR name .
+.IR name .
.I name
-can be a relative or absolute path.
+can be a relative or absolute path.
.I directory
-is an optional directory that will be used as the parent directory.
+is an optional directory that will be used as the parent directory.
If no
.I directory
is specified, the current script's directory is used as the parent.
+If
+.I name
+is a list, SCons returns a list of Dir nodes.
+Construction variables are expanded in
+.IR name .
+
Directory Nodes can be used anywhere you
would supply a string as a directory name
to a Builder method or function.
.IP
will print:
.ES
-'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
+\&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
.EE
.ES
.RI EnsurePythonVersion( major ", " minor )
.TP
.RI env.EnsurePythonVersion( major ", " minor )
-Ensure that the Python version is at least
-.IR major . minor .
+Ensure that the Python version is at least
+.IR major . minor .
This function will
print out an error message and exit SCons with a non-zero exit code if the
actual Python version is not late enough.
.RI EnsureSConsVersion( major ", " minor ", [" revision ])
.TP
.RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
-Ensure that the SCons version is at least
+Ensure that the SCons version is at least
.IR major.minor ,
or
-.IR major.minor.revision .
+.IR major.minor.revision .
if
.I revision
is specified.
pairs.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Execute( action ", [" strfunction ", " varlist ])
.TP
.RI env.Execute( action ", [" strfunction ", " varlist ])
.RI Export( vars )
.TP
.RI env.Export( vars )
-This tells
+This tells
.B scons
to export a list of variables from the current
SConscript file to all other SConscript files.
The exported variables are kept in a global collection,
so subsequent calls to
.BR Export ()
-will over-write previous exports that have the same name.
+will over-write previous exports that have the same name.
Multiple variable names can be passed to
.BR Export ()
as separate arguments or as a list. A dictionary can be used to map
function, below.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI File( name ", [" directory ])
-.TP
+.TP
.RI env.File( name ", [" directory ])
This returns a
File Node,
an object that represents the specified file
-.IR name .
+.IR name .
.I name
-can be a relative or absolute path.
+can be a relative or absolute path.
.I directory
-is an optional directory that will be used as the parent directory.
+is an optional directory that will be used as the parent directory.
+
+If
+.I name
+is a list, SCons returns a list of File nodes.
+Construction variables are expanded in
+.IR name .
File Nodes can be used anywhere you
would supply a string as a file name
.RI FindFile( file ", " dirs )
.TP
.RI env.FindFile( file ", " dirs )
-Search for
-.I file
-in the path specified by
+Search for
+.I file
+in the path specified by
.IR dirs .
.I file
may be a list of file names or a single file name. In addition to searching
.RI FindInstalledFiles( )
.TP
.RI env.FindInstalledFiles( )
-Returns the list of targets setup by the
+Returns the list of targets set up by the
.B Install()
or
.B InstallAs()
builders.
This function serves as a convenient method to select the contents of
-a Binary Package.
+a binary package.
Example:
It does so by inspecting the dependency tree starting at the optional
argument
.B node
-which defaults to the '"."'-node. It will then return all leafs of
+which defaults to the '"."'-node. It will then return all leaves of
.B node.
These are all children which have no further children.
FindSourceFiles( 'src' )
.EE
+.IP
As you can see build support files (SConstruct in the above example)
will also be returned by this function.
1) The returned list will contain all appropriate directories
found in source trees
(when
-.BR BuildDir ()
+.BR VariantDir ()
is used)
or in code repositories
(when
print str(object)
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI GetBuildFailures()
+Returns a list of exceptions for the
+actions that failed while
+attempting to build targets.
+Each element in the returned list is a
+.B BuildError
+object
+with the following attributes
+that record various aspects
+of the build failure:
+
+.B .node
+The node that was being built
+when the build failure occurred.
+
+.B .status
+The numeric exit status
+returned by the command or Python function
+that failed when trying to build the
+specified Node.
+
+.B .errstr
+The SCons error string
+describing the build failure.
+(This is often a generic
+message like "Error 2"
+to indicate that an executed
+command exited with a status of 2.)
+
+.B .filename
+The name of the file or
+directory that actually caused the failure.
+This may be different from the
+.B .node
+attribute.
+For example,
+if an attempt to build a target named
+.B sub/dir/target
+fails because the
+.B sub/dir
+directory could not be created,
+then the
+.B .node
+attribute will be
+.B sub/dir/target
+but the
+.B .filename
+attribute will be
+.BR sub/dir .
+
+.B .executor
+The SCons Executor object
+for the target Node
+being built.
+This can be used to retrieve
+the construction environment used
+for the failed action.
+
+.B .action
+The actual SCons Action object that failed.
+This will be one specific action
+out of the possible list of
+actions that would have been
+executed to build the target.
+
+.B .command
+The actual expanded command that was executed and failed,
+after expansion of
+.BR $TARGET ,
+.BR $SOURCE ,
+and other construction variables.
+
+Note that the
+.BR GetBuildFailures ()
+function
+will always return an empty list
+until any build failure has occurred,
+which means that
+.BR GetBuildFailures ()
+will always return an empty list
+while the
+.B SConscript
+files are being read.
+Its primary intended use is
+for functions that will be
+executed before SCons exits
+by passing them to the
+standard Python
+.BR atexit.register ()
+function.
+Example:
+
+.ES
+import atexit
+
+def print_build_failures():
+ from SCons.Script import GetBuildFailures
+ for bf in GetBuildFailures():
+ print "%s failed: %s" % (bf.node, bf.errstr)
+
+atexit.register(print_build_failures)
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI GetBuildPath( file ", [" ... ])
.TP
.RI env.GetLaunchDir()
Returns the absolute path name of the directory from which
-.B
-scons
+.B scons
was initially invoked.
This can be useful when using the
.BR \-u ,
.RI GetOption( name )
.TP
.RI env.GetOption( name )
-This function provides a way to query a select subset of the scons command line
-options from a SConscript file. See
-.IR SetOption ()
-for a description of the options available.
+This function provides a way to query the value of
+SCons options set on scons command line
+(or set using the
+.IR SetOption ()
+function).
+The options supported are:
+
+.RS 10
+.TP 6
+.B cache_debug
+.TP 6
+which corresponds to --cache-debug;
+.TP 6
+.B cache_disable
+which corresponds to --cache-disable;
+.TP 6
+.B cache_force
+which corresponds to --cache-force;
+.TP 6
+.B cache_show
+which corresponds to --cache-show;
+.TP 6
+.B clean
+which corresponds to -c, --clean and --remove;
+.TP 6
+.B config
+which corresponds to --config;
+.TP 6
+.B directory
+which corresponds to -C and --directory;
+.TP 6
+.B diskcheck
+which corresponds to --diskcheck
+.TP 6
+.B duplicate
+which corresponds to --duplicate;
+.TP 6
+.B file
+which corresponds to -f, --file, --makefile and --sconstruct;
+.TP 6
+.B help
+which corresponds to -h and --help;
+.TP 6
+.B ignore_errors
+which corresponds to --ignore-errors;
+.TP 6
+.B implicit_cache
+which corresponds to --implicit-cache;
+.TP 6
+.B implicit_deps_changed
+which corresponds to --implicit-deps-changed;
+.TP 6
+.B implicit_deps_unchanged
+which corresponds to --implicit-deps-unchanged;
+.TP 6
+.B interactive
+which corresponds to --interact and --interactive;
+.TP 6
+.B keep_going
+which corresponds to -k and --keep-going;
+.TP 6
+.B max_drift
+which corresponds to --max-drift;
+.TP 6
+.B no_exec
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+.TP 6
+.B no_site_dir
+which corresponds to --no-site-dir;
+.TP 6
+.B num_jobs
+which corresponds to -j and --jobs;
+.TP 6
+.B profile_file
+which corresponds to --profile;
+.TP 6
+.B question
+which corresponds to -q and --question;
+.TP 6
+.B random
+which corresponds to --random;
+.TP 6
+.B repository
+which corresponds to -Y, --repository and --srcdir;
+.TP 6
+.B silent
+which corresponds to -s, --silent and --quiet;
+.TP 6
+.B site_dir
+which corresponds to --site-dir;
+.TP 6
+.B stack_size
+which corresponds to --stack-size;
+.TP 6
+.B taskmastertrace_file
+which corresponds to --taskmastertrace; and
+.TP 6
+.B warn
+which corresponds to --warn and --warning.
+.RE
+
+.IP
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
+.TP
+.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
+Returns Nodes (or strings) that match the specified
+.IR pattern ,
+relative to the directory of the current
+.B SConscript
+file.
+The
+.BR env.Glob ()
+form performs string substition on
+.I pattern
+and returns whatever matches
+the resulting expanded pattern.
+
+The specified
+.I pattern
+uses Unix shell style metacharacters for matching:
+
+.ES
+ * matches everything
+ ? matches any single character
+ [seq] matches any character in seq
+ [!seq] matches any char not in seq
+.EE
+
+.IP
+Character matches do
+.I not
+span directory separators.
+
+The
+.BR Glob ()
+knows about
+repositories
+(see the
+.BR Repository ()
+function)
+and source directories
+(see the
+.BR VariantDir ()
+function)
+and
+returns a Node (or string, if so configured)
+in the local (SConscript) directory
+if matching Node is found
+anywhere in a corresponding
+repository or source directory.
+
+The
+.B ondisk
+argument may be set to
+.B False
+(or any other non-true value)
+to disable the search for matches on disk,
+thereby only returning matches among
+already-configured File or Dir Nodes.
+The default behavior is to
+return corresponding Nodes
+for any on-disk matches found.
+
+The
+.B source
+argument may be set to
+.B True
+(or any equivalent value)
+to specify that,
+when the local directory is a
+.BR VariantDir (),
+the returned Nodes should be from the
+corresponding source directory,
+not the local directory.
+
+The
+.B strings
+argument may be set to
+.B True
+(or any equivalent value)
+to have the
+.BR Glob ()
+function return strings, not Nodes,
+that represent the matched files or directories.
+The returned strings will be relative to
+the local (SConscript) directory.
+(Note that This may make it easier to perform
+arbitrary manipulation of file names,
+but if the returned strings are
+passed to a different
+.B SConscript
+file,
+any Node translation will be relative
+to the other
+.B SConscript
+directory,
+not the original
+.B SConscript
+directory.)
+
+Example:
+
+.ES
+Program('foo', Glob('*.c'))
+.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\".TP
.RI Help( text )
.TP
.RI env.Help( text )
-This specifies help text to be printed if the
-.B -h
+This specifies help text to be printed if the
+.B -h
argument is given to
.BR scons .
If
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Import( vars )
-.TP
+.TP
.RI env.Import( vars )
-This tells
+This tells
.B scons
to import a list of variables into the current SConscript file. This
will import variables that were exported with
.BR Export ()
-or in the
+or in the
.I exports
-argument to
+argument to
.BR SConscript ().
-Variables exported by
+Variables exported by
.BR SConscript ()
have precedence.
-Multiple variable names can be passed to
+Multiple variable names can be passed to
.BR Import ()
as separate arguments or as a list. The variable "*" can be used
to import all variables.
not as separate arguments to
.BR env.MergeFlags ().
-By default,
+By default,
duplicate values are eliminated;
you can, however, specify
.B unique=0
# flag and merge the result into the construction variables.
env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
+# Combine an optimization flag with the flags returned from running pkg-config
+# twice and merge the result into the construction variables.
env.MergeFlags(['-O3',
'!pkg-config gtk+-2.0 --cflags --libs',
'!pkg-config libpng12 --cflags --libs'])
.RI env.NoCache( target ", ...)"
Specifies a list of files which should
.I not
-be cached whenever the
+be cached whenever the
.BR CacheDir ()
method has been activated.
The specified targets may be a list
Builder methods.
Calling
-.BR NoClean ()
+.BR NoClean ()
for a target overrides calling
.BR Clean ()
for the same target,
.BR gtk-config )
and adds the options
to the appropriate construction variables.
-By default,
+By default,
duplicate values are not
added to any construction variables;
you can specify
and the construction variables they affect
are as specified for the
.BR env.ParseFlags ()
-method (which thie method calls).
+method (which this method calls).
See that method's description, below,
for a table of options and construction variables.
Any other strings not associated with options
are assumed to be the names of libraries
and added to the
-.B LIBS
+.B LIBS
construction variable.
Examples (all of which produce the same result):
This is so that any executed commands
that use sockets to connect with other systems
(such as fetching source files from
-external CVS repository specifications like
+external CVS repository specifications like
.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
will work on Windows systems.
.B Local()
method.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Requires( target ", " prerequisite )
+.TP
+.RI env.Requires( target ", " prerequisite )
+Specifies an order-only relationship
+between the specified target file(s)
+and the specified prerequisite file(s).
+The prerequisite file(s)
+will be (re)built, if necessary,
+.I before
+the target file(s),
+but the target file(s) do not actually
+depend on the prerequisites
+and will not be rebuilt simply because
+the prerequisite file(s) change.
+
+Example:
+
+.ES
+env.Requires('foo', 'file-that-must-be-built-before-foo')
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Return([ vars "... , " stop= ])
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-.TP
+.TP
.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
Creates a Scanner object for
the specified
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
This tells
.B scons
to execute
.RI name= script
keyword argument.
-The optional
+The optional
.I exports
argument provides a list of variable names or a dictionary of
named values to export to the
-.IR script(s) ". "
+.IR script(s) .
These variables are locally exported only to the specified
.IR script(s) ,
-and do not affect the
-global pool of variables used by
-the
+and do not affect the global pool of variables used by the
.BR Export ()
function.
-'\"If multiple dirs are provided,
-'\"each script gets a fresh export.
+'\"If multiple dirs are provided, each script gets a fresh export.
The subsidiary
.I script(s)
must use the
.BR Import ()
function to import the variables.
-The optional
-.I build_dir
-argument specifies that all of the target files
-(for example, object files and executables)
-that would normally be built in the subdirectory in which
-.I script
-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
-argument specifies that the
-source files from which
-the target files should be built
-can be found in
-.IR src_dir .
+If the optional
+.I variant_dir
+argument is present, it causes an effect equivalent to
+.BR VariantDir (
+.IR variant_dir ,
+.IR src_dir ,
+.IR duplicate )
+to be executed prior to reading the
+.IR script (s).
+(If
+.I variant_dir
+is not present, the
.I src_dir
-is interpreted relative to the directory
-of the calling SConscript file.
-
-By default,
-.B scons
-will link or copy (depending on the platform)
-all the source files into the build directory.
-This behavior may be disabled by
-setting the optional
+and
.I duplicate
-argument to 0
-(it is set to 1 by default),
-in which case
-.B scons
-will refer directly to
-the source files in their source directory
-when building target files.
-(Setting
-.IR duplicate =0
-is usually safe, and always more efficient
-than the default of
-.IR duplicate =1,
-but it may cause build problems in certain end-cases,
-such as compiling from source files that
-are generated by the build.)
+arguments are ignored.)
+The
+.I variant_dir
+and
+.I src_dir
+arguments are interpreted relative to the directory
+of the calling SConscript file.
+If
+.I src_dir
+is not specified, the directory of the calling SConscript file is assumed.
+See the description of the
+.BR VariantDir ()
+function below for additional details and restrictions.
-Any variables returned by
-.I script
-using
+Any variables returned by
+.I script
+using
.BR Return ()
will be returned by the call to
-.BR SConscript ().
+.BR SConscript ().
Examples:
SConscript('subdir/SConscript')
foo = SConscript('sub/SConscript', exports='env')
SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript('src/SConscript', build_dir='build', duplicate=0)
-SConscript('bld/SConscript', src_dir='src', exports='env variable')
+SConscript('dir/SConscript', exports='env variable')
SConscript(dirs=['sub1', 'sub2'])
SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
.EE
+.ES
+SConscript('bld/SConscript', variant_dir='bld', duplicate=0)
+.EE
+which is equivalent to
+.ES
+VariantDir('bld', '.', duplicate=0)
+SConscript('bld/SConscript')
+.EE
+'\"TODO: SConscript('bld/SConscript', src_dir='src', exports='env variable')
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI SConscriptChdir( value )
.RI env.SetOption( name ", " value )
This function provides a way to set a select subset of the scons command
line options from a SConscript file. The options supported are:
+
+.RS 10
+.TP 6
.B clean
which corresponds to -c, --clean and --remove;
+.TP 6
.B duplicate
which corresponds to --duplicate;
+.TP 6
.B help
which corresponds to -h and --help;
+.TP 6
.B implicit_cache
which corresponds to --implicit-cache;
+.TP 6
.B max_drift
which corresponds to --max-drift;
+.TP 6
.B no_exec
which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+.TP 6
.B num_jobs
-which corresponds to -j and --jobs.
+which corresponds to -j and --jobs;
+.TP 6
.B random
-which corresponds to --random.
+which corresponds to --random; and
+.TP 6
+.B stack_size
+which corresponds to --stack-size.
+.RE
+
+.IP
See the documentation for the
corresponding command line object for information about each specific
option.
Declares
.I side_effect
as a side effect of building
-.IR target .
-Both
-.I side_effect
+.IR target .
+Both
+.I side_effect
and
.I target
can be a list, a file name, or a node.
-A side effect is a target that is created
+A side effect is a target file that is created or updated
as a side effect of building other targets.
For example, a Windows PDB
file is created as a side effect of building the .obj
-files for a static library.
+files for a static library,
+and various log files are created updated
+as side effects of various TeX commands.
If a target is a side effect of multiple build commands,
.B scons
will ensure that only one set of commands
for side-effect targets that are built as a result of
multiple build commands.
+Because multiple build commands may update
+the same side effect file,
+by default the
+.I side_effect
+target is
+.I not
+automatically removed
+when the
+.I target
+is removed by the
+.B -c
+option.
+(Note, however, that the
+.I side_effect
+might be removed as part of
+cleaning the directory in which it lives.)
+If you want to make sure the
+.I side_effect
+is cleaned whenever a specific
+.I target
+is cleaned,
+you must specify this explicitly
+with the
+.BR Clean ()
+or
+.BR env.Clean ()
+function.
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI SourceCode( entries ", " builder )
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
+.RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
Performs construction variable interpolation
-on the specified string argument.
+on the specified string or sequence argument
+.IR input .
By default,
leading or trailing white space will
pairs
(as is done for signature calculation).
+If the input is a sequence
+(list or tuple),
+the individual elements of
+the sequence will be expanded,
+and the results will be returned as a list.
+
The optional
.I target
and
from within a Python function used
as an SCons action.
-By default,
-all returned values are converted
-to their string representation.
+Returned string values or sequence elements
+are converted to their string representation by default.
The optional
.I conv
argument
.RI SourceSignatures( type )
.TP
.RI env.SourceSignatures( type )
-This function tells
+Note: Although it is not yet officially deprecated,
+use of this function is discouraged.
+See the
+.BR Decider ()
+function for a more flexible and straightforward way
+to configure SCons' decision-making.
+
+The
+.BR SourceSignatures ()
+function tells
.B scons
how to decide if a source file
(a file that is not built from any other files)
means
.B scons
decides that a source file has changed
-if its timestamp (modification time) is newer than
+if its timestamp (modification time) has changed since
the last time it was used to rebuild a particular target file.
+(Note that although this is similar to the behavior of Make,
+by default it will also rebuild if the dependency is
+.I older
+than the last time it was used to rebuild the target file.)
There is no different between the two behaviors
for Python
# marks file2.txt to be a documentation file
Tag( 'file2.txt', DOC )
.EE
-</summary>
-</builder>
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI TargetSignatures( type )
.TP
.RI env.TargetSignatures( type )
-This function tells
+Note: Although it is not yet officially deprecated,
+use of this function is discouraged.
+See the
+.BR Decider ()
+function for a more flexible and straightforward way
+to configure SCons' decision-making.
+
+The
+.BR TargetSignatures ()
+function tells
.B scons
how to decide if a target file
(a file that
means
.B scons
decides that a target file has changed
-if its timestamp (modification time) is newer than
+if its timestamp (modification time) has changed since
the last time it was used to rebuild some other target file.
+(Note that although this is similar to the behavior of Make,
+by default it will also rebuild if the dependency is
+.I older
+than the last time it was used to rebuild the target file.)
.B "source"
means
by setting a new value.
The optional
.I built_value
-argument can be specified
+argument can be specified
when the Value Node is created
to indicate the Node should already be considered
"built."
# $TARGET.
f = open(str(target[0]), 'wb')
f.write('prefix=' + source[0].get_contents())
-
+
# Fetch the prefix= argument, if any, from the command
# line, and use /usr/local as the default.
prefix = ARGUMENTS.get('prefix', '/usr/local')
env.UpdateValue(target = Value(output), source = Value(input))
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
+.TP
+.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
+Use the
+.BR VariantDir ()
+function to create a copy of your sources in another location:
+if a name under
+.IR variant_dir
+is not found but exists under
+.IR src_dir ,
+the file or directory is copied to
+.IR variant_dir .
+Target files can be built in a different directory than the original sources
+by simply refering to the sources (and targets) within the variant tree.
+
+.BR VariantDir ()
+can be called multiple times with the same
+.I src_dir
+to set up multiple builds with different options
+.RI ( variants ).
+The
+.I src_dir
+location must be in or underneath the SConstruct file's directory, and
+.I variant_dir
+may not be underneath
+.IR src_dir .
+'\"TODO: Can the above restrictions be clarified or relaxed?
+'\"TODO: The latter restriction is clearly not completely right;
+'\"TODO: src_dir = '.' works fine with a build dir under it.
+
+The default behavior is for
+.B scons
+to physically duplicate the source files in the variant tree.
+Thus, a build performed in the variant tree is guaranteed to be identical
+to a build performed in the source tree even if
+intermediate source files are generated during the build,
+or preprocessors or other scanners search for included files
+relative to the source file,
+or individual compilers or other invoked tools are hard-coded
+to put derived files in the same directory as source files.
+
+If possible on the platform,
+the duplication is performed by linking rather than copying;
+see also the
+.IR --duplicate
+command-line option.
+Moreover, only the files needed for the build are duplicated;
+files and directories that are not used are not present in
+.IR variant_dir .
+
+Duplicating the source tree may be disabled by setting the
+.I duplicate
+argument to 0.
+This will cause
+.B scons
+to invoke Builders using the path names of source files in
+.I src_dir
+and the path names of derived files within
+.IR variant_dir .
+This is always more efficient than
+.IR duplicate =1,
+and is usually safe for most builds
+(but see above for cases that may cause problems).
+
+Note that
+.BR VariantDir ()
+works most naturally with a subsidiary SConscript file.
+However, you would then call the subsidiary SConscript file
+not in the source directory, but in the
+.I variant_dir ,
+regardless of the value of
+.IR duplicate .
+This is how you tell
+.B scons
+which variant of a source tree to build:
+
+.ES
+# run src/SConscript in two variant directories
+VariantDir('build/variant1', 'src')
+SConscript('build/variant1/SConscript')
+VariantDir('build/variant2', 'src')
+SConscript('build/variant2/SConscript')
+.EE
+
+.IP
+See also the
+.BR SConscript ()
+function, described above,
+for another way to specify a variant directory
+in conjunction with calling a subsidiary SConscript file.
+
+Examples:
+
+.ES
+# use names in the build directory, not the source directory
+VariantDir('build', 'src', duplicate=0)
+Program('build/prog', 'build/source.c')
+.EE
+
+.ES
+# this variant builds both the source and docs
+VariantDir('build', '.', duplicate=0)
+SConscript(dirs=['build/src','build/doc'])
+.EE
+Or, equivalently:
+.ES
+SConscript(dirs=['build/src','build/doc'],
+ variant_dir = 'build', duplicate = 0)
+.EE
+
+.ES
+SConscript('build/SConscript', variant_dir = 'build', duplicate = 0)
+.EE
+Note that in the last example, the
+.I src_dir
+is not given, so the current directory is assumed, and the
+.B SConstruct
+and the
+.B SConscript
+are actually in the same directory, even though the
+.B SConscript
+is treated as if it were in the
+.B build
+subdirectory.
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI WhereIs( program ", [" path ", " pathext ", " reject ])
.\" CC The C compiler
.\" Example: env["CC"] = "c68x"
.\" Default: env["CC"] = "cc"
-.\"
+.\"
.\" CCCOM The command line ...
.\" Example:
.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
'\"
-'\" The descriptions below of the various SCons contruction variables
+'\" The descriptions below of the various SCons construction 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,
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
'\"
-'\" The descriptions above of the various SCons contruction variables
+'\" The descriptions above of the various SCons construction 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,
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.LP
-Construction variables can be retrieved and set using the
-.B Dictionary
+Construction variables can be retrieved and set using the
+.B Dictionary
method of the construction environment:
.ES
env = Environment(CC="cc")
.EE
-or when copying a construction environment using the
-.B Clone
+or when copying a construction environment using the
+.B Clone
method:
.ES
.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. However, users may override this behaviour with the
+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 ", " config_h ])
+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
+.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
This creates a configure context, which can be used to perform checks.
.I env
specifies the environment for building the tests.
This environment may be modified when performing checks.
.I custom_tests
is a dictionary containing custom tests.
-See also the section about custom tests below.
+See also the section about custom tests below.
By default, no custom tests are added to the configure context.
.I conf_dir
specifies a directory where the test cases are built.
that are executed to check for the existence of header files, libraries, etc.
The default is the file #/config.log.
If you are using the
-.B BuildDir
+.BR VariantDir ()
method,
-you may want to specify a subdirectory under your build directory.
+you may want to specify a subdirectory under your variant 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.
+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.
.I config_h
file is being built.
+The optional
+.B clean
+and
+.B help
+arguments can be used to suppress execution of the configuration
+tests when the
+.B -c/--clean
+or
+.B -H/-h/--help
+options are used, respectively.
+The default behavior is always to execute
+configure context tests,
+since the results of the tests may
+affect the list of targets to be cleaned
+or the help text.
+If the configure tests do not affect these,
+then you may add the
+.B clean=False
+or
+.B help=False
+arguments
+(or both)
+to avoid unnecessary test execution.
+
.EE
A created
.B Configure
instance has the following associated methods:
-.TP
+.TP
.RI Configure.Finish( self )
This method should be called after configuration is done.
It returns the environment as modified
by the configuration checks performed.
After this method is called, no further checks can be performed
with this configuration context.
-However, you can create a new
-.RI Configure
+However, you can create a new
+.RI Configure
context to perform additional checks.
Only one context should be active at a time.
.TP
.RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
-Checks if
+Checks if
.I header
is usable in the specified language.
.I header
.B #include
lines should precede the
header line being checked for.
-The optional argument
-.I include_quotes
+The optional argument
+.I include_quotes
must be
a two character string, where the first character denotes the opening
quote and the second character denotes the closing quote.
.RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
This is a wrapper around
.B Configure.CheckHeader
-which checks if
+which checks if
.I header
is usable in the C language.
.I header
.B #include
lines should precede the
header line being checked for.
-The optional argument
-.I include_quotes
+The optional argument
+.I include_quotes
must be
a two character string, where the first character denotes the opening
quote and the second character denotes the closing quote (both default
.RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
This is a wrapper around
.B Configure.CheckHeader
-which checks if
+which checks if
.I header
is usable in the C++ language.
.I header
.B #include
lines should precede the
header line being checked for.
-The optional argument
-.I include_quotes
+The optional argument
+.I include_quotes
must be
a two character string, where the first character denotes the opening
quote and the second character denotes the closing quote (both default
to \N'34').
-Returns 1 on success and 0 on failure.
+Returns 1 on success and 0 on failure.
.TP
.RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
and selects the compiler to be used for the check;
the default is "C".
-.TP
+.TP
.RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
-Checks if
-.I library
-provides
+Checks if
+.I library
+provides
.IR symbol .
If the value of
.I autoadd
is 1 and the library provides the specified
.IR symbol ,
appends the library to the LIBS construction environment variable.
-.I library
+.I library
may also be None (the default),
-in which case
-.I symbol
+in which case
+.I symbol
is checked with the current LIBS variable,
or a list of library names,
in which case each library in the list
will be checked for
.IR symbol .
-If
+If
.I symbol
is not set or is
.BR None ,
is 1.
This method returns 1 on success and 0 on error.
-.TP
+.TP
.RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
-In contrast to the
-.RI Configure.CheckLib
+In contrast to the
+.RI Configure.CheckLib
call, this call provides a more sophisticated way to check against libraries.
-Again,
+Again,
.I library
-specifies the library or a list of libraries to check.
+specifies the library or a list of libraries to check.
.I header
specifies a header to check for.
.I header
can link against the specified
.IR library .
.I autoadd
-specifies whether to add the library to the environment (only if the check
+specifies whether to add the library to the environment (only if the check
succeeds). This method returns 1 on success and 0 on error.
.TP
if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
# do stuff for qt - usage, e.g.
conf.env.Append( CPPFLAGS = '-DWITH_QT' )
-env = conf.Finish()
+env = conf.Finish()
+.EE
+
+.TP
+.RI Configure.CheckTypeSize( self ", " type_name ", [" header ", " language ", " expect ])
+Checks for the size of a type defined by
+.BR typedef .
+.I type_name
+specifies the typedef name 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 empty.
+The optional
+.I language
+argument should be
+.B C
+or
+.B C++
+and selects the compiler to be used for the check;
+the default is "C".
+The optional
+.I expect
+argument should be an integer.
+If this argument is used,
+the function will only check whether the type
+given in type_name has the expected size (in bytes).
+For example,
+.B "CheckTypeSize('short', expect = 2)"
+will return success only if short is two bytes.
+
+.ES
+.EE
+
+.TP
+.RI Configure.CheckDeclaration( self ", " symbol ", [" includes ", " language ])
+Checks if the specified
+.I symbol
+is declared.
+.I includes
+is a string containing one or more
+.B #include
+lines that will be inserted into the program
+that will be run to test for the existence of the type.
+The optional
+.I language
+argument should be
+.B C
+or
+.B C++
+and selects the compiler to be used for the check;
+the default is "C".
+
+.TP
+.RI Configure.Define(self ", " symbol ", [" value ", " comment ])
+This function does not check for anything, but defines a
+preprocessor symbol that will be added to the configuration header file.
+It is the equivalent of AC_DEFINE,
+and defines the symbol
+.I name
+with the optional
+.B value
+and the optional comment
+.BR comment .
+
+.IP
+Examples:
+
+.ES
+env = Environment()
+conf = Configure( env )
+
+# Puts the following line in the config header file:
+# #define A_SYMBOL
+conf.Define('A_SYMBOL')
+
+# Puts the following line in the config header file:
+# #define A_SYMBOL 1
+conf.Define('A_SYMBOL', 1)
+.EE
+
+.IP
+Be careful about quoting string values, though:
+
+.ES
+env = Environment()
+conf = Configure( env )
+
+# Puts the following line in the config header file:
+# #define A_SYMBOL YA
+conf.Define('A_SYMBOL', "YA")
+
+# Puts the following line in the config header file:
+# #define A_SYMBOL "YA"
+conf.Define('A_SYMBOL', '"YA"')
+.EE
+
+.IP
+For comment:
+
+.ES
+env = Environment()
+conf = Configure( env )
+
+# Puts the following lines in the config header file:
+# /* Set to 1 if you have a symbol */
+# #define A_SYMBOL 1
+conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
.EE
.EE
-You can define your own custom checks.
+You can define your own custom checks.
in addition to the predefined checks.
These are passed in a dictionary to the Configure function.
This dictionary maps the names of the checks
-to user defined Python callables
+to user defined Python callables
(either Python functions or class instances implementing the
.I __call__
method).
-The first argument of the call is always a
+The first argument of the call is always a
.I CheckContext
instance followed by the arguments,
which must be supplied by the user of the check.
These CheckContext instances define the following methods:
-.TP
+.TP
.RI CheckContext.Message( self ", " text )
-Usually called before the check is started.
+Usually called before the check is started.
.I text
will be displayed to the user, e.g. 'Checking for library X...'
.TP
.RI CheckContext.Result( self, ", " res )
-Usually called after the check is done.
+Usually called after the check is done.
.I res
-can be either an integer or a string. In the former case, 'ok' (res != 0)
-or 'failed' (res == 0) is displayed to the user, in the latter case the
+can be either an integer or a string. In the former case, 'ok' (res != 0)
+or 'failed' (res == 0) is displayed to the user, in the latter case the
given string is displayed.
.TP
.RI CheckContext.TryCompile( self ", " text ", " extension )
-Checks if a file with the specified
+Checks if a file with the specified
.I extension
-(e.g. '.c') containing
-.I text
+(e.g. '.c') containing
+.I text
can be compiled using the environment's
-.B Object
+.B Object
builder. Returns 1 on success and 0 on failure.
-.TP
+.TP
.RI CheckContext.TryLink( self ", " text ", " extension )
Checks, if a file with the specified
.I extension
-(e.g. '.c') containing
-.I text
+(e.g. '.c') containing
+.I text
can be compiled using the environment's
.B Program
builder. Returns 1 on success and 0 on failure.
.RI CheckContext.TryRun( self ", " text ", " extension )
Checks, if a file with the specified
.I extension
-(e.g. '.c') containing
-.I text
+(e.g. '.c') containing
+.I text
can be compiled using the environment's
.B Program
builder. On success, the program is run. If the program
.TP
.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
Checks if the specified
-.I action
+.I action
with an optional source file (contents
.I text
-, extension
+, extension
.I extension
= ''
-) can be executed.
-.I action
-may be anything which can be converted to a
+) can be executed.
+.I action
+may be anything which can be converted to a
.B scons
.RI Action.
On success,
the methods above are based on this method.
Given the Builder instance
.I builder
-and the optional
+and the optional
.I text
of a source file with optional
.IR extension ,
-this method returns 1 on success and 0 on failure. In addition,
-.I self.lastTarget
+this method returns 1 on success and 0 on failure. In addition,
+.I self.lastTarget
is set to the build target node, if the build was successful.
.EE
context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
ret = context.TryLink("""
#include <qapp.h>
-int main(int argc, char **argv) {
+int main(int argc, char **argv) {
QApplication qapp(argc, argv);
return 0;
}
if not conf.CheckQt('/usr/lib/qt'):
print 'We really need qt!'
Exit(1)
-env = conf.Finish()
+env = conf.Finish()
.EE
-.SS Construction Variable Options
+.SS Command-Line Construction Variables
-Often when building software, various options need to be specified at build
-time that are not known when the SConstruct/SConscript files are
-written. For example, libraries needed for the build may be in non-standard
+Often when building software,
+some variables must be specified at build time.
+For example, libraries needed for the build may be in non-standard
locations, or site-specific compiler options may need to be passed to the
-compiler.
+compiler.
.B scons
-provides a mechanism for overridding construction variables from the
-command line or a text-based SConscript file through an Options
-object. To create an Options object, call the Options() function:
+provides a
+.B Variables
+object to support overriding construction variables
+on the command line:
+.ES
+$ scons VARIABLE=foo
+.EE
+The variable values can also be specified in a text-based SConscript file.
+To create a Variables object, call the Variables() function:
.TP
-.RI Options([ files "], [" args ])
-This creates an Options object that will read construction variables from
+.RI Variables([ files "], [" args ])
+This creates a Variables object that will read construction variables from
the file or list of filenames specified in
.IR files .
If no files are specified,
Example:
.ES
-opts = Options('custom.py')
-opts = Options('overrides.py', ARGUMENTS)
-opts = Options(None, {FOO:'expansion', BAR:7})
+vars = Variables('custom.py')
+vars = Variables('overrides.py', ARGUMENTS)
+vars = Variables(None, {FOO:'expansion', BAR:7})
.EE
-Options objects have the following methods:
+Variables objects have the following methods:
.TP
.RI Add( key ", [" help ", " default ", " validator ", " converter ])
-This adds a customizable construction variable to the Options object.
+This adds a customizable construction variable to the Variables object.
.I key
-is the name of the variable.
-.I help
+is the name of the variable.
+.I help
is the help text for the variable.
-.I default
+.I default
is the default value of the variable;
if the default value is
.B None
Examples:
.ES
-opts.Add('CC', 'The C compiler')
+vars.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)
+vars.Add('COLOR', validator=valid_color)
.EE
.TP
-.RI AddOptions( list )
+.RI AddVariables( list )
A wrapper script that adds
multiple customizable construction variables
-to an Options object.
+to a Variables object.
.I list
is a list of tuple or list objects
that contain the arguments
method.
.ES
-opt.AddOptions(
+opt.AddVariables(
('debug', '', 0),
('CC', 'The C compiler'),
('VALIDATE', 'An option for testing validation',
.RI Update( env ", [" args ])
This updates a construction environment
.I env
-with the customized construction variables. Normally this method is not
-called directly, but is called indirectly by passing the Options object to
+with the customized construction variables.
+Any specified variables that are
+.I not
+configured for the Variables object
+will be saved and may be
+retrieved with the
+.BR UnknownVariables ()
+method, below.
+
+Normally this method is not called directly,
+but is called indirectly by passing the Variables object to
the Environment() function:
.ES
-env = Environment(options=opts)
+env = Environment(variables=vars)
.EE
.IP
The text file(s) that were specified
-when the Options object was created
+when the Variables 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 UnknownVariables( )
+Returns a dictionary containing any
+variables that were specified
+either in the files or the dictionary
+with which the Variables object was initialized,
+but for which the Variables object was
+not configured.
+
+.ES
+env = Environment(variables=vars)
+for key, value in vars.UnknownVariables():
+ print "unknown variable: %s=%s" % (key, value)
+.EE
+
.TP
.RI Save( filename ", " env )
-This saves the currently set options into a script file named
+This saves the currently set variables into a script file named
.I filename
that can be used on the next invocation to automatically load the current
-settings. This method combined with the Options method can be used to
-support caching of options between runs.
+settings. This method combined with the Variables method can be used to
+support caching of variables between runs.
.ES
env = Environment()
-opts = Options(['options.cache', 'custom.py'])
-opts.Add(...)
-opts.Update(env)
-opts.Save('options.cache', env)
+vars = Variables(['variables.cache', 'custom.py'])
+vars.Add(...)
+vars.Update(env)
+vars.Save('variables.cache', env)
.EE
.TP
.RI GenerateHelpText( env ", [" sort ])
This generates help text documenting the customizable construction
-variables suitable to passing in to the Help() function.
+variables suitable to passing in to the Help() function.
.I env
is the construction environment that will be used to get the actual values
-of customizable variables. Calling with
+of customizable variables. Calling with
an optional
.I sort
function
function).
.ES
-Help(opts.GenerateHelpText(env))
-Help(opts.GenerateHelpText(env, sort=cmp))
+Help(vars.GenerateHelpText(env))
+Help(vars.GenerateHelpText(env, sort=cmp))
.EE
.TP
-.RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
+.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
This method returns a formatted string
containing the printable help text
for one option.
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
+vars.FormatVariableHelpText = my_format
.EE
-To make it more convenient to work with customizable Options,
+To make it more convenient to work with customizable Variables,
.B scons
provides a number of functions
that make it easy to set up
-various types of Options:
+various types of Variables:
.TP
-.RI BoolOption( key ", " help ", " default )
+.RI BoolVariable( key ", " help ", " default )
Return a tuple of arguments
to set up a Boolean option.
The option will use
as false.
.TP
-.RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
+.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
Return a tuple of arguments
to set up an option
whose value may be one
converted to lower case.
.TP
-.RI ListOption( key ", " help ", " default ", " names ", [", map ])
+.RI ListVariable( key ", " help ", " default ", " names ", [", map ])
Return a tuple of arguments
to set up an option
whose value may be one or more
list.
.TP
-.RI PackageOption( key ", " help ", " default )
+.RI PackageVariable( key ", " help ", " default )
Return a tuple of arguments
to set up an option
whose value is a path name
of a package that may be
-enabled, disabled or
+enabled, disabled or
given an explicit path name.
The option will use
the specified name
to disable use of the specified option.
.TP
-.RI PathOption( key ", " help ", " default ", [" validator ])
+.RI PathVariable( key ", " help ", " default ", [" validator ])
Return a tuple of arguments
to set up an option
whose value is expected to be a path name.
is acceptable.
SCons supplies the
following ready-made validators:
-.BR PathOption.PathExists
+.BR PathVariable.PathExists
(the default),
which verifies that the specified path exists;
-.BR PathOption.PathIsFile ,
+.BR PathVariable.PathIsFile ,
which verifies that the specified path is an existing file;
-.BR PathOption.PathIsDir ,
+.BR PathVariable.PathIsDir ,
which verifies that the specified path is an existing directory;
-.BR PathOption.PathIsDirCreate ,
+.BR PathVariable.PathIsDirCreate ,
which verifies that the specified path is a directory
and will create the specified directory if the path does not exist;
and
-.BR PathOption.PathAccept ,
+.BR PathVariable.PathAccept ,
which simply accepts the specific path name argument without validation,
and which is suitable if you want your users
to be able to specify a directory path that will be
function,
which must take three arguments
.RI ( key ,
-the name of the options variable to be set;
+the name of the variable to be set;
.IR val ,
the specified value being checked;
and
.RE
These functions make it
convenient to create a number
-of options with consistent behavior
+of variables with consistent behavior
in a single call to the
-.B AddOptions
+.B AddVariables
method:
.ES
-opts.AddOptions(
- BoolOption('warnings', 'compilation with -Wall and similiar', 1),
- EnumOption('debug', 'debug output and symbols', 'no'
+vars.AddVariables(
+ BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
+ EnumVariable('debug', 'debug output and symbols', 'no'
allowed_values=('yes', 'no', 'full'),
map={}, ignorecase=0), # case sensitive
- ListOption('shared',
+ ListVariable('shared',
'libraries to build as shared libraries',
'all',
names = list_of_libs),
- PackageOption('x11',
+ PackageVariable('x11',
'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),
+ PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
+ PathVariable('foopath', 'where the foo library is installed', foopath,
+ PathVariable.PathIsDir),
)
.EE
.B SConstruct
file is found).
The build path is the same as the source path if
-.I build_dir
+.I variant_dir
is not being used.
.IP abspath
.I File
or
.IR Dir .
-The
+The
.ES
# Get the current build dir's path, relative to top.
print "foo will be built in %s"%foo.path
.EE
+A
+.I Dir
+Node or
+.I File
+Node can also be used to create
+file and subdirectory Nodes relative to the generating Node.
+A
+.I Dir
+Node will place the new Nodes within the directory it represents.
+A
+.I File
+node will place the new Nodes within its parent directory
+(that is, "beside" the file in question).
+If
+.I d
+is a
+.I Dir
+(directory) Node and
+.I f
+is a
+.I File
+(file) Node,
+then these methods are available:
+
+.TP
+.IR d .Dir( name )
+Returns a directory Node for a subdirectory of
+.I d
+named
+.IR name .
+
+.TP
+.IR d .File( name )
+Returns a file Node for a file within
+.I d
+named
+.IR name .
+
+.TP
+.IR d .Entry( name )
+Returns an unresolved Node within
+.I d
+named
+.IR name .
+
+.TP
+.IR f .Dir( name )
+Returns a directory named
+.I name
+within the parent directory of
+.IR f .
+
+.TP
+.IR f .File( name )
+Returns a file named
+.I name
+within the parent directory of
+.IR f .
+
+.TP
+.IR f .Entry( name )
+Returns an unresolved Node named
+.I name
+within the parent directory of
+.IR f .
+
+.RE
+For example:
+
+.ES
+# Get a Node for a file within a directory
+incl = Dir('include')
+f = incl.File('header.h')
+
+# Get a Node for a subdirectory within a directory
+dist = Dir('project-3.2.1)
+src = dist.Dir('src')
+
+# Get a Node for a file in the same directory
+cfile = File('sample.c')
+hfile = cfile.File('sample.h')
+
+# Combined example
+docs = Dir('docs')
+html = docs.Dir('html')
+index = html.File('index.html')
+css = index.File('app.css')
+.EE
+
.SH EXTENDING SCONS
.SS Builder Objects
.B scons
Builder objects are created
using the
-.B Builder
+.B Builder
function.
The
.B Builder
function accepts the following arguments:
.IP action
-The command line string used to build the target from the source.
+The command line string used to build the target from the source.
.B action
can also be:
a list of strings representing the command
An action function
takes three arguments:
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I target
- a list of target nodes,
.I env
- the construction environment.
-.IP prefix
+.IP prefix
The prefix that will be prepended to the target file name.
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
+- 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
.EE
.IP ensure_suffix
-When set to any true value, causes
+When set to any true value, causes
.B scons
to add the target suffix specified by the
.I suffix
implicit dependencies
based only on the target file
and the construction environment,
-.I not
+.I not
for implicit
(See the section "Scanner Objects," below,
for information about creating Scanner objects.)
An emitter function
takes three arguments:
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I target
- a list of target nodes,
.I env
builder multiple times for the same target simply adds additional source
files to the target; it is not allowed to change the environment associated
with the target, specify addition environment overrides, or associate a different
-builder with the target.
+builder with the target.
.IP env
A construction environment that can be used
The generator function
takes four arguments:
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I target
- a list of target nodes,
.I env
.ES
def g(source, target, env, for_signature):
- return [["gcc", "-c", "-o"] + target + source]
+ return [["gcc", "-c", "-o"] + target + source]
b = Builder(generator=g)
.EE
.IP
-The
+The
.I generator
and
.I action
.IP single_source
Specifies that this builder expects exactly one source file per call. Giving
more than one source files without target files results in implicitely calling
-the builder multiple times (once for each source given). Giving multiple
+the builder multiple times (once for each source given). Giving multiple
source files together with target files results in a UserError exception.
.RE
.IP
-The
+The
.I generator
and
.I action
the setting of
.B source_ext_match
prevents
-.B scons
+.B scons
from exiting with an error
due to the mismatched suffixes of
.B foo.in
will be set in the executing construction
environment when the Builder object is called.
The canonical example here would be
-to set a construction variable to
+to set a construction variable to
the repository of a source code system.
Any additional keyword arguments supplied
def build_it(target = None, source = None, env = None):
# build the target from the source
return 0
-
+
a = Action(build_it)
.EE
that arrange for various common
file and directory manipulations
to be performed.
-These are similar in concept to "tasks" in the
+These are similar in concept to "tasks" in the
Ant build tool,
although the implementation is slightly different.
These functions do not actually
without relying
on platform-specific
external commands:
-that
+that
.ES
env = Environment(TMPBUILD = '/tmp/builddir')
env.Command('foo.out', 'foo.in',
env.Command('foo.out', 'foo.in',
[Mkdir('/tmp/builddir',
- Copy('$SOURCE', '/tmp/builddir')
- "cd /tmp/builddir && ])
-
+ Copy('$SOURCE', '/tmp/builddir/foo.in')
+ "cd /tmp/builddir && make",
+ Copy('/tmp/builddir/foo.out', '$TARGET')])
.EE
.TP
variables for each command execution:
.IP TARGET
-The file name of the target being built, or the file name of the first
+The file name of the target being built, or the file name of the first
target if multiple targets are being built.
.IP TARGETS
(Note that the above variables are reserved
and may not be set in a construction environment.)
-.LP
+.LP
For example, given the construction variable CC='cc', targets=['foo'], and
sources=['foo.c', 'bar.c']:
when a path references a file on other (POSIX) systems.
.IP srcpath
-The directory and file name to the source file linked to this file
-through BuildDir. If this file isn't linked, it just returns the
-directory and filename unchanged.
+The directory and file name to the source file linked to this file through
+.BR VariantDir ().
+If this file isn't linked,
+it just returns the directory and filename unchanged.
.IP srcdir
-The directory containing the source file linked to this file
-through BuildDir. If this file isn't linked, it just returns the
-directory part of the filename.
+The directory containing the source file linked to this file through
+.BR VariantDir ().
+If this file isn't linked,
+it just returns the directory part of the filename.
.IP rsrcpath
-The directory and file name to the source file linked to this file
-through BuildDir. If the file does not exist locally but exists in
-a Repository, the path in the Repository is returned.
+The directory and file name to the source file linked to this file through
+.BR VariantDir ().
+If the file does not exist locally but exists in a Repository,
+the path in the Repository is returned.
If this file isn't linked, it just returns the
directory and filename unchanged.
.IP rsrcdir
-The Repository directory containing the source file linked to this file
-through BuildDir. If this file isn't linked, it just returns the
-directory part of the filename.
+The Repository directory containing the source file linked to this file through
+.BR VariantDir ().
+If this file isn't linked,
+it just returns the directory part of the filename.
.LP
For example, the specified target will
${TARGET.suffix} => .x
${TARGET.abspath} => /top/dir/sub/dir/file.x
-SConscript('src/SConscript', build_dir='sub/dir')
+SConscript('src/SConscript', variant_dir='sub/dir')
$SOURCE => sub/dir/file.x
${SOURCE.srcpath} => src/file.x
${SOURCE.srcdir} => src
take four arguments:
.I target
- a list of target nodes,
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I env
- the construction environment,
.I for_signature
.IP String
When the value is a string it is interpreted as a space delimited list of
-command line arguments.
+command line arguments.
.IP List
When the value is a list it is interpreted as a list of command line
for the different file types that this
Scanner knows how to scan.
If the argument is a string,
-then it will be expanded
+then it will be expanded
into a list by the current environment.
.IP path_function
the
.BR Object (),
.BR SharedObject (),
-and
+and
.BR StaticObject ()
builders to decide
which scanner should be used
the underlying system.
On a case-sensitive system
such as Linux or UNIX,
-SCons treats a file with a
+SCons treats a file with a
.B .C
suffix as a C++ source file.
On a case-insensitive system
such as Windows,
-SCons treats a file with a
+SCons treats a file with a
.B .C
suffix as a C source file.
.SS .F file suffix
the underlying system.
On a case-sensitive system
such as Linux or UNIX,
-SCons treats a file with a
+SCons treats a file with a
.B .F
suffix as a Fortran source file
that is to be first run through
the standard C preprocessor.
On a case-insensitive system
such as Windows,
-SCons treats a file with a
+SCons treats a file with a
.B .F
suffix as a Fortran source file that should
.I not
tools, if they are both installed, regardless of the order of the bin
directories in the PATH variable. If you have both MSVC and MinGW
installed and you want to use MinGW instead of MSVC,
-then you must explictly tell SCons to use MinGW by passing
+then you must explictly tell SCons to use MinGW by passing
.ES
tools=['mingw']
for inc in includes:
for dir in path:
file = dir + os.sep + inc
- if os.path.exists(file):
+ if os.path.exists(file):
results.append(file)
break
return results
.SS Building Multiple Variants From the Same Source
-Use the build_dir keyword argument to
+Use the variant_dir keyword argument to
the SConscript function to establish
-one or more separate build directories for
-a given source directory:
+one or more separate variant build directory trees
+for a given source directory:
.ES
SConstruct:
cppdefines = ['FOO']
Export("cppdefines")
- SConscript('src/SConscript', build_dir='foo')
+ SConscript('src/SConscript', variant_dir='foo')
cppdefines = ['BAR']
Export("cppdefines")
- SConscript('src/SConscript', build_dir='bar')
+ SConscript('src/SConscript', variant_dir='bar')
src/SConscript:
Import('env')
env.Library('a', Split('a1.c a2.c a3.c'))
-libB/SConscript:
+libB/SConscript:
Import('env')
env.Library('b', Split('b1.c b2.c b3.c'))
allows SCons to append the appropriate library
prefix and suffix for the current platform
(for example, 'liba.a' on POSIX systems,
-'a.lib' on Windows).
+\&'a.lib' on Windows).
-.SS Customizing contruction variables from the command line.
+.SS Customizing construction variables from the command line.
The following would allow the C compiler to be specified on the command
-line or in the file custom.py.
+line or in the file custom.py.
.ES
-opts = Options('custom.py')
-opts.Add('CC', 'The C compiler.')
-env = Environment(options=opts)
-Help(opts.GenerateHelpText(env))
+vars = Variables('custom.py')
+vars.Add('CC', 'The C compiler.')
+env = Environment(variables=vars)
+Help(vars.GenerateHelpText(env))
.EE
The user could specify the C compiler on the command line:
cause their size to increase significantly, Microsoft provides a mechanism
for including the debugging information in an external file called a PDB
file. SCons supports PDB files through the PDB construction
-variable.
+variable.
SConstruct:
.ES
projects / scons.git / blobdiff