&SCons; has integrated support for multi-platform build configuration
similar to that offered by GNU &Autoconf;,
such as
figuring out what libraries or header files
are available on the local system.
This section describes how to use
this &SCons feature.
This chapter is still under development,
so not everything is explained as well as it should be.
See the &SCons; man page for additional information.
&Configure_Contexts;
The basic framework for multi-platform build configuration
in &SCons; is to attach a &configure_context; to a
construction environment by calling the &Configure; function,
perform a number of checks for
libraries, functions, header files, etc.,
and to then call the configure context's &Finish; method
to finish off the configuration:
env = Environment()
conf = Configure(env)
# Checks for libraries, header files, etc. go here!
env = conf.Finish()
&SCons; provides a number of basic checks,
as well as a mechanism for adding your own custom checks.
Note that &SCons; uses its own dependency
mechanism to determine when a check
needs to be run--that is,
&SCons; does not run the checks
every time it is invoked,
but caches the values returned by previous checks
and uses the cached values unless something has changed.
This saves a tremendous amount
of developer time while working on
cross-platform build issues.
The next sections describe
the basic checks that &SCons; supports,
as well as how to add your own custom checks.
Checking for the Existence of Header Files
Testing the existence of a header file
requires knowing what language the header file is.
A configure context has a &CheckCHeader; method
that checks for the existence of a C header file:
env = Environment()
conf = Configure(env)
if not conf.CheckCHeader('math.h'):
print 'Math.h must be installed!'
Exit(1)
if conf.CheckCHeader('foo.h'):
conf.env.Append('-DHAS_FOO_H')
env = conf.Finish()
Note that you can choose to terminate
the build if a given header file doesn't exist,
or you can modify the construction environment
based on the existence of a header file.
If you need to check for the existence
a C++ header file,
use the &CheckCXXHeader; method:
env = Environment()
conf = Configure(env)
if not conf.CheckCXXHeader('vector.h'):
print 'vector.h must be installed!'
Exit(1)
env = conf.Finish()
Checking for the Availability of a Function
Check for the availability of a specific function
using the &CheckFunc; method:
env = Environment()
conf = Configure(env)
if not conf.CheckFunc('strcpy'):
print 'Did not find strcpy(), using local version'
conf.env.Append(CPPDEFINES = '-Dstrcpy=my_local_strcpy')
env = conf.Finish()
Checking for the Availability of a Library
Check for the availability of a library
using the &CheckLib; method.
You only specify the basename of the library,
you don't need to add a lib
prefix or a .a or .lib suffix:
env = Environment()
conf = Configure(env)
if not conf.CheckLib('m'):
print 'Did not find libm.a or m.lib, exiting!'
Exit(1)
env = conf.Finish()
Because the ability to use a library successfully
often depends on having access to a header file
that describes the library's interface,
you can check for a library
and a header file
at the same time by using the
&CheckLibWithHeader; method:
env = Environment()
conf = Configure(env)
if not conf.CheckLibWithHeader('m', 'math.h', 'c'):
print 'Did not find libm.a or m.lib, exiting!'
Exit(1)
env = conf.Finish()
This is essentially shorthand for
separate calls to the &CheckHeader; and &CheckLib;
functions.
Checking for the Availability of a &typedef;
Check for the availability of a &typedef;
by using the &CheckType; method:
env = Environment()
conf = Configure(env)
if not conf.CheckType('off_t'):
print 'Did not find off_t typedef, assuming int'
conf.env.Append(CCFLAGS = '-Doff_t=int')
env = conf.Finish()
You can also add a string that will be
placed at the beginning of the test file
that will be used to check for the &typedef;.
This provide a way to specify
files that must be included to find the &typedef;:
env = Environment()
conf = Configure(env)
if not conf.CheckType('off_t', '#include <sys/types.h>\n'):
print 'Did not find off_t typedef, assuming int'
conf.env.Append(CCFLAGS = '-Doff_t=int')
env = conf.Finish()
Adding Your Own Custom Checks
A custom check is a Python function
that checks for a certain condition to exist
on the running system,
usually using methods that &SCons;
supplies to take care of the details
of checking whether a compilation succeeds,
a link succeeds,
a program is runnable,
etc.
A simple custom check for the existence of
a specific library might look as follows:
mylib_test_source_file = """
#include <mylib.h>
int main(int argc, char **argv)
{
MyLibrary mylib(argc, argv);
return 0;
}
"""
def CheckMyLibrary(context):
context.Message('Checking for MyLibrary...')
result = context.TryLink(mylib_test_source_file, '.c')
context.Result(result)
return result
The &Message; and &Result; methods
should typically begin and end a custom check to
let the user know what's going on:
the &Message; call prints the
specified message (with no trailing newline)
and the &Result; call prints
yes if the check succeeds and
no if it doesn't.
The &TryLink; method
actually tests for whether the
specified program text
will successfully link.
(Note that a custom check can modify
its check based on any arguments you
choose to pass it,
or by using or modifying the configure context environment
in the context.env attribute.)
This custom check function is
then attached to the &configure_context;
by passing a dictionary
to the &Configure; call
that maps a name of the check
to the underlying function:
env = Environment()
conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary})
You'll typically want to make
the check and the function name the same,
as we've done here,
to avoid potential confusion.
We can then put these pieces together
and actually call the CheckMyLibrary check
as follows:
mylib_test_source_file = """
#include <mylib.h>
int main(int argc, char **argv)
{
MyLibrary mylib(argc, argv);
return 0;
}
"""
def CheckMyLibrary(context):
context.Message('Checking for MyLibrary... ')
result = context.TryLink(mylib_test_source_file, '.c')
context.Result(result)
return result
env = Environment()
conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary})
if not conf.CheckMyLibrary():
print 'MyLibrary is not installed!'
Exit(1)
env = conf.Finish()
# We would then add actual calls like Program() to build
# something using the "env" construction environment.
If MyLibrary is not installed on the system,
the output will look like:
% scons
scons: Reading SConscript file ...
Checking for MyLibrary... failed
MyLibrary is not installed!
If MyLibrary is installed,
the output will look like:
% scons
scons: Reading SConscript file ...
Checking for MyLibrary... failed
scons: done reading SConscript
scons: Building targets ...
.
.
.
Not Configuring When Cleaning Targets
Using multi-platform configuration
as described in the previous sections
will run the configuration commands
even when invoking
scons -c
to clean targets:
% scons -Q -c
Checking for MyLibrary... yes
Removed foo.o
Removed foo
Although running the platform checks
when removing targets doesn't hurt anything,
it's usually unnecessary.
You can avoid this by using the
&GetOption(); method to
check whether the (clean)
option has been invoked on the command line:
env = Environment()
if not env.GetOption('clean'):
conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary})
if not conf.CheckMyLibrary():
print 'MyLibrary is not installed!'
Exit(1)
env = conf.Finish()
% scons -Q -c
Removed foo.o
Removed foo