[senf.git] / senfscons / Mainpage.dox

// $Id$
//
// Copyright (C) 2007
// Fraunhofer Institute for Open Communication Systems (FOKUS)
// Competence Center NETwork research (NET), St. Augustin, GERMANY
//     Stefan Bund <g0dil@berlios.de>
//
// 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 <a href="http://www.scons.org">SCons</a> software
    construction tool. SCons is a <a href="http://www.python.org">python</a> based replacement for
    \c make. SENFScons consists of several SCons builders as well as some global configuration and
    build utilities. SENFScons tightly integrates the <a
    href="http://www.boost.org/libs/test/doc/index.html">Boost.Test</a> unit testing framework. It
    also incorporates a very flexible infrastructure to build software documentation using <a
    href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a>. 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
    <tt>senfutil.SetupForSENF( env )</tt>.

    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:
    <pre>
    $ scons -j2 final=1 \
          LOGLEVELS='senf::log::Debug||IMPORTANT myapp::Transactions|mytrans::Area|VERBOSE'
    </pre>

    \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

    <dl><dt><tt>scons all_tests</tt></dt><dd>Build all unit tests</dd>

    <dt><tt>scons all_docs</tt></dt><dd>Build documentation of all modules</dd>

    <dt><tt>scons all</tt></dt><dd>Build all targets including binaries, libraries, documentation,
    tests and possible further targets </dd>

    <dt><tt>scons -u doc</tt></dt><dd>Run from within a module directory will build the
    documentation of that module</dd>

    <dt><tt>scons -u test</tt></dt><dd>Run from within a module directory will build and run the
    unit test of that module</dd></dl>

    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, <i>making the \c senfscons directory accessible</i> will always stay the
    same. See the template file for how this is done.

    <i>Simplifying the use of more complex frameworks</i> 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 <i>configure the construction environment</i> 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.

    <i>Loading the module \c SConscript files</i> will normally always be performed the same way
    using \c glob.glob() to automatically include any subdirectory module.

    You may then <i>specify global build targets</i>. 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

    <dl>
        <dt>\c CXX</dt>
            <dd>C++ compiler to use</dd>
        <dt>\c EXTRA_DEFINES</dt>
            <dd>preprocessor symbols to be defined locally</dd>
        <dt>\c EXTRA_LIBS</dt>
            <dd>additional libraries needed for a local build</dd>
    </dl>

    Additionally, the \ref use define additional configuration variables which may be set here.
 */

}

\f
// 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: