blob: 878980e60a0d50902e2b0e8e8d5b5308a0741436 [file] [log] [blame]
.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, sublicense, and/or sell copies of the Software, and to
.\" permit persons to whom the Software is furnished to do so, subject to
.\" the following conditions:
.\"
.\" The above copyright notice and this permission notice shall be included
.\" in all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
.\" doc/man/scons.1 5134 2010/08/16 23:02:40 bdeegan
.\"
.TH SCONS 1 "August 2010"
.\" 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
..
.SH NAME
scons \- a software construction tool
.SH SYNOPSIS
.B scons
[
.IR options ...
]
[
.IR name = val ...
]
[
.IR targets ...
]
.SH DESCRIPTION
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
.IR SConstruct ,
.IR Sconstruct ,
or
.I sconstruct
(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
.B -f
option.
The
.I SConstruct
file can specify subsidiary
configuration files using the
.BR SConscript ()
function.
By convention,
these subsidiary files are named
.IR SConscript ,
although any name may be used.
(Because of this naming convention,
the term "SConscript files"
is sometimes used to refer
generically to all
.B scons
configuration files,
regardless of actual file name.)
The configuration files
specify the target files to be built, and
(optionally) the rules to build those targets. Reasonable default
rules exist for building common software components (executable
programs, object files, libraries), so that for most software
projects, only the target and input files need be specified.
Before reading the
.I SConstruct
file,
.B scons
looks for a directory named
.I site_scons
in the directory containing the
.I SConstruct
file; if it exists,
.I site_scons
is added to sys.path,
the file
.IR site_scons/site_init.py ,
is evaluated if it exists,
and the directory
.I site_scons/site_tools
is added to the default toolpath if it exist.
See the
.I --no-site-dir
and
.I --site-dir
options for more details.
.B scons
reads and executes the SConscript files as Python scripts,
so you may use normal Python scripting capabilities
(such as flow control, data manipulation, and imported Python libraries)
to handle complicated build situations.
.BR scons ,
however, reads and executes all of the SConscript files
.I before
it begins building any targets.
To make this obvious,
.B scons
prints the following messages about what it is doing:
.ES
$ scons foo.out
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cp foo.in foo.out
scons: done building targets.
$
.EE
The status messages
(everything except the line that reads "cp foo.in foo.out")
may be suppressed using the
.B -Q
option.
.B scons
does not automatically propagate
the external environment used to execute
.B scons
to the commands used to build target files.
This is so that builds will be guaranteed
repeatable regardless of the environment
variables set at the time
.B scons
is invoked.
This also means that if the compiler or other commands
that you want to use to build your target files
are not in standard system locations,
.B scons
will not find them unless
you explicitly set the PATH
to include those locations.
Whenever you create an
.B scons
construction environment,
you can propagate the value of PATH
from your external environment as follows:
.ES
import os
env = Environment(ENV = {'PATH' : os.environ['PATH']})
.EE
Similarly, if the commands use external environment variables
like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
these variables can also be explicitly propagated:
.ES
import os
env = Environment(ENV = {'PATH' : os.environ['PATH'],
'HOME' : os.environ['HOME']})
.EE
Or you may explicitly propagate the invoking user's
complete external environment:
.ES
import os
env = Environment(ENV = os.environ)
.EE
This comes at the expense of making your build
dependent on the user's environment being set correctly,
but it may be more convenient for many configurations.
.B scons
can scan known input files automatically for dependency
information (for example, #include statements
in C or C++ files) and will rebuild dependent files appropriately
whenever any "included" input file changes.
.B scons
supports the
ability to define new scanners for unknown input file types.
.B scons
knows how to fetch files automatically from
SCCS or RCS subdirectories
using SCCS, RCS or BitKeeper.
.B scons
is normally executed in a top-level directory containing a
.I SConstruct
file, optionally specifying
as command-line arguments
the target file or files to be built.
By default, the command
.ES
scons
.EE
will build all target files in or below the current directory.
Explicit default targets
(to be built when no targets are specified on the command line)
may be defined the SConscript file(s)
using the
.B Default()
function, described below.
Even when
.B Default()
targets are specified in the SConscript file(s),
all target files in or below the current directory
may be built by explicitly specifying
the current directory (.)
as a command-line target:
.ES
scons .
.EE
Building all target files,
including any files outside of the current directory,
may be specified by supplying a command-line target
of the root directory (on POSIX systems):
.ES
scons /
.EE
or the path name(s) of the volume(s) in which all the targets
should be built (on Windows systems):
.ES
scons C:\\ D:\\
.EE
To build only specific targets,
supply them as command-line arguments:
.ES
scons foo bar
.EE
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 usually necessary.
The
.B -c
flag removes all files
necessary to build the specified target:
.ES
scons -c .
.EE
to remove all target files, or:
.ES
scons -c build export
.EE
to remove target files under build and export.
Additional files or directories to remove can be specified using the
.BR Clean()
function.
Conversely, targets that would normally be removed by the
.B -c
invocation
can be prevented from being removed by using the
.BR NoClean ()
function.
A subset of a hierarchical tree may be built by
remaining at the top-level directory (where the
.I SConstruct
file lives) and specifying the subdirectory as the target to be
built:
.ES
scons src/subdir
.EE
or by changing directory and invoking scons with the
.B -u
option, which traverses up the directory
hierarchy until it finds the
.I SConstruct
file, and then builds
targets relatively to the current subdirectory:
.ES
cd src/subdir
scons -u .
.EE
.B scons
supports building multiple targets in parallel via a
.B -j
option that takes, as its argument, the number
of simultaneous tasks that may be spawned:
.ES
scons -j 4
.EE
builds four targets in parallel, for example.
.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
.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-disable ,
and
.B --cache-show
command-line options. The
.B --random
option is useful to prevent multiple builds
from trying to update the cache simultaneously.
Values of variables to be passed to the SConscript file(s)
may be specified on the command line:
.ES
scons debug=1 .
.EE
These variables are available in SConscript files
through the ARGUMENTS dictionary,
and can be used in the SConscript file(s) to modify
the build in any way:
.ES
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS = '-g')
else:
env = Environment()
.EE
The command-line variable arguments are also available
in the ARGLIST list,
indexed by their order on the command line.
This allows you to process them in order rather than by name,
if necessary.
ARGLIST[0] returns a tuple
containing (argname, argvalue).
A Python exception is thrown if you
try to access a list member that
does not exist.
.B scons
requires Python version 2.4 or later.
There should be no other dependencies or requirements to run
.B scons.
.\" The following paragraph reflects the default tool search orders
.\" currently in SCons/Tool/__init__.py. If any of those search orders
.\" change, this documentation should change, too.
By default,
.B scons
knows how to search for available programming tools
on various systems.
On Windows systems,
.B scons
searches in order for the
Microsoft Visual C++ tools,
the MinGW tool chain,
the Intel compiler tools,
and the PharLap ETS compiler.
On OS/2 systems,
.B scons
searches in order for the
OS/2 compiler,
the GCC tool chain,
and the Microsoft Visual C++ tools,
On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
.B scons
searches for the native compiler tools
(MIPSpro, Visual Age, aCC, and Forte tools respectively)
and the GCC tool chain.
On all other platforms,
including POSIX (Linux and UNIX) platforms,
.B scons
searches in order
for the GCC tool chain,
the Microsoft Visual C++ tools,
and the Intel compiler tools.
You may, of course, override these default values
by appropriate configuration of
Environment construction variables.
.SH OPTIONS
In general,
.B scons
supports the same command-line options as GNU
.BR make ,
and many of those supported by
.BR cons .
.TP
-b
Ignored for compatibility with non-GNU versions of
.BR make.
.TP
-c, --clean, --remove
Clean up by removing all target files for which a construction
command is specified.
Also remove any files or directories associated to the construction command
using the
.BR Clean ()
function.
Will not remove any targets specified by the
.BR NoClean ()
function.
.TP
.RI --cache-debug= file
Print debug information about the
.BR CacheDir ()
derived-file caching
to the specified
.IR file .
If
.I file
is
.B \-
(a hyphen),
the debug information are printed to the standard output.
The printed messages describe what signature file names are
being looked for in, retrieved from, or written to the
.BR CacheDir ()
directory tree.
.TP
--cache-disable, --no-cache
Disable the derived-file caching specified by
.BR CacheDir ().
.B scons
will neither retrieve files from the cache
nor copy files to the cache.
.TP
--cache-force, --cache-populate
When using
.BR CacheDir (),
populate a cache by copying any already-existing, up-to-date
derived files to the cache,
in addition to files built by this invocation.
This is useful to populate a new cache with
all the current derived files,
or to add to the cache any derived files
recently built with caching disabled via the
.B --cache-disable
option.
.TP
--cache-show
When using
.BR CacheDir ()
and retrieving a derived file from the cache,
show the command
that would have been executed to build the file,
instead of the usual report,
"Retrieved `file' from cache."
This will produce consistent output for build logs,
regardless of whether a target
file was rebuilt or retrieved from the cache.
.TP
.RI --config= mode
This specifies how the
.B Configure
call should use or generate the
results of configuration tests.
The option should be specified from
among the following choices:
.TP
--config=auto
scons will use its normal dependency mechanisms
to decide if a test must be rebuilt or not.
This saves time by not running the same configuration tests
every time you invoke scons,
but will overlook changes in system header files
or external commands (such as compilers)
if you don't specify those dependecies explicitly.
This is the default behavior.
.TP
--config=force
If this option is specified,
all configuration tests will be re-run
regardless of whether the
cached results are out of date.
This can be used to explicitly
force the configuration tests to be updated
in response to an otherwise unconfigured change
in a system header file or compiler.
.TP
--config=cache
If this option is specified,
no configuration tests will be rerun
and all results will be taken from cache.
Note that scons will still consider it an error
if --config=cache is specified
and a necessary test does not
yet have any results in the cache.
.TP
.RI "-C" " directory" ", --directory=" directory
Change to the specified
.I directory
before searching for the
.IR SConstruct ,
.IR Sconstruct ,
or
.I sconstruct
file, or doing anything
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
.BR "-f directory/SConstruct" ,
except that it will search for
.IR SConstruct ,
.IR Sconstruct ,
or
.I sconstruct
in the specified directory.)
.\" .TP
.\" -d
.\" Display dependencies while building target files. Useful for
.\" figuring out why a specific file is being rebuilt, as well as
.\" general debugging of the build process.
.TP
-D
Works exactly the same way as the
.B -u
option except for the way default targets are handled.
When this option is used and no targets are specified on the command line,
all default targets are built, whether or not they are below the current
directory.
.TP
.RI --debug= type
Debug the build process.
.I type
specifies what type of debugging:
.TP
--debug=count
Print how many objects are created
of the various classes used internally by SCons
before and after reading the SConscript files
and before and after building targets.
This is not supported when SCons is executed with the Python
.B -O
(optimized) option
or when the SCons modules
have been compiled with optimization
(that is, when executing from
.B *.pyo
files).
.TP
--debug=dtree
A synonym for the newer
.B --tree=derived
option.
This will be deprecated in some future release
and ultimately removed.
.TP
--debug=explain
Print an explanation of precisely why
.B scons
is deciding to (re-)build any targets.
(Note: this does not print anything
for targets that are
.I not
rebuilt.)
.TP
--debug=findlibs
Instruct the scanner that searches for libraries
to print a message about each potential library
name it is searching for,
and about the actual libraries it finds.
.TP
--debug=includes
Print the include tree after each top-level target is built.
This is generally used to find out what files are included by the sources
of a given derived file:
.ES
$ scons --debug=includes foo.o
.EE
.TP
--debug=memoizer
Prints a summary of hits and misses using the Memoizer,
an internal subsystem that counts
how often SCons uses cached values in memory
instead of recomputing them each time they're needed.
.TP
--debug=memory
Prints how much memory SCons uses
before and after reading the SConscript files
and before and after building targets.
.TP
--debug=nomemoizer
A deprecated option preserved for backwards compatibility.
.TP
--debug=objects
Prints a list of the various objects
of the various classes used internally by SCons.
.TP
--debug=pdb
Re-run SCons under the control of the
.RI pdb
Python debugger.
.TP
--debug=presub
Print the raw command line used to build each target
before the construction environment variables are substituted.
Also shows which targets are being built by this command.
Output looks something like this:
.ES
$ scons --debug=presub
Building myprog.o with action(s):
$SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
\&...
.EE
.TP
--debug=stacktrace
Prints an internal Python stack trace
when encountering an otherwise unexplained error.
.TP
--debug=stree
A synonym for the newer
.B --tree=all,status
option.
This will be deprecated in some future release
and ultimately removed.
.TP
--debug=time
Prints various time profiling information:
the time spent executing each individual build command;
the total build time (time SCons ran from beginning to end);
the total time spent reading and executing SConscript files;
the total time spent SCons itself spend running
(that is, not counting reading and executing SConscript files);
and both the total time spent executing all build commands
and the elapsed wall-clock time spent executing those build commands.
(When
.B scons
is executed without the
.B -j
option,
the elapsed wall-clock time will typically
be slightly longer than the total time spent
executing all the build commands,
due to the SCons processing that takes place
in between executing each command.
When
.B scons
is executed
.I with
the
.B -j
option,
and your build configuration allows good parallelization,
the elapsed wall-clock time should
be significantly smaller than the
total time spent executing all the build commands,
since multiple build commands and
intervening SCons processing
should take place in parallel.)
.TP
--debug=tree
A synonym for the newer
.B --tree=all
option.
This will be deprecated in some future release
and ultimately removed.
.TP
.RI --diskcheck= types
Enable specific checks for
whether or not there is a file on disk
where the SCons configuration expects a directory
(or vice versa),
and whether or not RCS or SCCS sources exist
when searching for source and include files.
The
.I types
argument can be set to:
.BR all ,
to enable all checks explicitly
(the default behavior);
.BR none ,
to disable all such checks;
.BR match ,
to check that files and directories on disk
match SCons' expected configuration;
.BR rcs ,
to check for the existence of an RCS source
for any missing source or include files;
.BR sccs ,
to check for the existence of an SCCS source
for any missing source or include files.
Multiple checks can be specified separated by commas;
for example,
.B --diskcheck=sccs,rcs
would still check for SCCS and RCS sources,
but disable the check for on-disk matches of files and directories.
Disabling some or all of these checks
can provide a performance boost for large configurations,
or when the configuration will check for files and/or directories
across networked or shared file systems,
at the slight increased risk of an incorrect build
or of not handling errors gracefully
(if include files really should be
found in SCCS or RCS, for example,
or if a file really does exist
where the SCons configuration expects a directory).
.TP
.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
prefer hard links to soft links to copies. You can specify different
behaviours with this option.
.IR ORDER
must be one of
.IR hard-soft-copy
(the default),
.IR soft-hard-copy ,
.IR hard-copy ,
.IR soft-copy
or
.IR copy .
SCons will attempt to duplicate files using
the mechanisms in the specified order.
.\" .TP
.\" -e, --environment-overrides
.\" Variables from the execution environment override construction
.\" variables from the SConscript files.
.TP
.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
Use
.I file
as the initial SConscript file.
Multiple
.B -f
options may be specified,
in which case
.B scons
will read all of the specified files.
.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
.B -H
option for command-line option help. If no local help message
is defined, prints the standard help message about command-line
options. Exits after displaying the appropriate message.
.TP
-H, --help-options
Print the standard help message about command-line options and
exit.
.TP
-i, --ignore-errors
Ignore all errors from commands executed to rebuild files.
.TP
.RI -I " directory" ", --include-dir=" directory
Specifies a
.I directory
to search for
imported Python modules. If several
.B -I
options
are used, the directories are searched in the order specified.
.TP
--implicit-cache
Cache implicit dependencies.
This causes
.B scons
to use the implicit (scanned) dependencies
from the last time it was run
instead of scanning the files for implicit dependencies.
This can significantly speed up SCons,
but with the following limitations:
.IP
.B scons
will not detect changes to implicit dependency search paths
(e.g.
.BR CPPPATH ", " LIBPATH )
that would ordinarily
cause different versions of same-named files to be used.
.IP
.B scons
will miss changes in the implicit dependencies
in cases where a new implicit
dependency is added earlier in the implicit dependency search path
(e.g.
.BR CPPPATH ", " LIBPATH )
than a current implicit dependency with the same name.
.TP
--implicit-deps-changed
Forces SCons to ignore the cached implicit dependencies. This causes the
implicit dependencies to be rescanned and recached. This implies
.BR --implicit-cache .
.TP
--implicit-deps-unchanged
Force SCons to ignore changes in the implicit dependencies.
This causes cached implicit dependencies to always be used.
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
option, the last one is effective.
.\" ??? If the
.\" .B -j
.\" option
.\" is specified without an argument,
.\" .B scons
.\" will not limit the number of
.\" simultaneous jobs.
.TP
-k, --keep-going
Continue as much as possible after an error. The target that
failed and those that depend on it will not be remade, but other
targets specified on the command line will still be processed.
.\" .TP
.\" .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
.\" .I N
.\" (a floating-point number).
.\"
.\" .TP
.\" --list-derived
.\" List derived files (targets, dependencies) that would be built,
.\" but do not build them.
.\" [XXX This can probably go away with the right
.\" combination of other options. Revisit this issue.]
.\"
.\" .TP
.\" --list-actions
.\" List derived files that would be built, with the actions
.\" (commands) that build them. Does not build the files.
.\" [XXX This can probably go away with the right
.\" combination of other options. Revisit this issue.]
.\"
.\" .TP
.\" --list-where
.\" List derived files that would be built, plus where the file is
.\" defined (file name and line number). Does not build the files.
.\" [XXX This can probably go away with the right
.\" combination of other options. Revisit this issue.]
.TP
-m
Ignored for compatibility with non-GNU versions of
.BR make .
.TP
.RI --max-drift= SECONDS
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
will be used instead of
calculating a new content signature (MD5 checksum)
of the file's contents.
The default value is 2 days, which means a file must have a
modification time of at least two days ago in order to have its
cached content signature used.
A negative value means to never cache the content
signature and to ignore the cached value if there already is one. A value
of 0 means to always use the cached signature,
no matter how old the file is.
.TP
.RI --md5-chunksize= KILOBYTES
Set the block size used to compute MD5 signatures to
.IR KILOBYTES .
This value determines the size of the chunks which are read in at once when
computing MD5 signatures. Files below that size are fully stored in memory
before performing the signature computation while bigger files are read in
block-by-block. A huge block-size leads to high memory consumption while a very
small block-size slows down the build considerably.
The default value is to use a chunk size of 64 kilobytes, which should
be appropriate for most uses.
.TP
-n, --just-print, --dry-run, --recon
No execute. Print the commands that would be executed to build
any out-of-date target files, but do not execute the commands.
.TP
.RI --no-site-dir
Prevents the automatic addition of the standard
.I site_scons
dir to
.IR sys.path .
Also prevents loading the
.I site_scons/site_init.py
module if it exists, and prevents adding
.I site_scons/site_tools
to the toolpath.
.\" .TP
.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
.\" Do not rebuild
.\" .IR file ,
.\" and do
.\" not rebuild anything due to changes in the contents of
.\" .IR file .
.\" .TP
.\" .RI --override " file"
.\" Read values to override specific build environment variables
.\" from the specified
.\" .IR file .
.\" .TP
.\" -p
.\" Print the data base (construction environments,
.\" Builder and Scanner objects) that are defined
.\" after reading the SConscript files.
.\" After printing, a normal build is performed
.\" as usual, as specified by other command-line options.
.\" This also prints version information
.\" printed by the
.\" .B -v
.\" option.
.\"
.\" To print the database without performing a build do:
.\"
.\" .ES
.\" scons -p -q
.\" .EE
.TP
.RI --profile= file
Run SCons under the Python profiler
and save the results in the specified
.IR file .
The results may be analyzed using the Python
pstats module.
.TP
-q, --question
Do not run any commands, or print anything. Just return an exit
status that is zero if the specified targets are already up to
date, non-zero otherwise.
.TP
-Q
Quiets SCons status messages about
reading SConscript files,
building targets
and entering directories.
Commands that are executed
to rebuild target files are still printed.
.\" .TP
.\" -r, -R, --no-builtin-rules, --no-builtin-variables
.\" Clear the default construction variables. Construction
.\" environments that are created will be completely empty.
.TP
--random
Build dependencies in a random order. This is useful when
building multiple trees simultaneously with caching enabled,
to prevent multiple builds from simultaneously trying to build
or retrieve the same target files.
.TP
-s, --silent, --quiet
Silent. Do not print commands that are executed to rebuild
target files.
Also suppresses SCons status messages.
.TP
-S, --no-keep-going, --stop
Ignored for compatibility with GNU
.BR make .
.TP
.RI --site-dir= dir
Uses the named dir as the site dir rather than the default
.I site_scons
dir. This dir will get prepended to
.IR sys.path ,
the module
.IR dir /site_init.py
will get loaded if it exists, and
.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 .
(Touching a file to make it
appear up-to-date is unnecessary when using
.BR scons .)
.TP
.RI --taskmastertrace= file
Prints trace information to the specified
.I file
about how the internal Taskmaster object
evaluates and controls the order in which Nodes are built.
A file name of
.B -
may be used to specify the standard output.
.TP
.RI -tree= options
Prints a tree of the dependencies
after each top-level target is built.
This prints out some or all of the tree,
in various formats,
depending on the
.I options
specified:
.TP
--tree=all
Print the entire dependency tree
after each top-level target is built.
This prints out the complete dependency tree,
including implicit dependencies and ignored dependencies.
.TP
--tree=derived
Restricts the tree output to only derived (target) files,
not source files.
.TP
--tree=status
Prints status information for each displayed node.
.TP
--tree=prune
Prunes the tree to avoid repeating dependency information
for nodes that have already been displayed.
Any node that has already been displayed
will have its name printed in
.BR "[square brackets]" ,
as an indication that the dependencies
for that node can be found by searching
for the relevant output higher up in the tree.
.IP
Multiple options may be specified,
separated by commas:
.ES
# Prints only derived files, with status information:
scons --tree=derived,status
# Prints all dependencies of target, with status information
# and pruning dependencies of already-visited Nodes:
scons --tree=all,prune,status target
.EE
.TP
-u, --up, --search-up
Walks up the directory structure until an
.I SConstruct ,
.I Sconstruct
or
.I sconstruct
file is found, and uses that
as the top of the directory tree.
If no targets are specified on the command line,
only targets at or below the
current directory will be built.
.TP
-U
Works exactly the same way as the
.B -u
option except for the way default targets are handled.
When this option is used and no targets are specified on the command line,
all default targets that are defined in the SConscript(s) in the current
directory are built, regardless of what directory the resultant targets end
up in.
.TP
-v, --version
Print the
.B scons
version, copyright information,
list of authors, and any other relevant information.
Then exit.
.TP
-w, --print-directory
Print a message containing the working directory before and
after other processing.
.TP
--no-print-directory
Turn off -w, even if it was turned on implicitly.
.TP
.RI --warn= type ", --warn=no-" type
Enable or disable warnings.
.I type
specifies the type of warnings to be enabled or disabled:
.TP
--warn=all, --warn=no-all
Enables or disables all warnings.
.TP
--warn=cache-write-error, --warn=no-cache-write-error
Enables or disables warnings about errors trying to
write a copy of a built file to a specified
.BR CacheDir ().
These warnings are disabled by default.
.TP
--warn=corrupt-sconsign, --warn=no-corrupt-sconsign
Enables or disables warnings about unfamiliar signature data in
.B .sconsign
files.
These warnings are enabled by default.
.TP
--warn=dependency, --warn=no-dependency
Enables or disables warnings about dependencies.
These warnings are disabled by default.
.TP
--warn=deprecated, --warn=no-deprecated
Enables or disables all warnings about use of
currently deprecated features.
These warnings are enabled by default.
Note that the
.B --warn=no-deprecated
option does not disable warnings about absolutely all deprecated features.
Warnings for some deprecated features that have already been through
several releases with deprecation warnings
may be mandatory for a release or two
before they are officially no longer supported by SCons.
Warnings for some specific deprecated features
may be enabled or disabled individually;
see below.
.RS
.TP
--warn=deprecated-copy, --warn=no-deprecated-copy
Enables or disables warnings about use of the deprecated
.B env.Copy()
method.
.TP
--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
Enables or disables warnings about use of the deprecated
.B SourceSignatures()
function or
.B env.SourceSignatures()
method.
.TP
--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
Enables or disables warnings about use of the deprecated
.B TargetSignatures()
function or
.B env.TargetSignatures()
method.
.RE
.TP
--warn=duplicate-environment, --warn=no-duplicate-environment
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=future-deprecated, --warn=no-future-deprecated
Enables or disables warnings about features
that will be deprecated in the future.
These warnings are disabled by default.
Enabling this warning is especially
recommended for projects that redistribute
SCons configurations for other users to build,
so that the project can be warned as soon as possible
about to-be-deprecated features
that may require changes to the configuration.
.TP
--warn=link, --warn=no-link
Enables or disables warnings about link steps.
.TP
--warn=misleading-keywords, --warn=no-misleading-keywords
Enables or disables warnings about use of the misspelled keywords
.B targets
and
.B sources
when calling Builders.
(Note the last
.B s
characters, the correct spellings are
.B target
and
.B source.)
These warnings are enabled by default.
.TP
--warn=missing-sconscript, --warn=no-missing-sconscript
Enables or disables warnings about missing SConscript files.
These warnings are enabled by default.
.TP
--warn=no-md5-module, --warn=no-no-md5-module
Enables or disables warnings about the version of Python
not having an MD5 checksum module available.
These warnings are enabled by default.
.TP
--warn=no-metaclass-support, --warn=no-no-metaclass-support
Enables or disables warnings about the version of Python
not supporting metaclasses when the
.B --debug=memoizer
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
not being able to support parallel builds when the
.B -j
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
reserved construction variable names
.BR CHANGED_SOURCES ,
.BR CHANGED_TARGETS ,
.BR TARGET ,
.BR TARGETS ,
.BR SOURCE ,
.BR SOURCES ,
.BR UNCHANGED_SOURCES
or
.BR UNCHANGED_TARGETS .
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
.\" .IR file .
.\"
.\" .TP
.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
.\" Pretend that the target
.\" .I file
.\" has been
.\" modified. When used with the
.\" .B -n
.\" option, this
.\" show you what would be rebuilt if you were to modify that file.
.\" Without
.\" .B -n
.\" ... what? XXX
.\"
.\" .TP
.\" --warn-undefined-variables
.\" Warn when an undefined variable is referenced.
.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 be specified, in which case the
repositories are searched in the order specified.
.SH CONFIGURATION FILE REFERENCE
.\" .SS Python Basics
.\" 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
.BR scons .
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
for the current platform.
An optional platform keyword argument may be
used to specify that an environment should
be initialized for a different platform:
.ES
env = Environment(platform = 'cygwin')
env = Environment(platform = 'os2')
env = Environment(platform = 'posix')
env = Environment(platform = 'win32')
.EE
Specifying a platform initializes the appropriate
construction variables in the environment
to use and generate file names with prefixes
and suffixes appropriate for the platform.
Note that the
.B win32
platform adds the
.B SystemDrive
and
.B SystemRoot
variables from the user's external environment
to the construction environment's
.B ENV
dictionary.
This is so that any executed commands
that use sockets to connect with other systems
(such as fetching source files from
external CVS repository specifications like
.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
will work on Windows systems.
The platform argument may be function or callable object,
in which case the Environment() method
will call the specified argument to update
the new construction environment:
.ES
def my_platform(env):
env['VAR'] = 'xyzzy'
env = Environment(platform = my_platform)
.EE
Additionally, a specific set of tools
with which to initialize the environment
may be specified as an optional keyword argument:
.ES
env = Environment(tools = ['msvc', 'lex'])
.EE
Non-built-in tools may be specified using the toolpath argument:
.ES
env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
.EE
This looks for a tool specification in tools/foo.py (as well as
using the ordinary default tools for the platform). foo.py should
have two functions: generate(env, **kw) and exists(env).
The
.B generate()
function
modifies the passed-in environment
to set up variables so that the tool
can be executed;
it may use any keyword arguments
that the user supplies (see below)
to vary its initialization.
The
.B exists()
function should return a true
value if the tool is available.
Tools in the toolpath are used before
any of the built-in ones. For example, adding gcc.py to the toolpath
would override the built-in gcc tool.
Also note that the toolpath is
stored in the environment for use
by later calls to
.BR Clone ()
and
.BR Tool ()
methods:
.ES
base = Environment(toolpath=['custom_path'])
derived = base.Clone(tools=['custom_tool'])
derived.CustomBuilder()
.EE
The elements of the tools list may also
be functions or callable objects,
in which case the Environment() method
will call the specified elements
to update the new construction environment:
.ES
def my_tool(env):
env['XYZZY'] = 'xyzzy'
env = Environment(tools = [my_tool])
.EE
The individual elements of the tools list
may also themselves be two-element lists of the form
.RI ( toolname ", " kw_dict ).
SCons searches for the
.I toolname
specification file as described above, and
passes
.IR kw_dict ,
which must be a dictionary, as keyword arguments to the tool's
.B generate
function.
The
.B generate
function can use the arguments to modify the tool's behavior
by setting up the environment in different ways
or otherwise changing its initialization.
.ES
# in tools/my_tool.py:
def generate(env, **kw):
# Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
env['MY_TOOL'] = kw.get('arg1', '1')
def exists(env):
return 1
# in SConstruct:
env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
toolpath=['tools'])
.EE
The tool definition (i.e. my_tool()) can use the PLATFORM variable from
the environment it receives to customize the tool for different platforms.
If no tool list is specified, then SCons will auto-detect the installed
tools using the PATH variable in the ENV construction variable and the
platform name when the Environment is constructed. Changing the PATH
variable after the Environment is constructed will not cause the tools to
be redetected.
SCons supports the following tool specifications out of the box:
.ES
386asm
aixc++
aixcc
aixf77
aixlink
ar
as
bcc32
c++
cc
cvf
dmd
dvipdf
dvips
f77
f90
f95
fortran
g++
g77
gas
gcc
gfortran
gnulink
gs
hpc++
hpcc
hplink
icc
icl
ifl
ifort
ilink
ilink32
intelc
jar
javac
javah
latex
lex
link
linkloc
m4
masm
midl
mingw
mslib
mslink
mssdk
msvc
msvs
mwcc
mwld
nasm
pdflatex
pdftex
qt
rmic
rpcgen
sgiar
sgic++
sgicc
sgilink
sunar
sunc++
suncc
sunf77
sunf90
sunf95
sunlink
swig
tar
tex
textfile
tlib
yacc
zip
.EE
Additionally, there is a "tool" named
.B default
which configures the
environment with a default set of tools for the current platform.
On posix and cygwin platforms
the GNU tools (e.g. gcc) are preferred by SCons,
on Windows the Microsoft tools (e.g. msvc)
followed by MinGW are preferred by SCons,
and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
.SS Builder Methods
Build rules are specified by calling a construction
environment's builder methods.
The arguments to the builder methods are
.B target
(a list of targets to be built,
usually file names)
and
.B source
(a list of sources to be built,
usually file names).
Because long lists of file names
can lead to a lot of quoting,
.B scons
supplies a
.B Split()
global function
and a same-named environment method
that split a single string
into a list, separated on
strings of white-space characters.
(These are similar to the split() member function of Python strings
but work even if the input isn't a string.)
Like all Python arguments,
the target and source arguments to a builder method
can be specified either with or without
the "target" and "source" keywords.
When the keywords are omitted,
the target is first,
followed by the source.
The following are equivalent examples of calling the Program builder method:
.ES
env.Program('bar', ['bar.c', 'foo.c'])
env.Program('bar', Split('bar.c foo.c'))
env.Program('bar', env.Split('bar.c foo.c'))
env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
env.Program(target = 'bar', Split('bar.c foo.c'))
env.Program(target = 'bar', env.Split('bar.c foo.c'))
env.Program('bar', source = 'bar.c foo.c'.split())
.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,
then the target argument may be omitted completely,
and
.B scons
will deduce the target file name from
the source file name.
The following examples all build the
executable program
.B bar
(on POSIX systems)
or
.B bar.exe
(on Windows systems)
from the bar.c source file:
.ES
env.Program(target = 'bar', source = 'bar.c')
env.Program('bar', source = 'bar.c')
env.Program(source = 'bar.c')
env.Program('bar.c')
.EE
As a convenience, a
.B srcdir
keyword argument may be specified
when calling a Builder.
When specified,
all source file strings that are not absolute paths
will be interpreted relative to the specified
.BR srcdir .
The following example will build the
.B build/prog
(or
.B build/prog.exe
on Windows)
program from the files
.B src/f1.c
and
.BR src/f2.c :
.ES
env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
.EE
It is possible to override or add construction variables when calling a
builder method by passing additional keyword arguments.
These overridden or added
variables will only be in effect when building the target, so they will not
affect other parts of the build. For example, if you want to add additional
libraries for just one program:
.ES
env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
.EE
or generate a shared library with a non-standard suffix:
.ES
env.SharedLibrary('word', 'word.cpp',
SHLIBSUFFIX='.ocx',
LIBSUFFIXES=['.ocx'])
.EE
(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
if you want SCons to search automatically
for dependencies on the non-standard library names;
see the descriptions of these variables, below, for more information.)
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,
methods of a construction environment object,
they may also be called without an explicit environment:
.ES
Program('hello', 'hello.c')
SharedLibrary('word', 'word.cpp')
.EE
In this case,
the methods are called internally using a default construction
environment that consists of the tools and values that
.B scons
has determined are appropriate for the local system.
Builder methods that can be called without an explicit
environment may be called from custom Python modules that you
import into an SConscript file by adding the following
to the Python module:
.ES
from SCons.Script import *
.EE
All builder methods return a list-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-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.
For example, if it were necessary
to add a specific
.B -D
flag when compiling one specific object file:
.ES
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
.EE
Using a Node in this way
makes for a more portable build
by avoiding having to specify
a platform-specific object suffix
when calling the Program() builder method.
Note that Builder calls will automatically "flatten"
the source and target file lists,
so it's all right to have the bar_obj list
return by the StaticObject() call
in the middle of the source file list.
If you need to manipulate a list of lists returned by Builders
directly using Python,
you can either build the list by hand:
.ES
foo = Object('foo.c')
bar = Object('bar.c')
objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
for object in objects:
print str(object)
.EE
Or you can use the
.BR Flatten ()
function supplied by scons
to create a list containing just the Nodes,
which may be more convenient:
.ES
foo = Object('foo.c')
bar = Object('bar.c')
objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
for object in objects:
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()
function:
.ES
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
print "The path to bar_obj is:", str(bar_obj_list[0])
.EE
Note again that because the Builder call returns a list,
we have to access the first element in the list
.B (bar_obj_list[0])
to get at the Node that actually represents
the object file.
Builder calls support a
.B chdir
keyword argument that
specifies that the Builder's action(s)
should be executed
after changing directory.
If the
.B chdir
argument is
a string or a directory Node,
scons will change to the specified directory.
If the
.B chdir
is not a string or Node
and is non-zero,
then scons will change to the
target file's directory.
.ES
# scons will change to the "sub" subdirectory
# before executing the "cp" command.
env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
"cp dir/foo.in dir/foo.out",
chdir='sub')
# Because chdir is not a string, scons will change to the
# target's directory ("sub/dir") before executing the
# "cp" command.
env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
"cp foo.in foo.out",
chdir=1)
.EE
Note that scons will
.I not
automatically modify
its expansion of
construction variables like
.B $TARGET
and
.B $SOURCE
when using the chdir
keyword argument--that is,
the expanded file names
will still be relative to
the top-level SConstruct directory,
and consequently incorrect
relative to the chdir directory.
If you use the chdir keyword argument,
you will typically need to supply a different
command line using
expansions like
.B ${TARGET.file}
and
.B ${SOURCE.file}
to use just the filename portion of the
targets and source.
.B scons
provides the following builder methods:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\" BEGIN GENERATED BUILDER DESCRIPTIONS
'\"
'\" The descriptions below of the various SCons Builders are generated
'\" from the .xml files that live next to the various Python modules in
'\" the build enginer library. If you're reading this [gnt]roff file
'\" with an eye towards patching this man page, you can still submit
'\" a diff against this text, but it will have to be translated to a
'\" diff against the underlying .xml file before the patch is actually
'\" accepted. If you do that yourself, it will make it easier to
'\" integrate the patch.
'\"
'\" BEGIN GENERATED BUILDER DESCRIPTIONS
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP CFile()
.IP env.CFile()
Builds a C source file given a lex (\fB.l\fP)
or yacc (\fB.y\fP) input file.
The suffix specified by the $CFILESUFFIX construction variable
(\fB.c\fP by default)
is automatically added to the target
if it is not already present.
Example:
.ES
# builds foo.c
env.CFile(target = 'foo.c', source = 'foo.l')
# builds bar.c
env.CFile(target = 'bar', source = 'bar.y')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP CXXFile()
.IP env.CXXFile()
Builds a C++ source file given a lex (\fB.ll\fP)
or yacc (\fB.yy\fP)
input file.
The suffix specified by the $CXXFILESUFFIX construction variable
(\fB.cc\fP by default)
is automatically added to the target
if it is not already present.
Example:
.ES
# builds foo.cc
env.CXXFile(target = 'foo.cc', source = 'foo.ll')
# builds bar.cc
env.CXXFile(target = 'bar', source = 'bar.yy')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP DVI()
.IP env.DVI()
Builds a \fB.dvi\fP file
from a \fB.tex\fP,
\fB.ltx\fP or \fB.latex\fP input file.
If the source file suffix is \fB.tex\fP,
.B scons
will examine the contents of the file;
if the string
.B \\documentclass
or
.B \\documentstyle
is found, the file is assumed to be a LaTeX file and
the target is built by invoking the $LATEXCOM command line;
otherwise, the $TEXCOM command line is used.
If the file is a LaTeX file,
the
.BR DVI ()
builder method will also examine the contents
of the
.B .aux
file and invoke the $BIBTEX command line
if the string
.B bibdata
is found,
start $MAKEINDEX to generate an index if a
.B .ind
file is found
and will examine the contents
.B .log
file and re-run the $LATEXCOM command
if the log file says it is necessary.
The suffix \fB.dvi\fP
(hard-coded within TeX itself)
is automatically added to the target
if it is not already present.
Examples:
.ES
# builds from aaa.tex
env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
# builds bbb.dvi
env.DVI(target = 'bbb', source = 'bbb.ltx')
# builds from ccc.latex
env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Install()
.IP env.Install()
Installs one or more source files or directories
in the specified target,
which must be a directory.
The names of the specified source files or directories
remain the same within the destination directory.
.ES
env.Install('/usr/local/bin', source = ['foo', 'bar'])
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP InstallAs()
.IP env.InstallAs()
Installs one or more source files or directories
to specific names,
allowing changing a file or directory name
as part of the installation.
It is an error if the
target
and
source
arguments list different numbers of files or directories.
.ES
env.InstallAs(target = '/usr/local/bin/foo',
source = 'foo_debug')
env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
source = ['libFOO.a', 'libBAR.a'])
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Jar()
.IP env.Jar()
Builds a Java archive (\fB.jar\fP) file
from the specified list of sources.
Any directories in the source list
will be searched for \fB.class\fP files).
Any \fB.java\fP files in the source list
will be compiled to \fB.class\fP files
by calling the \fBJava\fP() Builder.
If the $JARCHDIR value is set, the
.B jar
command will change to the specified directory using the
.B \-C
option.
If $JARCHDIR is not set explicitly,
&SCons; will use the top of any subdirectory tree
in which Java \fB.class\fP
were built by the \fBJava\fP() Builder.
If the contents any of the source files begin with the string
.BR Manifest-Version ,
the file is assumed to be a manifest
and is passed to the
.B jar
command with the
.B m
option set.
.ES
env.Jar(target = 'foo.jar', source = 'classes')
env.Jar(target = 'bar.jar',
source = ['bar1.java', 'bar2.java'])
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Java()
.IP env.Java()
Builds one or more Java class files.
The sources may be any combination of explicit
\fB.java\fP files,
or directory trees which will be scanned
for \fB.java\fP files.
SCons will parse each source \fB.java\fP file
to find the classes
(including inner classes)
defined within that file,
and from that figure out the
target \fB.class\fP files that will be created.
The class files will be placed underneath
the specified target directory.
SCons will also search each Java file
for the Java package name,
which it assumes can be found on a line
beginning with the string
.B package
in the first column;
the resulting \fB.class\fP files
will be placed in a directory reflecting
the specified package name.
For example,
the file
.B Foo.java
defining a single public
.I Foo
class and
containing a package name of
.I sub.dir
will generate a corresponding
.B sub/dir/Foo.class
class file.
Examples:
.ES
env.Java(target = 'classes', source = 'src')
env.Java(target = 'classes', source = ['src1', 'src2'])
env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
.EE
.IP
Java source files can use the native encoding for the underlying OS.
Since SCons compiles in simple ASCII mode by default,
the compiler will generate warnings about unmappable characters,
which may lead to errors as the file is processed further.
In this case, the user must specify the \fBLANG\fP
environment variable to tell the compiler what encoding is used.
For portibility, it's best if the encoding is hard-coded
so that the compile will work if it is done on a system
with a different encoding.
.ES
env = Environment()
env['ENV']['LANG'] = 'en_GB.UTF-8'
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP JavaH()
.IP env.JavaH()
Builds C header and source files for
implementing Java native methods.
The target can be either a directory
in which the header files will be written,
or a header file name which
will contain all of the definitions.
The source can be the names of \fB.class\fP files,
the names of \fB.java\fP files
to be compiled into \fB.class\fP files
by calling the \fBJava\fP() builder method,
or the objects returned from the
.BR Java ()
builder method.
If the construction variable
$JAVACLASSDIR
is set, either in the environment
or in the call to the
.BR JavaH ()
builder method itself,
then the value of the variable
will be stripped from the
beginning of any \fB.class\fP file names.
Examples:
.ES
# builds java_native.h
classes = env.Java(target = 'classdir', source = 'src')
env.JavaH(target = 'java_native.h', source = classes)
# builds include/package_foo.h and include/package_bar.h
env.JavaH(target = 'include',
source = ['package/foo.class', 'package/bar.class'])
# builds export/foo.h and export/bar.h
env.JavaH(target = 'export',
source = ['classes/foo.class', 'classes/bar.class'],
JAVACLASSDIR = 'classes')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Library()
.IP env.Library()
A synonym for the
.BR StaticLibrary ()
builder method.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP LoadableModule()
.IP env.LoadableModule()
On most systems,
this is the same as
.BR SharedLibrary ().
On Mac OS X (Darwin) platforms,
this creates a loadable module bundle.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP M4()
.IP env.M4()
Builds an output file from an M4 input file.
This uses a default $M4FLAGS value of
.BR \-E ,
which considers all warnings to be fatal
and stops on the first warning
when using the GNU version of m4.
Example:
.ES
env.M4(target = 'foo.c', source = 'foo.c.m4')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Moc()
.IP env.Moc()
Builds an output file from a moc input file. Moc input files are either
header files or cxx files. This builder is only available after using the
tool 'qt'. See the $QTDIR variable for more information.
Example:
.ES
env.Moc('foo.h') # generates moc_foo.cc
env.Moc('foo.cpp') # generates foo.moc
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP MSVSProject()
.IP env.MSVSProject()
Builds a Microsoft Visual Studio project file,
and by default builds a solution file as well.
This builds a Visual Studio project file, based on the version of
Visual Studio that is configured (either the latest installed version,
or the version specified by
$MSVS_VERSION
in the Environment constructor).
For Visual Studio 6, it will generate a
.B .dsp
file.
For Visual Studio 7 (.NET) and later versions, it will generate a
.B .vcproj
file.
By default,
this also generates a solution file
for the specified project,
a
.B .dsw
file for Visual Studio 6
or a
.B .sln
file for Visual Studio 7 (.NET).
This behavior may be disabled by specifying
.B auto_build_solution=0
when you call
.BR MSVSProject (),
in which case you presumably want to
build the solution file(s)
by calling the
.BR MSVSSolution ()
Builder (see below).
The \fBMSVSProject\fP() builder
takes several lists of filenames
to be placed into the project file.
These are currently limited to
.BR srcs ,
.BR incs ,
.BR localincs ,
.BR resources ,
and
.BR misc .
These are pretty self-explanatory, but it should be noted that these
lists are added to the $SOURCES construction variable as strings,
NOT as SCons File Nodes. This is because they represent file
names to be added to the project file, not the source files used to
build the project file.
The above filename lists are all optional,
although at least one must be specified
for the resulting project file to be non-empty.
In addition to the above lists of values,
the following values may be specified:
.BR target :
The name of the target
.B .dsp
or
.B .vcproj
file.
The correct
suffix for the version of Visual Studio must be used,
but the
$MSVSPROJECTSUFFIX
construction variable
will be defined to the correct value (see example below).
.BR variant :
The name of this particular variant.
For Visual Studio 7 projects,
this can also be a list of variant names.
These are typically things like "Debug" or "Release", but really
can be anything you want.
For Visual Studio 7 projects,
they may also specify a target platform
separated from the variant name by a
.B |
(vertical pipe)
character:
.BR Debug|Xbox .
The default target platform is Win32.
Multiple calls to
.BR MSVSProject ()
with different variants are allowed;
all variants will be added to the project file with their appropriate
build targets and sources.
.BR buildtarget :
An optional string, node, or list of strings or nodes
(one per build variant), to tell the Visual Studio debugger
what output target to use in what build variant.
The number of
.B buildtarget
entries must match the number of
.B variant
entries.
.BR runfile :
The name of the file that Visual Studio 7 and later
will run and debug.
This appears as the value of the
.B Output
field in the resutling Visual Studio project file.
If this is not specified,
the default is the same as the specified
.B buildtarget
value.
Note that because &SCons; always executes its build commands
from the directory in which the \fBSConstruct\fP file is located,
if you generate a project file in a different directory
than the \fBSConstruct\fP directory,
users will not be able to double-click
on the file name in compilation error messages
displayed in the Visual Studio console output window.
This can be remedied by adding the
Visual C/C++
.B /FC
compiler option to the $CCFLAGS variable
so that the compiler will print
the full path name of any
files that cause compilation errors.
Example usage:
.ES
barsrcs = ['bar.cpp'],
barincs = ['bar.h'],
barlocalincs = ['StdAfx.h']
barresources = ['bar.rc','resource.h']
barmisc = ['bar_readme.txt']
dll = env.SharedLibrary(target = 'bar.dll',
source = barsrcs)
env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
srcs = barsrcs,
incs = barincs,
localincs = barlocalincs,
resources = barresources,
misc = barmisc,
buildtarget = dll,
variant = 'Release')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP MSVSSolution()
.IP env.MSVSSolution()
Builds a Microsoft Visual Studio solution file.
This builds a Visual Studio solution file,
based on the version of Visual Studio that is configured
(either the latest installed version,
or the version specified by
$MSVS_VERSION
in the construction environment).
For Visual Studio 6, it will generate a
.B .dsw
file.
For Visual Studio 7 (.NET), it will
generate a
.B .sln
file.
The following values must be specified:
.BR target :
The name of the target .dsw or .sln file. The correct
suffix for the version of Visual Studio must be used, but the value
$MSVSSOLUTIONSUFFIX
will be defined to the correct value (see example below).
.BR variant :
The name of this particular variant, or a list of variant
names (the latter is only supported for MSVS 7 solutions). These are
typically things like "Debug" or "Release", but really can be anything
you want. For MSVS 7 they may also specify target platform, like this
"Debug|Xbox". Default platform is Win32.
.BR projects :
A list of project file names, or Project nodes returned by calls to the
.BR MSVSProject ()
Builder,
to be placed into the solution file.
It should be noted that these file names are NOT added to the $SOURCES
environment variable in form of files, but rather as strings. This
is because they represent file names to be added to the solution file,
not the source files used to build the solution file.
(NOTE: Currently only one project is supported per solution.)
Example Usage:
.ES
env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
projects = ['bar' + env['MSVSPROJECTSUFFIX']],
variant = 'Release')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Object()
.IP env.Object()
A synonym for the
.BR StaticObject ()
builder method.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Package()
.IP env.Package()
Builds software distribution packages.
Packages consist of files to install and packaging information.
The former may be specified with the \fIsource\fP parameter and may be left out,
in which case the &FindInstalledFiles; function will collect
all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached.
If the \fItarget\fP is not specified
it will be deduced from additional information given to this Builder.
The packaging information is specified
with the help of construction variables documented below.
This information is called a tag to stress that
some of them can also be attached to files with the &Tag; function.
The mandatory ones will complain if they were not specified.
They vary depending on chosen target packager.
The target packager may be selected with the "PACKAGETYPE" command line
option or with the $PACKAGETYPE construction variable. Currently
the following packagers available:
* msi - Microsoft Installer
* rpm - Redhat Package Manger
* ipkg - Itsy Package Management System
* tarbz2 - compressed tar
* targz - compressed tar
* zip - zip file
* src_tarbz2 - compressed tar source
* src_targz - compressed tar source
* src_zip - zip file source
An updated list is always available under the "package_type" option when
running "scons --help" on a project that has packaging activated.
.ES
env = Environment(tools=['default', 'packaging'])
env.Install('/bin/', 'my_program')
env.Package( NAME = 'foo',
VERSION = '1.2.3',
PACKAGEVERSION = 0,
PACKAGETYPE = 'rpm',
LICENSE = 'gpl',
SUMMARY = 'balalalalal',
DESCRIPTION = 'this should be really really long',
X_RPM_GROUP = 'Application/fu',
SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz'
)
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP PCH()
.IP env.PCH()
Builds a Microsoft Visual C++ precompiled header.
Calling this builder method
returns a list of two targets: the PCH as the first element, and the object
file as the second element. Normally the object file is ignored.
This builder method is only
provided when Microsoft Visual C++ is being used as the compiler.
The PCH builder method is generally used in
conjuction with the PCH construction variable to force object files to use
the precompiled header:
.ES
env['PCH'] = env.PCH('StdAfx.cpp')[0]
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP PDF()
.IP env.PDF()
Builds a \fB.pdf\fP file
from a \fB.dvi\fP input file
(or, by extension, a \fB.tex\fP,
.BR .ltx ,
or
\fB.latex\fP input file).
The suffix specified by the $PDFSUFFIX construction variable
(\fB.pdf\fP by default)
is added automatically to the target
if it is not already present. Example:
.ES
# builds from aaa.tex
env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
# builds bbb.pdf from bbb.dvi
env.PDF(target = 'bbb', source = 'bbb.dvi')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP PostScript()
.IP env.PostScript()
Builds a \fB.ps\fP file
from a \fB.dvi\fP input file
(or, by extension, a \fB.tex\fP,
.BR .ltx ,
or
\fB.latex\fP input file).
The suffix specified by the $PSSUFFIX construction variable
(\fB.ps\fP by default)
is added automatically to the target
if it is not already present. Example:
.ES
# builds from aaa.tex
env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
# builds bbb.ps from bbb.dvi
env.PostScript(target = 'bbb', source = 'bbb.dvi')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Program()
.IP env.Program()
Builds an executable given one or more object files
or C, C++, D, or Fortran source files.
If any C, C++, D or Fortran source files are specified,
then they will be automatically
compiled to object files using the
.BR Object ()
builder method;
see that builder method's description for
a list of legal source file suffixes
and how they are interpreted.
The target executable file prefix
(specified by the $PROGPREFIX construction variable; nothing by default)
and suffix
(specified by the $PROGSUFFIX construction variable;
by default, \fB.exe\fP on Windows systems,
nothing on POSIX systems)
are automatically added to the target if not already present.
Example:
.ES
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP RES()
.IP env.RES()
Builds a Microsoft Visual C++ resource file.
This builder method is only provided
when Microsoft Visual C++ or MinGW is being used as the compiler. The
.B .res
(or
.B .o
for MinGW) suffix is added to the target name if no other suffix is given.
The source
file is scanned for implicit dependencies as though it were a C file.
Example:
.ES
env.RES('resource.rc')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP RMIC()
.IP env.RMIC()
Builds stub and skeleton class files
for remote objects
from Java \fB.class\fP files.
The target is a directory
relative to which the stub
and skeleton class files will be written.
The source can be the names of \fB.class\fP files,
or the objects return from the
.BR Java ()
builder method.
If the construction variable
$JAVACLASSDIR
is set, either in the environment
or in the call to the
.BR RMIC ()
builder method itself,
then the value of the variable
will be stripped from the
beginning of any \fB.class \fP
file names.
.ES
classes = env.Java(target = 'classdir', source = 'src')
env.RMIC(target = 'outdir1', source = classes)
env.RMIC(target = 'outdir2',
source = ['package/foo.class', 'package/bar.class'])
env.RMIC(target = 'outdir3',
source = ['classes/foo.class', 'classes/bar.class'],
JAVACLASSDIR = 'classes')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP RPCGenClient()
.IP env.RPCGenClient()
Generates an RPC client stub (\fB_clnt.c\fP) file
from a specified RPC (\fB.x\fP) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
.ES
# Builds src/rpcif_clnt.c
env.RPCGenClient('src/rpcif.x')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP RPCGenHeader()
.IP env.RPCGenHeader()
Generates an RPC header (\fB.h\fP) file
from a specified RPC (\fB.x\fP) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
.ES
# Builds src/rpcif.h
env.RPCGenHeader('src/rpcif.x')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP RPCGenService()
.IP env.RPCGenService()
Generates an RPC server-skeleton (\fB_svc.c\fP) file
from a specified RPC (\fB.x\fP) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
.ES
# Builds src/rpcif_svc.c
env.RPCGenClient('src/rpcif.x')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP RPCGenXDR()
.IP env.RPCGenXDR()
Generates an RPC XDR routine (\fB_xdr.c\fP) file
from a specified RPC (\fB.x\fP) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
.ES
# Builds src/rpcif_xdr.c
env.RPCGenClient('src/rpcif.x')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP SharedLibrary()
.IP env.SharedLibrary()
Builds a shared library
(\fB.so\fP on a POSIX system,
\fB.dll\fP on Windows)
given one or more object files
or C, C++, D or Fortran source files.
If any source files are given,
then they will be automatically
compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
(specified by the $SHLIBPREFIX construction variable;
by default, \fBlib\fP on POSIX systems,
nothing on Windows systems)
and suffix
(specified by the $SHLIBSUFFIX construction variable;
by default, \fB.dll\fP on Windows systems,
\fB.so\fP on POSIX systems)
are automatically added to the target if not already present.
Example:
.ES
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
.EE
.IP
On Windows systems, the
.BR SharedLibrary ()
builder method will always build an import
(\fB.lib\fP) library
in addition to the shared (\fB.dll\fP) library,
adding a \fB.lib\fP library with the same basename
if there is not already a \fB.lib\fP file explicitly
listed in the targets.
Any object files listed in the
.B source
must have been built for a shared library
(that is, using the
.BR SharedObject ()
builder method).
.B scons
will raise an error if there is any mismatch.
On some platforms, there is a distinction between a shared library
(loaded automatically by the system to resolve external references)
and a loadable module (explicitly loaded by user action).
For maximum portability, use the \fBLoadableModule\fP() builder for the latter.
On Windows systems, specifying
.B register=1
will cause the \fB.dll\fP to be
registered after it is built using REGSVR32.
The command that is run
("regsvr32" by default) is determined by $REGSVR construction
variable, and the flags passed are determined by $REGSVRFLAGS. By
default, $REGSVRFLAGS includes the \fB/s\fP option,
to prevent dialogs from popping
up and requiring user attention when it is run. If you change
$REGSVRFLAGS, be sure to include the \fB/s\fP option.
For example,
.ES
env.SharedLibrary(target = 'bar',
source = ['bar.cxx', 'foo.obj'],
register=1)
.EE
.IP
will register \fBbar.dll\fP as a COM object
when it is done linking it.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP SharedObject()
.IP env.SharedObject()
Builds an object file for
inclusion in a shared library.
Source files must have one of the same set of extensions
specified above for the
.BR StaticObject ()
builder method.
On some platforms building a shared object requires additional
compiler option
(e.g. \fB\-fPIC\fP for gcc)
in addition to those needed to build a
normal (static) object, but on some platforms there is no difference between a
shared object and a normal (static) one. When there is a difference, SCons
will only allow shared objects to be linked into a shared library, and will
use a different suffix for shared objects. On platforms where there is no
difference, SCons will allow both normal (static)
and shared objects to be linked into a
shared library, and will use the same suffix for shared and normal
(static) objects.
The target object file prefix
(specified by the $SHOBJPREFIX construction variable;
by default, the same as $OBJPREFIX)
and suffix
(specified by the $SHOBJSUFFIX construction variable)
are automatically added to the target if not already present.
Examples:
.ES
env.SharedObject(target = 'ddd', source = 'ddd.c')
env.SharedObject(target = 'eee.o', source = 'eee.cpp')
env.SharedObject(target = 'fff.obj', source = 'fff.for')
.EE
.IP
Note that the source files will be scanned
according to the suffix mappings in the
.B SourceFileScanner
object.
See the section "Scanner Objects,"
below, for more information.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP StaticLibrary()
.IP env.StaticLibrary()
Builds a static library given one or more object files
or C, C++, D or Fortran source files.
If any source files are given,
then they will be automatically
compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
(specified by the $LIBPREFIX construction variable;
by default, \fBlib\fP on POSIX systems,
nothing on Windows systems)
and suffix
(specified by the $LIBSUFFIX construction variable;
by default, \fB.lib\fP on Windows systems,
\fB.a\fP on POSIX systems)
are automatically added to the target if not already present.
Example:
.ES
env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
.EE
.IP
Any object files listed in the
.B source
must have been built for a static library
(that is, using the
.BR StaticObject ()
builder method).
.B scons
will raise an error if there is any mismatch.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP StaticObject()
.IP env.StaticObject()
Builds a static object file
from one or more C, C++, D, or Fortran source files.
Source files must have one of the following extensions:
.ES
.asm assembly language file
.ASM assembly language file
.c C file
.C Windows: C file
POSIX: C++ file
.cc C++ file
.cpp C++ file
.cxx C++ file
.cxx C++ file
.c++ C++ file
.C++ C++ file
.d D file
.f Fortran file
.F Windows: Fortran file
POSIX: Fortran file + C pre-processor
.for Fortran file
.FOR Fortran file
.fpp Fortran file + C pre-processor
.FPP Fortran file + C pre-processor
.m Object C file
.mm Object C++ file
.s assembly language file
.S Windows: assembly language file
ARM: CodeSourcery Sourcery Lite
.sx assembly language file + C pre-processor
POSIX: assembly language file + C pre-processor
.spp assembly language file + C pre-processor
.SPP assembly language file + C pre-processor
.EE
.IP
The target object file prefix
(specified by the $OBJPREFIX construction variable; nothing by default)
and suffix
(specified by the $OBJSUFFIX construction variable;
\fB.obj\fP on Windows systems,
\fB.o\fP on POSIX systems)
are automatically added to the target if not already present.
Examples:
.ES
env.StaticObject(target = 'aaa', source = 'aaa.c')
env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
.EE
.IP
Note that the source files will be scanned
according to the suffix mappings in
.B SourceFileScanner
object.
See the section "Scanner Objects,"
below, for more information.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Substfile()
.IP env.Substfile()
The \fBSubstfile\fP() builder generates a single text file
by concatenating the source files.
Nested lists of sources are flattened.
$LINESEPARATOR is used to separate the source files;
see the description of \fBTextfile\fP() for details.
If a single source file is present with an \fB.in\fP suffix,
the suffix is stripped and the remainder is used as the default target name.
The prefix and suffix specified by the $SUBSTFILEPREFIX
and $SUBSTFILESUFFIX construction variables
(the null string by default in both cases)
are automatically added to the target if they are not already present.
If a construction variable named $SUBST_DICT is present,
it may be either a Python dictionary or a sequence of (key,value) tuples.
If the former,
the dictionary is converted into a list of tuples in an arbitrary order,
so if one key is a prefix of another key
or if one substitution could be further expanded by another subsitition,
it is unpredictible whether the expansion will occur.
Any occurences in the source of a key
are replaced by the corresponding value,
which may be a Python callable function or a string.
If a value is a function,
it is first called (with no arguments) to produce a string.
The string is \fIsubst\fP-expanded
and the result replaces the key.
.ES
env = Environment(tools = ['default', 'textfile'])
env['prefix'] = '/usr/bin'
script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
env.Substfile('script.in', SUBST_DICT = script_dict)
conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
# UNPREDICTABLE - one key is a prefix of another
bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
env.Substfile('foo.in', SUBST_DICT = bad_foo)
# PREDICTABLE - keys are applied longest first
good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
env.Substfile('foo.in', SUBST_DICT = good_foo)
# UNPREDICTABLE - one substitution could be futher expanded
bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
env.Substfile('bar.in', SUBST_DICT = bad_bar)
# PREDICTABLE - substitutions are expanded in order
good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
env.Substfile('bar.in', SUBST_DICT = good_bar)
# the SUBST_DICT may be in common (and not an override)
substutions = {}
subst = Environment(tools = ['textfile', SUBST_DICT = substitutions)
substitutions['@foo@'] = 'foo'
subst['SUBST_DICT']['@bar@'] = 'bar'
subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
Value('#include "@bar@.h"'),
"common.in",
"pgm1.in"
])
subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
Value('#include "@bar@.h"'),
"common.in",
"pgm2.in"
])
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Tar()
.IP env.Tar()
Builds a tar archive of the specified files
and/or directories.
Unlike most builder methods,
the
.BR Tar ()
builder method may be called multiple times
for a given target;
each additional call
adds to the list of entries
that will be built into the archive.
Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
.B scons
knows about them from other Builder or function calls.
.ES
env.Tar('src.tar', 'src')
# Create the stuff.tar file.
env.Tar('stuff', ['subdir1', 'subdir2'])
# Also add "another" to the stuff.tar file.
env.Tar('stuff', 'another')
# Set TARFLAGS to create a gzip-filtered archive.
env = Environment(TARFLAGS = '-c -z')
env.Tar('foo.tar.gz', 'foo')
# Also set the suffix to .tgz.
env = Environment(TARFLAGS = '-c -z',
TARSUFFIX = '.tgz')
env.Tar('foo')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Textfile()
.IP env.Textfile()
The \fBTextfile\fP() builder generates a single text file.
The source strings constitute the lines;
nested lists of sources are flattened.
$LINESEPARATOR is used to separate the strings.
If present, the $SUBST_DICT construction variable
is used to modify the strings before they are written;
see the \fBSubstfile\fP() description for details.
The prefix and suffix specified by the $TEXTFILEPREFIX
and $TEXTFILESUFFIX construction variables
(the null string and \fB.txt\fP by default, respectively)
are automatically added to the target if they are not already present.
Examples:
.ES
# builds/writes foo.txt
env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
# builds/writes bar.txt
env.Textfile(target = 'bar',
source = ['lalala', 'tanteratei'],
LINESEPARATOR='|*')
# nested lists are flattened automatically
env.Textfile(target = 'blob',
source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
# files may be used as input by wraping them in File()
env.Textfile(target = 'concat', # concatenate files with a marker between
source = [File('concat1'), File('concat2')],
LINESEPARATOR = '====================\\n')
Results are:
foo.txt
....8<----
Goethe
42
Schiller
....8<---- (no linefeed at the end)
bar.txt:
....8<----
lalala|*tanteratei
....8<---- (no linefeed at the end)
blob.txt
....8<----
lalala
Goethe
42
Schiller
tanteratei
....8<---- (no linefeed at the end)
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP TypeLibrary()
.IP env.TypeLibrary()
Builds a Windows type library (\fB.tlb\fP)
file from an input IDL file (\fB.idl\fP).
In addition, it will build the associated inteface stub and
proxy source files,
naming them according to the base name of the \fB.idl\fP file.
For example,
.ES
env.TypeLibrary(source="foo.idl")
.EE
.IP
Will create \fBfoo.tlb\fP,
.BR foo.h ,
.BR foo_i.c ,
.B foo_p.c
and
.B foo_data.c
files.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Uic()
.IP env.Uic()
Builds a header file, an implementation file and a moc file from an ui file.
and returns the corresponding nodes in the above order.
This builder is only available after using the tool 'qt'. Note: you can
specify \fB.ui\fP files directly as source
files to the \fBProgram\fP(),
\fBLibrary\fP() and \fBSharedLibrary\fP() builders
without using this builder. Using this builder lets you override the standard
naming conventions (be careful: prefixes are always prepended to names of
built files; if you don't want prefixes, you may set them to ``).
See the $QTDIR variable for more information.
Example:
.ES
env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP Zip()
.IP env.Zip()
Builds a zip archive of the specified files
and/or directories.
Unlike most builder methods,
the
.BR Zip ()
builder method may be called multiple times
for a given target;
each additional call
adds to the list of entries
that will be built into the archive.
Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
.B scons
knows about them from other Builder or function calls.
.ES
env.Zip('src.zip', 'src')
# Create the stuff.zip file.
env.Zip('stuff', ['subdir1', 'subdir2'])
# Also add "another" to the stuff.tar file.
env.Zip('stuff', 'another')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\" END GENERATED BUILDER DESCRIPTIONS
'\"
'\" The descriptions above of the various SCons Builders are generated
'\" from the .xml files that live next to the various Python modules in
'\" the build enginer library. If you're reading this [gnt]roff file
'\" with an eye towards patching this man page, you can still submit
'\" a diff against this text, but it will have to be translated to a
'\" diff against the underlying .xml file before the patch is actually
'\" accepted. If you do that yourself, it will make it easier to
'\" integrate the patch.
'\"
'\" END GENERATED BUILDER DESCRIPTIONS
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.P
All
targets of builder methods automatically depend on their sources.
An explicit dependency can
be specified using the
.B Depends
method of a construction environment (see below).
In addition,
.B scons
automatically scans
source files for various programming languages,
so the dependencies do not need to be specified explicitly.
By default, SCons can
C source files,
C++ source files,
Fortran source files with
.B .F
(POSIX systems only),
.B .fpp,
or
.B .FPP
file extensions,
and assembly language files with
.B .S
(POSIX systems only),
.B .spp,
or
.B .SPP
files extensions
for C preprocessor dependencies.
SCons also has default support
for scanning D source files,
You can also write your own Scanners
to add support for additional source file types.
These can be added to the default
Scanner object used by the
.BR Object (),
.BR StaticObject (),
and
.BR SharedObject ()
Builders by adding them
to the
.B SourceFileScanner
object.
See the section "Scanner Objects,"
below, for more information about
defining your own Scanner objects
and using the
.B SourceFileScanner
object.
.SS Methods and Functions to Do Things
In addition to Builder methods,
.B scons
provides a number of other construction environment methods
and global functions to
manipulate the build configuration.
Usually, a construction environment method
and global function with the same name both exist
so that you don't have to remember whether
to a specific bit of functionality
must be called with or without a construction environment.
In the following list,
if you call something as a global function
it looks like:
.ES
.RI Function( arguments )
.EE
and if you call something through a construction
environment it looks like:
.ES
.RI env.Function( arguments )
.EE
If you can call the functionality in both ways,
then both forms are listed.
Global functions may be called from custom Python modules that you
import into an SConscript file by adding the following
to the Python module:
.ES
from SCons.Script import *
.EE
Except where otherwise noted,
the same-named
construction environment method
and global function
provide the exact same functionality.
The only difference is that,
where appropriate,
calling the functionality through a construction environment will
substitute construction variables into
any supplied strings.
For example:
.ES
env = Environment(FOO = 'foo')
Default('$FOO')
env.Default('$FOO')
.EE
In the above example,
the first call to the global
.B Default()
function will actually add a target named
.B $FOO
to the list of default targets,
while the second call to the
.B env.Default()
construction environment method
will expand the value
and add a target named
.B foo
to the list of default targets.
For more on construction variable expansion,
see the next section on
construction variables.
Construction environment methods
and global functions supported by
.B scons
include:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
.TP
.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
Creates an Action object for
the specified
.IR action .
See the section "Action Objects,"
below, for a complete explanation of the arguments and behavior.
Note that the
.BR env.Action ()
form of the invocation will expand
construction variables in any argument strings,
including the
.I action
argument, at the time it is called
using the construction variables in the
.I env
construction environment through which
.BR env.Action ()
was called.
The
.BR Action ()
form delays all variable expansion
until the Action object is actually used.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI AddMethod( object, function ", [" name ])
.TP
.RI env.AddMethod( function ", [" name ])
When called with the
.BR AddMethod ()
form,
adds the specified
.I function
to the specified
.I object
as the specified method
.IR name .
When called with the
.BR env.AddMethod ()
form,
adds the specified
.I function
to the construction environment
.I env
as the specified method
.IR name .
In both cases, if
.I name
is omitted or
.BR None ,
the name of the
specified
.I function
itself is used for the method name.
Examples:
.ES
# Note that the first argument to the function to
# be attached as a method must be the object through
# which the method will be called; the Python
# convention is to call it 'self'.
def my_method(self, arg):
print "my_method() got", arg
# Use the global AddMethod() function to add a method
# to the Environment class. This
AddMethod(Environment, my_method)
env = Environment()
env.my_method('arg')
# Add the function as a method, using the function
# name for the method call.
env = Environment()
env.AddMethod(my_method, 'other_method_name')
env.other_method_name('another arg')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI AddOption( arguments )
This function adds a new command-line option to be recognized.
The specified
.I arguments
are the same as supported by the standard Python
.BR optparse.add_option ()
method (with a few additional capabilities noted below);
see the documentation for
.B optparse
for a thorough discussion of its option-processing capabities.
In addition to the arguments and values supported by the
.B optparse.add_option ()
method,
the SCons
.BR AddOption ()
function allows you to set the
.B nargs
keyword value to
.B '?'
(a string with just the question mark)
to indicate that the specified long option(s) take(s) an
.I optional
argument.
When
.B "nargs = '?'"
is passed to the
.BR AddOption ()
function, the
.B const
keyword argument
may be used to supply the "default"
value that should be used when the
option is specified on the command line
without an explicit argument.
If no
.B default=
keyword argument is supplied when calling
.BR AddOption (),
the option will have a default value of
.BR None .
Once a new command-line option has been added with
.BR AddOption (),
the option value may be accessed using
.BR GetOption ()
or
.BR env.GetOption ().
\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
\" Uncomment this when that works. See tigris issue 2105.
\" The value may also be set, using
\" .BR SetOption ()
\" or
\" .BR env.SetOption (),
\" if conditions in a
\" .B SConscript
\" require overriding any default value.
\" Note, however, that a
\" value specified on the command line will
\" .I always
\" override a value set by any SConscript file.
Any specified
.B help=
strings for the new option(s)
will be displayed by the
.B -H
or
.B -h
options
(the latter only if no other help text is
specified in the SConscript files).
The help text for the local options specified by
.BR AddOption ()
will appear below the SCons options themselves,
u