SCons provides a number of ways for the writer of the SConscript files to give the users who will run SCons a great deal of control over the build execution. The arguments that the user can specify on the command line are broken down into three types:
Command-line options always begin with one or two - (hyphen) characters. SCons provides ways for you to examine and set options values from within your SConscript files, as well as the ability to define your own custom options. See Section 10.1, below.
Any command-line argument containing an =
(equal sign) is considered a variable setting with the form
SCons provides direct access to
all of the command-line variable settings,
the ability to apply command-line variable settings
to construction environments,
and functions for configuring
specific types of variables
(Boolean values, path names, etc.)
with automatic validation of the user's specified values.
See Section 10.2, below.
Any command-line argument that is not an option or a variable setting (does not begin with a hyphen and does not contain an equal sign) is considered a target that the user (presumably) wants SCons to build. A list of Node objects representing the target or targets to build. SCons provides access to the list of specified targets, as well as ways to set the default list of targets from within the SConscript files. See Section 10.3, below.
SCons has many command-line options that control its behavior. A SCons command-line option always begins with one or two - (hyphen) characters.
Users may find themselves supplying
the same command-line options every time
they run SCons.
For example, you might find it saves time
to specify a value of -j 2
to have SCons run up to two build commands in parallel.
To avoid having to type -j 2 by hand
you can set the external environment variable
SCONSFLAGS to a string containing
command-line options that you want SCons to use.
If, for example,
you're using a POSIX shell that's
compatible with the Bourne shell,
and you always want SCons to use the
you can set the
environment as follows:
% scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... ... [build output] ... scons: done building targets. % export SCONSFLAGS="-Q" % scons ... [build output] ...
Users of csh-style shells on POSIX systems
can set the
SCONSFLAGS environment as follows:
$ setenv SCONSFLAGS "-Q"
Windows users may typically want to set the
SCONSFLAGS in the appropriate tab of the
System Properties window.
SCons provides the
to get the values set by the various command-line options.
One common use of this is to check whether or not
the -h or --help option
has been specified.
Normally, SCons does not print its help text
until after it has read all of the SConscript files,
because it's possible that help text has been added
by some subsidiary SConscript file deep in the
source tree hierarchy.
Of course, reading all of the SConscript files
takes extra time.
If you know that your configuration does not define
any additional help text in subsidiary SConscript files,
you can speed up the command-line help available to users
by using the
GetOption function to load the
subsidiary SConscript files only if the
the user has not specified
the -h or --help option,
if not GetOption('help'): SConscript('src/SConscript', export='env')
In general, the string that you pass to the
GetOption function to fetch the value of a command-line
option setting is the same as the "most common" long option name
(beginning with two hyphen characters),
although there are some exceptions.
The list of SCons command-line options
GetOption strings for fetching them,
are available in the
Section 10.1.4 section,
You can also set the values of SCons
command-line options from within the SConscript files
by using the
The strings that you use to set the values of SCons
command-line options are available in the
Section 10.1.4 section,
One use of the
SetOption function is to
specify a value for the -j
or --jobs option,
so that users get the improved performance
of a parallel build without having to specify the option by hand.
A complicating factor is that a good value
for the -j option is
One rough guideline is that the more processors
your system has,
the higher you want to set the
in order to take advantage of the number of CPUs.
For example, suppose the administrators
of your development systems
have standardized on setting a
NUM_CPU environment variable
to the number of processors on each system.
A little bit of Python code
to access the environment variable
provide the right level of flexibility:
import os num_cpu = int(os.environ.get('NUM_CPU', 2)) SetOption('num_jobs', num_cpu) print "running with -j", GetOption('num_jobs')
The above snippet of code
sets the value of the --jobs option
to the value specified in the
$NUM_CPU environment variable.
(This is one of the exception cases
where the string is spelled differently from
the from command-line option.
The string for fetching or setting the --jobs
value is num_jobs
for historical reasons.)
The code in this example prints the num_jobs
value for illustrative purposes.
It uses a default value of 2
to provide some minimal parallelism even on
% scons -Q running with -j 2 scons: `.' is up to date.
But if the
environment variable is set,
then we use that for the default number of jobs:
% export NUM_CPU="4" % scons -Q running with -j 4 scons: `.' is up to date.
But any explicit
-j or --jobs
value the user specifies an the command line is used first,
regardless of whether or not
variable is set:
% scons -Q -j 7 running with -j 7 scons: `.' is up to date. % export NUM_CPU="4" % scons -Q -j 3 running with -j 3 scons: `.' is up to date.
The strings that you can pass to the
SetOption functions usually correspond to the
first long-form option name
(beginning with two hyphen characters: --),
after replacing any remaining hyphen characters
The full list of strings and the variables they correspond to is as follows:
|String for ||Command-Line Option(s)|
SCons also allows you to define your own
command-line options with the
AddOption function takes the same arguments
from the standard Python library.
Once you have added a custom command-line option
the value of the option (if any) is immediately available
using the standard
(The value can also be set using
although that's not very useful in practice
because a default value can be specified in
directly in the
One useful example of using this functionality
is to provide a
--prefix for users:
AddOption('--prefix', dest='prefix', type='string', nargs=1, action='store', metavar='DIR', help='installation prefix') env = Environment(PREFIX = GetOption('prefix')) installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in') Default(installed_foo)
The above code uses the
to set the
construction variable to any
value that the user specifies with a command-line
option of --prefix.
will expand to a null string if it's not initialized,
running SCons without the
option of --prefix
will install the file in the
% scons -Q -n Install file: "foo.in" as "/usr/bin/foo.in"
But specifying --prefix=/tmp/install on the command line causes the file to be installed in the /tmp/install/usr/bin/ directory:
% scons -Q -n --prefix=/tmp/install Install file: "foo.in" as "/tmp/install/usr/bin/foo.in"