// $Id$ // // Copyright (C) 2007 // Fraunhofer Institute for Open Communication Systems (FOKUS) // Competence Center NETwork research (NET), St. Augustin, GERMANY // Stefan Bund // // This program is free software; you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation; either version 2 of the License, or // (at your option) any later version. // // This program is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with this program; if not, write to the // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. namespace senfscons { /** \mainpage The Senf Build Environment The Senf Build Environment is based on the SCons software construction tool. SCons is a python based replacement for \c make. SENFScons consists of several SCons builders as well as some global configuration and build utilities. SENFScons tightly integrates the Boost.Test unit testing framework. It also incorporates a very flexible infrastructure to build software documentation using Doxygen. This infrastructure uses quite a bit of pre- and postprocessing (which is integrated with the provided Doxygen builder) to fix some doxygen problems and generate a (IMHO) more readable layout. \autotoc \section senfutil_overview Building Projects using SENF When building projects using senf, SENFSCons has a very simple helper module \ref senfutil to make the building of libraries utilizing senf simpler: \code import sys sys.path.extend(('senf/senfscons','/usr/lib/senf/senfscons')) import os.path, glob, senfutil env = Environment() senfutil.SetupForSENF( env ) env.Append( LIBS = [ ], CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ], LINKFLAGS = [ ], CXXFLAGS_debug = [ ], LINKFLAGS_debug = [ ], LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ], CXXFLAGS_final = [ '-O3' ], LINKFLAGS_final = [ ], LOGLEVELS_final = [ ], SENF_BUILDOPTS = [ ], ) env.Default( env.Program( target = 'udpforward', source = glob.glob('*.cc') ) ) env.Clean(DEFAULT_TARGETS, [ 'udpforward.log', 'udpforward.pid' ]) \endcode This example builds a simple binary from a number of source files (all '.cc' files). It links against the SENF library and automatically sets all the correct compiler options using senfutil.SetupForSENF( env ). This script automatically uses a SENF installation either symlinked or imported into the current project in directory 'senf' or, if this directory does not exist, a globaly installed SENF. A locally installed SENF is automatically recompiled if needed. Parallel building is also supported. This script automatically supports the \c final and \c LOGLEVELS command line parameters. The LOGLEVELS parameter uses a much more readable syntax than SENF_LOG_CONF: 
    $ scons -j2 final=1 \
          LOGLEVELS='senf::log::Debug||IMPORTANT myapp::Transactions|mytrans::Area|VERBOSE'
\section senfscons_intro Introduction to the SENFSCons build system Here we give an overview on how SENF itself is built. The SENFSCons system aims to be quite flexible at separates SENF specific tasks from generic tasks to facilitate reuse. \subsection senfscons_layout The Project Layout The SENFSCons infrastructure will always use a consistent directory layout. The top-level directory will contain one subdirectory for every module. The main target will often be considered to be just another module using the facilities provided by library modules. The top-level project directory must contain the SENFSCons module in 'senfscons'. The top-level \c SConstruct file will set up the global project configuration (which libraries are used etc) and will then automatically load all module \c SConscript files. Documentation is generated per module. This simplifies reusing modules in other projects. The framework however semi-automatically creates the necessary cross-reference information to cross-link the different module documentations. The unit-tests as well are run on a per-module basis. \subsection senfscons_buildconf Standard Build Configuration When the \c SConsctruct and \c SConscript files are build using the default SENFSCons helpers, by default all libraries and binaries are built. Some additional targets are
scons all_tests
Build all unit tests
scons all_docs
Build documentation of all modules
scons all
Build all targets including binaries, libraries, documentation, tests and possible further targets
scons -u doc
Run from within a module directory will build the documentation of that module
scons -u test
Run from within a module directory will build and run the unit test of that module
To clean any of the targets use the SCons \c -c parameter. The build environment can be configured \e locally using \ref sconfig in the project root directory. \see \ref sconstruct \n \ref sconscript \n \ref sconfig \n \ref builder */ /** \page sconstruct The Top-Level 'SConstruct' File The top-level \c SConstruct file sets up the build, configures used libraries and parameters and invokes the module \c SConscript files. To simplify the configuration, the SENFScons python package is provided. This package has helper utilities to simplify standard tasks. In \c senfscons/SConstruct.template you may find an example SConstruct file. Copy this to the project root (under the name \c SConstruct) to start a new project. You can then modify and configure it to your wishes. The general structure of the \c SConstruct file is \li make the \c senfscons directory accessible \li tell the SENFScons infrastructure, which frameworks you intend to use and let SENFScons built a construction environment for you \li configure the construction environment \li load module sconscript file \li specify global build targets The first part, making the \c senfscons directory accessible will always stay the same. See the template file for how this is done. Simplifying the use of more complex frameworks is one of the most important things why SENFScons exists. If you only use very simple libraries, the configuration is quite simple. However for more complex frameworks the configuration can get quite complicated. This is simplified using the SENFScons framework statements. They all reside in the \c SENFSCons package and have a prefix of \c Use. See \ref use. After all frameworks are configured, you can use SEFNScons.MakeEnvironment() to create a correctly configured construction environment. To configure the construction environment you can set Variables in the construction environment. See the SCons manpage for a list of supported variables. Some additional variables are available with the new builders introduced with SENFSCons. Those are documented with the builder module documentation. Loading the module \c SConscript files will normally always be performed the same way using \c glob.glob() to automatically include any subdirectory module. You may then specify global build targets. You can use standard SCons targets or use all the target helpers provided with SENFSCons. Two standard helpers should always be included: SENFSCons.StandardTargets() and SENFSCons.GlobalTargets(). You can find more target helpers at \ref target The SConstruct file is an ordinary python file. It is loaded by SCons prior to building the software. Just remember, you can use all of python and all of SCons here. SENFScons just provides some additional helpers to make things simpler and more concise. \see \ref use \n \ref target */ /** \page sconscript The Module 'SConscript' Files Every module (that is subdirectory) is built by that modules \c SConscript file. In \c SConscript.template you can find a template of such a file. Every \c SConscript file starts by importing the construction environment. The \c SConscript file is an ordinary \c SConscript file as used by SCons. You may use any of the SCons facilities to define targets. However, you will mostly use the \ref target. Every \c SConscript file should call \c SENFSCons.StandardTargets() to initialize the standard targets of every module. \see \ref target */ /** \page sconfig The 'SConfig' File To configure the build environment to the local environment, a \c SConfig file may be created in the projects root directory. The supported parameters are
\c CXX
C++ compiler to use
\c EXTRA_DEFINES
preprocessor symbols to be defined locally
\c EXTRA_LIBS
additional libraries needed for a local build
Additionally, the \ref use define additional configuration variables which may be set here. */ } // Local Variables: // mode: c++ // fill-column: 100 // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" // mode: flyspell // mode: auto-fill // End: