&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:
Options
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 , below.
Variables
Any command-line argument containing an =
(equal sign) is considered a variable setting with the form
variable=value
&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 , below.
Targets
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 , below.
Command-Line Options
&SCons; has many command-line options
that control its behavior.
A &SCons; command-line option
always begins with one or two - (hyphen)
characters.
Not Having to Specify Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable
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
every time,
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
-Q option,
you can set the &SCONSFLAGS;
environment as follows:
def b(target, source, env):
pass
def s(target, source, env):
return " ... [build output] ..."
a = Action(b, strfunction = s)
env = Environment(BUILDERS = {'A' : Builder(action=a)})
env.A('foo.out', 'foo.in')
foo.in
sconsexport SCONSFLAGS="-Q"scons
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.
Getting Values Set by Command-Line Options: the &GetOption; Function
&SCons; provides the &GetOption; function
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,
like so:
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
and the &GetOption; strings for fetching them,
are available in the
section,
below.
Setting Values of Command-Line Options: the &SetOption; Function
You can also set the values of &SCons;
command-line options from within the &SConscript; files
by using the &SetOption; function.
The strings that you use to set the values of &SCons;
command-line options are available in the
section,
below.
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
somewhat system-dependent.
One rough guideline is that the more processors
your system has,
the higher you want to set the
-j value,
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
and the &SetOption; function
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')
foo.in
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
single-processor systems:
scons -Q
But if the $NUM_CPU
environment variable is set,
then we use that for the default number of jobs:
export NUM_CPU="4"scons -Q
But any explicit
-j or --jobs
value the user specifies an the command line is used first,
regardless of whether or not
the $NUM_CPU environment
variable is set:
scons -Q -j 7export NUM_CPU="4"scons -Q -j 3Strings for Getting or Setting Values of &SCons; Command-Line Options
The strings that you can pass to the &GetOption;
and &SetOption; functions usually correspond to the
first long-form option name
(beginning with two hyphen characters: --),
after replacing any remaining hyphen characters
with underscores.
The full list of strings and the variables they
correspond to is as follows:
String for &GetOption; and &SetOption;Command-Line Option(s)cache_debugcache_disablecache_forcecache_showclean,
,
configdirectory,
diskcheckduplicatefile,
,
,
help,
ignore_errorsimplicit_cacheimplicit_deps_changedimplicit_deps_unchangedinteractive,
keep_going,
max_driftno_exec,
,
,
,
no_site_dirnum_jobs,
profile_filequestion,
randomrepository,
,
silent,
,
site_dirstack_sizetaskmastertrace_filewarnAdding Custom Command-Line Options: the &AddOption; Function
&SCons; also allows you to define your own
command-line options with the &AddOption; function.
The &AddOption; function takes the same arguments
as the optparse.add_option function
from the standard Python library.
The &AddOption; function is,
in fact, implemented using a subclass
of the optparse.OptionParser.
Once you have added a custom command-line option
with the &AddOption; function,
the value of the option (if any) is immediately available
using the standard &GetOption; function.
(The value can also be set using &SetOption;,
although that's not very useful in practice
because a default value can be specified in
directly in the &AddOption; call.)
One useful example of using this functionality
is to provide a 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)
foo.in
The above code uses the &GetOption; function
to set the $PREFIX
construction variable to any
value that the user specifies with a command-line
option of --prefix.
Because $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
/usr/bin/ directory:
scons -Q -n
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/installCommand-Line <varname>variable</varname>=<varname>value</varname> Build Variables
You may want to control various aspects
of your build by allowing the user
to specify variable=value
values on the command line.
For example, suppose you
want users to be able to
build a debug version of a program
by running &SCons; as follows:
% scons -Q debug=1
&SCons; provides an &ARGUMENTS; dictionary
that stores all of the
variable=value
assignments from the command line.
This allows you to modify
aspects of your build in response
to specifications on the command line.
(Note that unless you want to require
that users always
specify a variable,
you probably want to use
the Python
ARGUMENTS.get() function,
which allows you to specify a default value
to be used if there is no specification
on the command line.)
The following code sets the &cv-link-CCFLAGS; construction
variable in response to the debug
flag being set in the &ARGUMENTS; dictionary:
env = Environment()
debug = ARGUMENTS.get('debug', 0)
if int(debug):
env.Append(CCFLAGS = '-g')
env.Program('prog.c')
prog.c
This results in the -g
compiler option being used when
debug=1
is used on the command line:
scons -Q debug=0scons -Q debug=0scons -Q debug=1scons -Q debug=1
Notice that &SCons; keeps track of
the last values used to build the object files,
and as a result correctly rebuilds
the object and executable files
only when the value of the debug
argument has changed.
The &ARGUMENTS; dictionary has two minor drawbacks.
First, because it is a dictionary,
it can only store one value for each specified keyword,
and thus only "remembers" the last setting
for each keyword on the command line.
This makes the &ARGUMENTS; dictionary
inappropriate if users should be able to
specify multiple values
on the command line for a given keyword.
Second, it does not preserve
the order in which the variable settings
were specified,
which is a problem if
you want the configuration to
behave differently in response
to the order in which the build
variable settings were specified on the command line.
To accomodate these requirements,
&SCons; provides an &ARGLIST; variable
that gives you direct access to
variable=value
settings on the command line,
in the exact order they were specified,
and without removing any duplicate settings.
Each element in the &ARGLIST; variable
is itself a two-element list
containing the keyword and the value
of the setting,
and you must loop through,
or otherwise select from,
the elements of &ARGLIST; to
process the specific settings you want
in whatever way is appropriate for your configuration.
For example,
the following code to let the user
add to the &CPPDEFINES; construction variable
by specifying multiple
define=
settings on the command line:
cppdefines = []
for key, value in ARGLIST:
if key == 'define':
cppdefines.append(value)
env = Environment(CPPDEFINES = cppdefines)
env.Object('prog.c')
prog.c
Yields the following output:
scons -Q define=FOOscons -Q define=FOO define=BAR
Note that the &ARGLIST; and &ARGUMENTS;
variables do not interfere with each other,
but merely provide slightly different views
into how the user specified
variable=value
settings on the command line.
You can use both variables in the same
&SCons; configuration.
In general, the &ARGUMENTS; dictionary
is more convenient to use,
(since you can just fetch variable
settings through a dictionary access),
and the &ARGLIST; list
is more flexible
(since you can examine the
specific order in which
the user's command-line variabe settings).
Controlling Command-Line Build Variables
Being able to use a command-line build variable like
debug=1 is handy,
but it can be a chore to write specific Python code
to recognize each such variable,
check for errors and provide appropriate messages,
and apply the values to a construction variable.
To help with this,
&SCons; supports a class to
define such build variables easily,
and a mechanism to apply the
build variables to a construction environment.
This allows you to control how the build variables affect
construction environments.
For example, suppose that you want users to set
a &RELEASE; construction variable on the
command line whenever the time comes to build
a program for release,
and that the value of this variable
should be added to the command line
with the appropriate -D option
(or other command line option)
to pass the value to the C compiler.
Here's how you might do that by setting
the appropriate value in a dictionary for the
&cv-link-CPPDEFINES; construction variable:
vars = Variables()
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
env.Program(['foo.c', 'bar.c'])
foo.c
bar.c
This &SConstruct; file first creates a &Variables; object
(the vars = Variables() call),
and then uses the object's &Add;
method to indicate that the &RELEASE;
variable can be set on the command line,
and that its default value will be 0
(the third argument to the &Add; method).
The second argument is a line of help text;
we'll learn how to use it in the next section.
We then pass the created &Variables;
object as a &variables; keyword argument
to the &Environment; call
used to create the construction environment.
This then allows a user to set the
&RELEASE; build variable on the command line
and have the variable show up in
the command line used to build each object from
a C source file:
scons -Q RELEASE=1
NOTE: Before &SCons; release 0.98.1, these build variables
were known as "command-line build options."
The class was actually named the &Options; class,
and in the sections below,
the various functions were named
&BoolOption;, &EnumOption;, &ListOption;,
&PathOption;, &PackageOption; and &AddOptions;.
These older names still work,
and you may encounter them in older
&SConscript; fles,
but their use is discouraged
and will be officially deprecated some day.
Providing Help for Command-Line Build Variables
To make command-line build variables most useful,
you ideally want to provide
some help text that will describe
the available variables
when the user runs scons -h.
You could write this text by hand,
but &SCons; provides an easier way.
&Variables; objects support a
&GenerateHelpText; method
that will, as its name suggests,
generate text that describes
the various variables that
have been added to it.
You then pass the output from this method to
the &Help; function:
vars = Variables('custom.py')
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars)
Help(vars.GenerateHelpText(env))
&SCons; will now display some useful text
when the -h option is used:
scons -Q -h
Notice that the help output shows the default value,
and the current actual value of the build variable.
Reading Build Variables From a File
Giving the user a way to specify the
value of a build variable on the command line
is useful,
but can still be tedious
if users must specify the variable
every time they run &SCons;.
We can let users provide customized build variable settings
in a local file by providing a
file name when we create the
&Variables; object:
vars = Variables('custom.py')
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
env.Program(['foo.c', 'bar.c'])
Help(vars.GenerateHelpText(env))
foo.c
bar.c
RELEASE = 1
This then allows the user to control the &RELEASE;
variable by setting it in the &custom_py; file:
Note that this file is actually executed
like a Python script.
Now when we run &SCons;:
scons -Q
And if we change the contents of &custom_py; to:
vars = Variables('custom.py')
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
env.Program(['foo.c', 'bar.c'])
Help(vars.GenerateHelpText(env))
foo.c
bar.c
RELEASE = 0
The object files are rebuilt appropriately
with the new variable:
scons -QPre-Defined Build Variable Functions
&SCons; provides a number of functions
that provide ready-made behaviors
for various types of command-line build variables.
True/False Values: the &BoolVariable; Build Variable Function
It's often handy to be able to specify a
variable that controls a simple Boolean variable
with a &true; or &false; value.
It would be even more handy to accomodate
users who have different preferences for how to represent
&true; or &false; values.
The &BoolVariable; function
makes it easy to accomodate these
common representations of
&true; or &false;.
The &BoolVariable; function takes three arguments:
the name of the build variable,
the default value of the build variable,
and the help string for the variable.
It then returns appropriate information for
passing to the &Add; method of a &Variables; object, like so:
vars = Variables('custom.py')
vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0))
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
env.Program('foo.c')
foo.c
With this build variable,
the &RELEASE; variable can now be enabled by
setting it to the value yes
or t:
scons -Q RELEASE=yes foo.oscons -Q RELEASE=t foo.o
Other values that equate to &true; include
y,
1,
on
and
all.
Conversely, &RELEASE; may now be given a &false;
value by setting it to
no
or
f:
scons -Q RELEASE=no foo.oscons -Q RELEASE=f foo.o
Other values that equate to &false; include
n,
0,
off
and
none.
Lastly, if a user tries to specify
any other value,
&SCons; supplies an appropriate error message:
scons -Q RELEASE=bad_value foo.oSingle Value From a List: the &EnumVariable; Build Variable Function
Suppose that we want a user to be able to
set a &COLOR; variable
that selects a background color to be
displayed by an application,
but that we want to restrict the
choices to a specific set of allowed colors.
This can be set up quite easily
using the &EnumVariable;,
which takes a list of &allowed_values
in addition to the variable name,
default value,
and help text arguments:
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue')))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
foo.c
The user can now explicity set the &COLOR; build variable
to any of the specified allowed values:
scons -Q COLOR=red foo.oscons -Q COLOR=blue foo.oscons -Q COLOR=green foo.o
But, almost more importantly,
an attempt to set &COLOR;
to a value that's not in the list
generates an error message:
scons -Q COLOR=magenta foo.o
The &EnumVariable; function also supports a way
to map alternate names to allowed values.
Suppose, for example,
that we want to allow the user
to use the word navy as a synonym for
blue.
We do this by adding a ↦ dictionary
that will map its key values
to the desired legal value:
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue'),
map={'navy':'blue'}))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
foo.c
As desired, the user can then use
navy on the command line,
and &SCons; will translate it into blue
when it comes time to use the &COLOR;
variable to build a target:
scons -Q COLOR=navy foo.o
By default, when using the &EnumVariable; function,
arguments that differ
from the legal values
only in case
are treated as illegal values:
scons -Q COLOR=Red foo.oscons -Q COLOR=BLUE foo.oscons -Q COLOR=nAvY foo.o
The &EnumVariable; function can take an additional
&ignorecase; keyword argument that,
when set to 1,
tells &SCons; to allow case differences
when the values are specified:
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue'),
map={'navy':'blue'},
ignorecase=1))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
foo.c
Which yields the output:
scons -Q COLOR=Red foo.oscons -Q COLOR=BLUE foo.oscons -Q COLOR=nAvY foo.oscons -Q COLOR=green foo.o
Notice that an &ignorecase; value of 1
preserves the case-spelling that the user supplied.
If you want &SCons; to translate the names
into lower-case,
regardless of the case used by the user,
specify an &ignorecase; value of 2:
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue'),
map={'navy':'blue'},
ignorecase=2))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
foo.c
Now &SCons; will use values of
red,
green or
blue
regardless of how the user spells
those values on the command line:
scons -Q COLOR=Red foo.oscons -Q COLOR=nAvY foo.oscons -Q COLOR=GREEN foo.oMultiple Values From a List: the &ListVariable; Build Variable Function
Another way in which you might want to allow users
to control a build variable is to
specify a list of one or more legal values.
&SCons; supports this through the &ListVariable; function.
If, for example, we want a user to be able to set a
&COLORS; variable to one or more of the legal list of values:
vars = Variables('custom.py')
vars.Add(ListVariable('COLORS', 'List of colors', 0,
['red', 'green', 'blue']))
env = Environment(variables = vars,
CPPDEFINES={'COLORS' : '"${COLORS}"'})
env.Program('foo.c')
foo.c
A user can now specify a comma-separated list
of legal values,
which will get translated into a space-separated
list for passing to the any build commands:
scons -Q COLORS=red,blue foo.oscons -Q COLORS=blue,green,red foo.o
In addition, the &ListVariable; function
allows the user to specify explicit keywords of
&all; or &none;
to select all of the legal values,
or none of them, respectively:
scons -Q COLORS=all foo.oscons -Q COLORS=none foo.o
And, of course, an illegal value
still generates an error message:
scons -Q COLORS=magenta foo.oPath Names: the &PathVariable; Build Variable Function
&SCons; supports a &PathVariable; function
to make it easy to create a build variable
to control an expected path name.
If, for example, you need to
define a variable in the preprocessor
that controls the location of a
configuration file:
vars = Variables('custom.py')
vars.Add(PathVariable('CONFIG',
'Path to configuration file',
'__ROOT__/etc/my_config'))
env = Environment(variables = vars,
CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
env.Program('foo.c')
foo.c
/opt/location
/opt/location
This then allows the user to
override the &CONFIG; build variable
on the command line as necessary:
scons -Q foo.oscons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o
By default, &PathVariable; checks to make sure
that the specified path exists and generates an error if it
doesn't:
scons -Q CONFIG=__ROOT__/does/not/exist foo.o
&PathVariable; provides a number of methods
that you can use to change this behavior.
If you want to ensure that any specified paths are,
in fact, files and not directories,
use the &PathVariable_PathIsFile; method:
vars = Variables('custom.py')
vars.Add(PathVariable('CONFIG',
'Path to configuration file',
'__ROOT__/etc/my_config',
PathVariable.PathIsFile))
env = Environment(variables = vars,
CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
env.Program('foo.c')
foo.c
/opt/location
Conversely, to ensure that any specified paths are
directories and not files,
use the &PathVariable_PathIsDir; method:
vars = Variables('custom.py')
vars.Add(PathVariable('DBDIR',
'Path to database directory',
'__ROOT__/var/my_dbdir',
PathVariable.PathIsDir))
env = Environment(variables = vars,
CPPDEFINES={'DBDIR' : '"$DBDIR"'})
env.Program('foo.c')
foo.c
/opt/location
If you want to make sure that any specified paths
are directories,
and you would like the directory created
if it doesn't already exist,
use the &PathVariable_PathIsDirCreate; method:
vars = Variables('custom.py')
vars.Add(PathVariable('DBDIR',
'Path to database directory',
'__ROOT__/var/my_dbdir',
PathVariable.PathIsDirCreate))
env = Environment(variables = vars,
CPPDEFINES={'DBDIR' : '"$DBDIR"'})
env.Program('foo.c')
foo.c
/opt/location
Lastly, if you don't care whether the path exists,
is a file, or a directory,
use the &PathVariable_PathAccept; method
to accept any path that the user supplies:
vars = Variables('custom.py')
vars.Add(PathVariable('OUTPUT',
'Path to output file or directory',
None,
PathVariable.PathAccept))
env = Environment(variables = vars,
CPPDEFINES={'OUTPUT' : '"$OUTPUT"'})
env.Program('foo.c')
foo.c
Enabled/Disabled Path Names: the &PackageVariable; Build Variable Function
Sometimes you want to give users
even more control over a path name variable,
allowing them to explicitly enable or
disable the path name
by using yes or no keywords,
in addition to allow them
to supply an explicit path name.
&SCons; supports the &PackageVariable;
function to support this:
vars = Variables('custom.py')
vars.Add(PackageVariable('PACKAGE',
'Location package',
'__ROOT__/opt/location'))
env = Environment(variables = vars,
CPPDEFINES={'PACKAGE' : '"$PACKAGE"'})
env.Program('foo.c')
foo.c
/opt/location
/opt/location
When the &SConscript; file uses the &PackageVariable; funciton,
user can now still use the default
or supply an overriding path name,
but can now explicitly set the
specified variable to a value
that indicates the package should be enabled
(in which case the default should be used)
or disabled:
scons -Q foo.oscons -Q PACKAGE=__ROOT__/usr/local/location foo.oscons -Q PACKAGE=yes foo.oscons -Q PACKAGE=no foo.oAdding Multiple Command-Line Build Variables at Once
Lastly, &SCons; provides a way to add
multiple build variables to a &Variables; object at once.
Instead of having to call the &Add; method
multiple times,
you can call the &AddVariables;
method with a list of build variables
to be added to the object.
Each build variable is specified
as either a tuple of arguments,
just like you'd pass to the &Add; method itself,
or as a call to one of the pre-defined
functions for pre-packaged command-line build variables.
in any order:
vars = Variables()
vars.AddVariables(
('RELEASE', 'Set to 1 to build for release', 0),
('CONFIG', 'Configuration file', '/etc/my_config'),
BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
EnumVariable('debug', 'debug output and symbols', 'no',
allowed_values=('yes', 'no', 'full'),
map={}, ignorecase=0), # case sensitive
ListVariable('shared',
'libraries to build as shared libraries',
'all',
names = list_of_libs),
PackageVariable('x11',
'use X11 installed here (yes = search some places)',
'yes'),
PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
)
Handling Unknown Command-Line Build Variables: the &UnknownVariables; Function
Users may, of course,
occasionally misspell variable names in their command-line settings.
&SCons; does not generate an error or warning
for any unknown variables the users specifies on the command line.
(This is in no small part because you may be
processing the arguments directly using the &ARGUMENTS; dictionary,
and therefore &SCons; can't know in the general case
whether a given "misspelled" variable is
really unknown and a potential problem,
or something that your &SConscript; file
will handle directly with some Python code.)
If, however, you're using a &Variables; object to
define a specific set of command-line build variables
that you expect users to be able to set,
you may want to provide an error
message or warning of your own
if the user supplies a variable setting
that is not among
the defined list of variable names known to the &Variables; object.
You can do this by calling the &UnknownVariables;
method of the &Variables; object:
vars = Variables(None)
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
unknown = vars.UnknownVariables()
if unknown:
print "Unknown variables:", unknown.keys()
Exit(1)
env.Program('foo.c')
foo.c
The &UnknownVariables; method returns a dictionary
containing the keywords and values
of any variables the user specified on the command line
that are not
among the variables known to the &Variables; object
(from having been specified using
the &Variables; object's&Add; method).
In the examble above,
we check for whether the dictionary
returned by the &UnknownVariables; is non-empty,
and if so print the Python list
containing the names of the unknwown variables
and then call the &Exit; function
to terminate &SCons;:
scons -Q NOT_KNOWN=foo
Of course, you can process the items in the
dictionary returned by the &UnknownVariables; function
in any way appropriate to your build configuration,
including just printing a warning message
but not exiting,
logging an error somewhere,
etc.
Note that you must delay the call of &UnknownVariables;
until after you have applied the &Variables; object
to a construction environment
with the variables=
keyword argument of an &Environment; call.
Command-Line TargetsFetching Command-Line Targets: the &COMMAND_LINE_TARGETS; Variable
&SCons; supports a &COMMAND_LINE_TARGETS; variable
that lets you fetch the list of targets that the
user specified on the command line.
You can use the targets to manipulate the
build in any way you wish.
As a simple example,
suppose that you want to print a reminder
to the user whenever a specific program is built.
You can do this by checking for the
target in the &COMMAND_LINE_TARGETS; list:
if 'bar' in COMMAND_LINE_TARGETS:
print "Don't forget to copy `bar' to the archive!"
Default(Program('foo.c'))
Program('bar.c')
foo.c
foo.c
Then, running &SCons; with the default target
works as it always does,
but explicity specifying the &bar; target
on the command line generates the warning message:
scons -Qscons -Q bar
Another practical use for the &COMMAND_LINE_TARGETS; variable
might be to speed up a build
by only reading certain subsidiary &SConscript;
files if a specific target is requested.
Controlling the Default Targets: the &Default; Function
One of the most basic things you can control
is which targets &SCons; will build by default--that is,
when there are no targets specified on the command line.
As mentioned previously,
&SCons; will normally build every target
in or below the current directory
by default--that is, when you don't
explicitly specify one or more targets
on the command line.
Sometimes, however, you may want
to specify explicitly that only
certain programs, or programs in certain directories,
should be built by default.
You do this with the &Default; function:
env = Environment()
hello = env.Program('hello.c')
env.Program('goodbye.c')
Default(hello)
hello.c
goodbye.c
This &SConstruct; file knows how to build two programs,
&hello; and &goodbye;,
but only builds the
&hello; program by default:
scons -Qscons -Qscons -Q goodbye
Note that, even when you use the &Default;
function in your &SConstruct; file,
you can still explicitly specify the current directory
(.) on the command line
to tell &SCons; to build
everything in (or below) the current directory:
scons -Q .
You can also call the &Default;
function more than once,
in which case each call
adds to the list of targets to be built by default:
env = Environment()
prog1 = env.Program('prog1.c')
Default(prog1)
prog2 = env.Program('prog2.c')
prog3 = env.Program('prog3.c')
Default(prog3)
prog1.c
prog2.c
prog3.c
Or you can specify more than one target
in a single call to the &Default; function:
env = Environment()
prog1 = env.Program('prog1.c')
prog2 = env.Program('prog2.c')
prog3 = env.Program('prog3.c')
Default(prog1, prog3)
Either of these last two examples
will build only the
prog1
and
prog3
programs by default:
scons -Qscons -Q .
You can list a directory as
an argument to &Default;:
env = Environment()
env.Program(['prog1/main.c', 'prog1/foo.c'])
env.Program(['prog2/main.c', 'prog2/bar.c'])
Default('prog1')
int main() { printf("prog1/main.c\n"); }
int foo() { printf("prog1/foo.c\n"); }
int main() { printf("prog2/main.c\n"); }
int bar() { printf("prog2/bar.c\n"); }
In which case only the target(s) in that
directory will be built by default:
scons -Qscons -Qscons -Q .
Lastly, if for some reason you don't want
any targets built by default,
you can use the Python None
variable:
env = Environment()
prog1 = env.Program('prog1.c')
prog2 = env.Program('prog2.c')
Default(None)
prog1.c
prog2.c
Which would produce build output like:
scons -Qscons -Q .Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable
&SCons; supports a &DEFAULT_TARGETS; variable
that lets you get at the current list of default targets.
The &DEFAULT_TARGETS variable has
two important differences from the &COMMAND_LINE_TARGETS; variable.
First, the &DEFAULT_TARGETS; variable is a list of
internal &SCons; nodes,
so you need to convert the list elements to strings
if you want to print them or look for a specific target name.
Fortunately, you can do this easily
by using the Python map function
to run the list through str:
prog1 = Program('prog1.c')
Default(prog1)
print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
prog1.c
(Keep in mind that all of the manipulation of the
&DEFAULT_TARGETS; list takes place during the
first phase when &SCons; is reading up the &SConscript; files,
which is obvious if
we leave off the -Q flag when we run &SCons;:)
scons
Second,
the contents of the &DEFAULT_TARGETS; list change
in response to calls to the &Default: function,
as you can see from the following &SConstruct; file:
prog1 = Program('prog1.c')
Default(prog1)
print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
prog2 = Program('prog2.c')
Default(prog2)
print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
prog1.c
prog2.c
Which yields the output:
scons
In practice, this simply means that you
need to pay attention to the order in
which you call the &Default; function
and refer to the &DEFAULT_TARGETS; list,
to make sure that you don't examine the
list before you've added the default targets
you expect to find in it.
Fetching the List of Build Targets, Regardless of Origin: the &BUILD_TARGETS; Variable
We've already been introduced to the
&COMMAND_LINE_TARGETS; variable,
which contains a list of targets specified on the command line,
and the &DEFAULT_TARGETS; variable,
which contains a list of targets specified
via calls to the &Default; method or function.
Sometimes, however,
you want a list of whatever targets
&SCons; will try to build,
regardless of whether the targets came from the
command line or a &Default; call.
You could code this up by hand, as follows:
if COMMAND_LINE_TARGETS:
targets = COMMAND_LINE_TARGETS
else:
targets = DEFAULT_TARGETS
&SCons;, however, provides a convenient
&BUILD_TARGETS; variable
that eliminates the need for this by-hand manipulation.
Essentially, the &BUILD_TARGETS; variable
contains a list of the command-line targets,
if any were specified,
and if no command-line targets were specified,
it contains a list of the targets specified
via the &Default; method or function.
Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
you must convert the list elements to strings
if you want to print them or look for a specific target name,
just like the &DEFAULT_TARGETS; list:
prog1 = Program('prog1.c')
Program('prog2.c')
Default(prog1)
print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
prog1.c
prog2.c
Notice how the value of &BUILD_TARGETS;
changes depending on whether a target is
specified on the command line:
scons -Qscons -Q prog2scons -Q -c .