&SCons; supports a lot of additional functionality
that doesn't readily fit into the other chapters.
Verifying the Python Version: the &EnsurePythonVersion; Function
Although the &SCons; code itself will run
on any Python version 1.5.2 or later,
you are perfectly free to make use of
Python syntax and modules from more modern versions
(for example, Python 2.4 or 2.5)
when writing your &SConscript; files
or your own local modules.
If you do this, it's usually helpful to
configure &SCons; to exit gracefully with an error message
if it's being run with a version of Python
that simply won't work with your code.
This is especially true if you're going to use &SCons;
to build source code that you plan to distribute publicly,
where you can't be sure of the Python version
that an anonymous remote user might use
to try to build your software.
&SCons; provides an &EnsurePythonVersion; function for this.
You simply pass it the major and minor versions
numbers of the version of Python you require:
EnsurePythonVersion(2, 5)
And then &SCons will exit with the following error
message when a user runs it with an unsupported
earlier version of Python:
% scons -Q
Python 2.5 or greater required, but you have Python 2.3.6
Verifying the SCons Version: the &EnsureSConsVersion; Function
You may, of course, write your &SConscript; files
to use features that were only added in
recent versions of &SCons;.
When you publicly distribute software that is built using &SCons;,
it's helpful to have &SCons;
verify the version being used and
exit gracefully with an error message
if the user's version of &SCons; won't work
with your &SConscript; files.
&SCons; provides an &EnsureSConsVersion; function
that verifies the version of &SCons;
in the same
the &EnsurePythonVersion; function
verifies the version of Python,
by passing in the major and minor versions
numbers of the version of SCons you require:
EnsureSConsVersion(1, 0)
And then &SCons will exit with the following error
message when a user runs it with an unsupported
earlier version of &SCons;:
% scons -Q
SCons 1.0 or greater required, but you have SCons 0.98.5
Explicitly Terminating &SCons; While Reading &SConscript; Files: the &Exit; Function
&SCons; supports an &Exit; function
which can be used to terminate &SCons;
while reading the &SConscript; files,
usually because you've detected a condition
under which it doesn't make sense to proceed:
if ARGUMENTS.get('FUTURE'):
print "The FUTURE option is not supported yet!"
Exit(2)
env = Environment()
env.Program('hello.c')
hello.c
scons -Q FUTURE=1
scons -Q
The &Exit; function takes as an argument
the (numeric) exit status that you want &SCons; to exit with.
If you don't specify a value,
the default is to exit with 0,
which indicates successful execution.
Note that the &Exit; function
is equivalent to calling the Python
sys.exit function
(which the it actually calls),
but because &Exit; is a &SCons; function,
you don't have to import the Python
sys module to use it.
Handling Nested Lists: the &Flatten; Function
&SCons; supports a &Flatten; function
which takes an input Python sequence
(list or tuple)
and returns a flattened list
containing just the individual elements of
the sequence.
This can be handy when trying to examine
a list composed of the lists
returned by calls to various Builders.
For example, you might collect
object files built in different ways
into one call to the &Program; Builder
by just enclosing them in a list, as follows:
objects = [
Object('prog1.c'),
Object('prog2.c', CCFLAGS='-DFOO'),
]
Program(objects)
prog1.c
prog2.c
Because the Builder calls in &SCons;
flatten their input lists,
this works just fine to build the program:
scons -Q
But if you were debugging your build
and wanted to print the absolute path
of each object file in the
objects list,
you might try the following simple approach,
trying to print each Node's
abspath
attribute:
objects = [
Object('prog1.c'),
Object('prog2.c', CCFLAGS='-DFOO'),
]
Program(objects)
for object_file in objects:
print object_file.abspath
prog1.c
prog2.c
This does not work as expected
because each call to str
is operating an embedded list returned by
each &Object; call,
not on the underlying Nodes within those lists:
scons -Q
The solution is to use the &Flatten; function
so that you can pass each Node to
the str separately:
objects = [
Object('prog1.c'),
Object('prog2.c', CCFLAGS='-DFOO'),
]
Program(objects)
for object_file in Flatten(objects):
print object_file.abspath
prog1.c
prog2.c
% scons -Q
/home/me/project/prog1.o
/home/me/project/prog2.o
cc -o prog1.o -c prog1.c
cc -o prog2.o -c -DFOO prog2.c
cc -o prog1 prog1.o prog2.o