SConfigure Walkthrough

Release:1.0.b??? Date:August 16, 2009

Here is a quick walkthrough of the SConfigure modules.

Introduction

SConfigure is a package designed to ease the configure process of SCons by creating extensions to the built-in SCons.Tool.Tool class. The objective of this project is to create an easy software environment for distributors as well as developers. A lot of the ideas from this project are borrowed from the python native distutils package.

The added functionality of SConfigure includes:

1. New tools (XTools) that require configuration. (eg. fftw, mpi, other libraries, etc. )
2. Methods of installing, managing configurations XTools.
3. Methods of using XTools.
4. Functions that install files to common Unix installation destinations.
5. Easy to create, and easy to install, binary and source distribution formats.

Configuring New Tools (XTools)

Scons is distributed with tools and allows a developer to extend these with their own tools. SConfigure defines a ToolCreator class that allows tools to be created dynamically at configure time.

These tools can be installed installed into a common location, for the use of a developer. I would like to propose that software libaries and frameworks that are compiled with SCons, create and install these SCons tools so that future developers may use them. I would also like to build up a library of external tools that may be configured with SConfigure. An example of why this is useful is that I have worked on many applications and libraries that require the header and libarary fftw. In each case I have had to get the user to define the location of the fftw if it is not in a standard location, and run a configure check to see if it works properly. With SConfigure, it defines a tool that encapsulates these actions when it is installed The configure section of the SConscript file may only contain:

env.XTool( 'fftw', doraise=True )

This statement checks that the tool exists and adds the proper libraries and paths to the compiler and environment flags. The doraise flag tell the XTool to raise an exception if the tool does not exist. If doraise is False, then the script will continue without exception and the exists() method of the Tool will default to False.

Using XTools

Version Control

XTools provides a developer with the power to control the version and type of the tool. For example, if you need a specific version of the fftw libarary you may include the line:

env.XTool( 'fftw', version=['==2.1.4'], doraise=True )

Or for a range of versions:

env.XTool( 'fftw', version=['<3.0','>=2.0'], doraise=True )

Equivalently:

env.XTool( 'fftw', version=['==2.x'], doraise=True )

The X acts as a wild card character.

If the version is not specified, the latest version is used.

Multiple installations of the same library

Another common issue facing developers is that some libraries may be compiled with different options. We need a way to specify constraints other than just the version. For example fftw2 may only be be compiled with either single or double precision floating point numbers. When SConfigure installs the fftw tool, it gives it this information. for example to specify that we want fftw 2.X with double precision then we use the tool:

env.XTool( 'fftw', version=['==2.x'], precision=['double'] , doraise=True )

Note

I think it may be nesessary to provide a easy way for users to discover what flags a library was compiled with?

The XTool will default to the version with the least amount of flags. The installer can also choose to give a tool default values for these types of flags.

Control flow during build

The most common problem I have found with the SCons configure is the amount of if statements used to control the build. For example you may have a SCons script like this:

# ...
# get paths and do some configure tests
# ...

fftw_exists = configure_test_results

if fftw_exists:

        prog = Program('myfftwtool', 'fftwsource.c', LIBS=[fftwlibs], CPPPATH=[fftwpath], LIBPATH=[fftwlibpath] )
        Alias( 'build' , prog )

With SConfigure you may use the XTool to do this for you:

env.XTool( 'fftw', version=['==2.x'], precision=['double'] )

prog = env.Program('myfftwtool', 'fftwsource.c' )

env.AliasIfExists( 'build', prog )

The command scons build will run the same for both programs if fftw exists or not, but the XTool will give the user warnings when and why the fftw tool is not being created. The second method also allows the developer the option to attempt to build the myfftwtool program regardless of wether or not fftw exists by calling scons myfftwtool directly.

New Functions

The following methods are added to the SCons Environment with the import of sconfig:

from sconfig import *

sconfig adds the standard UNIX configuration option –prefix. All of the following env.InstallXXX() methods have three main functions:

env.AliasIfExists( 'build', target )
ints = env.Install( "${prefix}/${std_location}", target )
env.AliasIfExists( 'install', ints )

This way all of the SConfigure projects have the aliases build and install. The variable ${std_location} differs for each installation method.

env.AliasIfExists(name, target)

env.InstallExecutable(target)

env.InstallLibrary(target)

env.InstallInclude(target)

env.InstallIncludeDir(target)

env.InstallPythonExecutable(target)

env.InstallPythonPackage(target)

env.InstallPythonModule(target)

env.InstallTool(target)

To expand on how this can be useful here is an example script:

from sconfig import *

env_fftw3 = Environment( )
env_fftw3.XTool( 'fftw', version=['==3.x'] )

env_mpi = Environment( )
env_mpi.XTool( 'mpi' )

prog = env_fftw3.Program('myfftwprog', 'fftwsource.c' )
mylib = env_mpi.Library('somelib', 'mpisource.c' )

InstallExecutable( prog )
InstallLibrary( mylib )

On the command scons build, this script will build the program myfftwprog or give the user a warning if fftw does not exist. and build the library libsomelib.a. For the command scons install, libsomelib.a and myfftwprog will be installed to usr/lib and usr/bin respectively.

Note

The command scons install –prefix=usr/local will install items to usr/local/lib and usr/local/bin.

Binary and Source Distribution Formats

More documentation to come...