Authors : Christophe Pradal, Samuel Dufour-Kowalski

Contributors : Pierre Barbier de Reuille

Institutes : CIRAD, INRIA

Type : Pure Python Package

Statut : Devel

License : Cecill-C

SConsX is an extension package of the famous SCons build tool. SConsX aims to simplify the build of complex multi-platform packages (i.e. using C++, Boost.Python and Python).

Like Boost.Jam or qmake, it knows about different types of compiler, and the different steps involved in compiling for Windows and Linux. This knowledge allows the user to describe what needs to be built in high-level terms, without concern for low-level details such as the compiler's specific flags, the way that the operating system handles dynamic libraries. The goal is to be able to write a single, simple, build description (SConsctruct and SConscript ) that is likely to work for several compilers on Linux and Windows. It also has built-in support for variant builds ( e.g.debug, release), options (e.g. include paths and threading options) and dependencies associated with the usage of particular libraries. The build objects are created in a separate build directory, not in the source directory.

SConsX extend SCons by adding knowledge to existing tools that are system dependent (e.g. default options and path, dependencies between tools). All the internal options can be overwited in an external configuration file (named option.py). For each tools, SConsX add also configuration capabilities that mimic autoconf functionalities.

SConsX is just a thin wrapper over SCons. It's easily extendible. You can add new tools as well as new high-level commands.

SConsX is under development. Lot of work have to be done for a better support of new compiler (e.g. Visual C++, mingw), new tools and new functionalities.

SconsX provides a set of tools with default options, configurations and dependencies.

Each tool provides:

• A set of options with default values dependeing on the OS.
• A list of dependecies. For instance, Boost.Python depends on Python.
• A configuration method that use SConf, the configuartion tool used by SCons.
• An update method that update the SCons environment with specific flags.

Available tools are limited but can be easily extended :

• compiler: Define a set of generic flags (e.g. debug or warning) for compilers on various OS.
• builddir: Define a build directory for build objects and sub directories for header files, lib and bin files created during the build.
• install: Define install directories used during the install stage, i.e. exec and exec_prefix, libdir, bindir and includedir as well as datadir.
• Other tools: OpenGL, QT, bison, flex, Boost.Python, …

This is a SConstruct file. See the SCons documentation for more information.

import sconsx
from sconsx import config
 
# Creation of a SCons object
# Set an option file as well as command line args.
option = Options("options.py", ARGUMENTS)
 
# Creation of a SConsX object 
conf = config.Config([ 'install', 'boost.python', 'qt4'])
 
# Update the SCons option with the default settings of each tools
conf.UpdateOptions( options )
 
# Creation of the Scons Environment
env = Environment( options= option )
 
# Update the environment with specific flags defined by SConsX and the user.
conf.Update( env )
 
# Generate an help using the command line scons -h
Help(option.GenerateHelpText(env))
 
SConscript(...)

Another equivalent solution is to use the ALEASolution method provided by SConsX:

import sconsx
from sconsx import config
 
# Creation of a SCons object
# Set an option file as well as command line args.
option = Options("options.py", ARGUMENTS)
 
env = config.ALEASolution(option, [ 'install', 'boost.python', 'qt4'])
 
SConscript(...)

SConsX is available on the GForge repository.

There is one requirement:

• SCons

python setup.py install

SConsX provides a set of tools with, for each tools, a set of options with default values depending on the OS and on the value of previous parameters.

Options may be set on a file (e.g. options.py) or via command line arguments. Each tool may also provide a configure method to test the validity of the configuration.

SConsX add the Config class to SCons.

A Config object maintains a list of tools in a Directed Acyclic Graph. It checks if there is no cyclic dependencies between the tools. If a tool depends on an other tool, it will add automagically its dependencies.

When a method is called on a Config instance, the method will be called on each tools.

• Config Constructor

To create a specific configuration, just create a Config object with the list of require tools:

conf = config.Config([ 'install', 'boost.python'])

In this example, boost.python will add python tool to the list of tools.

Some tools are added by default at the creation, i.e. the compiler tool and the builddir tool.

• add_tool

You can also add a tool after the creation of the Config object:

conf.add_tool('qt')

• Options

This method is used to build and to populate a SCons Option object based on the various tools maintain by the config object. In the next example, the values of the parameters will be retrieved in the option.py file or in the command line parameters. For each parameter, a default value is specified in each tool.

options= conf.Options('option.py',ARGUMENTS)

Add to your SConstruct the following command to generate the list of optional parameters with their default value.

Help(options.GenerateHelpText(env))

On the command line, type:

scons -h

• UpdateOptions

This method is the same than the previous Options method, but you pass as parameter an existing SCons Options object:

# Create a SCons Options instance
options= Options('option.py',ARGUMENTS)
conf.Update( options )

Thus, a same set of options can be shared between various Config instances.

• Update

This is the main method. The Update method update the Environment instance based on each tool strategy and on the values of the default parameters and by the parameters set by the user via the configuration file (e.g. option.py).

conf.Update(env)

For instance, the boost_python tool update the environment as is:

class Boost_Python:
  def update( self, env ):
      """ Update the environment with specific flags """
 
      env.AppendUnique( CPPPATH= [ env['boost_includes'] ] )
      env.AppendUnique( LIBPATH= [ env['boost_lib'] ] )
      env.Append( CPPDEFINES= '$boost_defines' )
      env.Append( CPPFLAGS= '$boost_flags' )
 
      boost_name= 'boost_python'+ env['boost_libs_suffix']
      env.AppendUnique( LIBS= [ boost_name ] )

• Configure

The Configure method test on each tool the validity of the configuration by generating a simple program and trying to build it.

conf.Configure( env )

The compiler tool is set by default when creating a Config object. It defines OS and compiler independant flags like debug or warning. These abstract settings are converted in specific flags for each compiler.

Available compilers are:

• gcc: gcc on linux and win32 with cygwin
• mingw: gcc compiler for win32
• msvc: Visual Studio 6., 7. and 8.

The builddir tool is set by default when creating a Config object.

It set a build directory that allows to separate built files from sources.

The install tool defines where to install various built files on the system like programs, libraries, headers and so on.

The python tool allows to link with the Python library.

The boost_python tool allows to link with the Boost.Python library. It depends on the python tool.

The qt tool allows configure the QT environment. The multithreaded qt library is used rather than the default library if available.

The opengl tool allows to build with the OpenGL library.

The qhull tool allows to build with the C qhull library.

bison and flex tools for setting binary and/or lib path.

gnuplot tool for setting the binary path

pthread, readline and termcap. These tools are required by other tools on Posix system.

SConsX provide high level functions to simplify the complexity of building an OpenAlea package:

A simple script that build a library mypkg from all the cpp files in the current directory, and install all the headers in a specific directory.

includes= env.ALEAGlob('*.h')
env.ALEAIncludes('mypkg',includes)
 
sources= env.ALEAGlob('*.cpp')
env.ALEALibrary('mypkg', sources)

• Configure a default environment with user options and set of tools.
• Generate the help obtained by `scons -h`
• Define the build directory to copy libraries, binaries and includes files.

env = ALEASolution(options, tools=...)

• Build static or dynamic library based on user flags.
• Install the built library and associated files in specific directories.
• Define build and install target.

env.ALEALibrary("mylib", sources, CPPDEFINES=...)

• Install the headers in a specific directory.
• Define build and install target.

env.ALEAIncludes("TheNameOfMyHeaderDirectory", headers)

• Build a program and install it in local and system directories.

env.ALEAProgram("myprog", headers)

Build a python wrapper and install it directly in the python package directory. It is used to build Boost.Python wrappers.

env.ALEAWrapper('../../myPythonDir','_mylib',sources)

Glob files by taking into account the build directory which is not the same as the source directory.

files= env.ALEAGlob('*.cpp',dir= '.')
# or
scons_files= env.ALEAGlob('SConscript','dir='*')

Idem that ALEAGlob, but return a list of directory only.

# return all the directories contain in the current directory.
dirs= env.ALEAGlobDir('*',dir= '.')

Add tools like:

• SWIG
• f2py

API documentation

Sphinx (API and user documentation)