Home | Download/Install | Documentation | Packages | Screenshots | News | Forum/Mailing-lists | Contact | GForge

For the up-to-date documentation of Sconsx, consult the sphinx pages

Sphinx (API and user documentation)

This wiki page is obsolet.

OpenAlea.SConsX

Authors : Christophe Pradal, Samuel Dufour-Kowalski

Contributors : Pierre Barbier de Reuille

Institutes : CIRAD, INRIA

Type : Pure Python Package

Statut : Devel

License : Cecill-C

About

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.

Description

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, …

Quick Example

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(...)

Installation

Download

SConsX is available on the GForge repository.

Requirements

There is one requirement:

Installation

python setup.py install

Technical Documentation

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.

The Config object

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 methods
  • 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 )

Available Tools with Options


Compiler

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.
Variable name Semantic Default
debug Build in a debug mode False
warnings Compilation with -Wall and similar False
static Build static libraries rather than dynamic one False
compiler Compiler tool used for the build Linux: gcc
Windows: msvc or mingw
rpath List of paths to search for shared libraries on Linux None
EXTRA_CXXFLAGS Specific user flags for c++ compiler None
EXTRA_CPPDEFINES Specific c++ defines None
EXTRA_LINKFLAGS Specific user flags for c++ linker None
EXTRA_CPPPATH Specific user include path None
EXTRA_LIBPATH Specific user library path None
EXTRA_LIBS Specific user libraries None

Build Directory

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.

Variable name Semantic Default
with_build_dir build files in a separate directory? (yes/no) True, yes, 1
build_prefix root of the build directory Linux: build-linux
Windows: build-win32

Install

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

Variable name Semantic Default
prefix install architecture-independent files ( /path/to/prefix ) Linux: /usr/local
Windows: C:\local
exec_prefix install architecture-dependent files ( /path/to/exec_prefix ) $prefix
bindir user executables ( /path/to/bindir ) $prefix/bin
libdir object code libraries ( /path/to/libdir ) $prefix/lib
includedir header files ( /path/to/includedir ) $prefix/include
datadir data ( /path/to/datadir ) $prefix/share
program_prefix prepend prefix to installed program names
program_suffix append suffix to installed program names
lib_prefix prepend prefix to installed library names
lib_suffix append suffix to installed library names

Python

The python tool allows to link with the Python library.

Variable name Semantic Default
python_includes Python include files ( /path/to/python_includes )
python_lib Python library path ( /path/to/python_includes )

Boost.Python

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

Variable name Semantic Default
boost_includes Boost_python include files ( /path/to/boost_includes ) /usr/include
boost_lib Boost_python libraries path ( /path/to/boost_lib ) /usr/lib
boost_flags Boost_python compiler flags None
boost_defines Boost_python defines None
boost_libs_suffix Boost_python library suffix name like -vc80-mt or -gcc None

QT 3

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

Variable name Semantic Default
QTDIR QT directory QTDIR environment variable
QT_CPPPATH QT include directory $QTDIR/include
QT_LIBPATH QT lib directory $QTDIR/lib
QT_BINPATH QT bin directory $QTDIR/bin

OpenGL

The opengl tool allows to build with the OpenGL library.

Variable name Semantic Default
gl_includes GL include files ( /path/to/gl_includes ) Posix: /usr/X11R6/include
Windows: Visual include path
gl_lib GL library path ( /path/to/gl_lib ) Posix: /usr/X11R6/lib
Windows: Visual lib path

QHull

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

Variable name Semantic Default
qhull_includes Qhull include files /usr/include
qhull_lib Qhull library path /usr/lib
qhull_libs_suffix Qhull library suffix name like -vc80 or -mingw None

Bison and Flex

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

Variable name Semantic
bison_bin Bison binary path
flex_bin Flex binary path
flex_lib Flex library path

gnuplot

gnuplot tool for setting the binary path

Variable name Semantic
gnuplot_bin Gnuplot binary path ( /path/to/gnuplot_bin )

Posix only tools

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

Variable name Semantic Default
pthread_includes pthread include files /usr/include
pthread_lib pthread library path /usr/lib
readline_includes readline include files /usr/include
readline_lib readline library path /usr/lib
termcap_includes termcap include files /usr/include
termcap_lib termcap library path /usr/lib

High-level functions for OpenAlea developpers

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

Usage

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)
ALEASolution
  • 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=...)
ALEALibrary
  • 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=...)
ALEAIncludes
  • Install the headers in a specific directory.
  • Define build and install target.
env.ALEAIncludes("TheNameOfMyHeaderDirectory", headers)
ALEAProgram
  • Build a program and install it in local and system directories.
env.ALEAProgram("myprog", headers)
ALEAWrapper

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)
ALEAGlob

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='*')
ALEAGlobDir

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

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

Future directions

Add tools like:

Documentation

 
packages/compilation_installation/sconsx/sconsx.txt · Last modified: 2010/08/05 14:47 by admin   Back to top
INRIA   INRA     CIRAD     AGROPOLIS
INRIA GForge RSS feed Valid XHTML 1.0 Valid CSS Driven by DokuWiki