senfscons/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 namespace senfscons {
  24
  25 /** \mainpage The Senf Build Environment
  26
  27     The Senf Build Environment is based on the <a href="http://www.scons.org">SCons</a> software
  28     construction tool. SCons is a <a href="http://www.python.org">python</a> based replacement for
  29     \c make. SENFScons consists of several SCons builders as well as some global configuration and
  30     build utilities. SENFScons tightly integrates the <a
  31     href="http://www.boost.org/libs/test/doc/index.html">Boost.Test</a> unit testing framework. It
  32     also incorporates a very flexible infrastructure to build software documentation using <a
  33     href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a>. This infrastructure uses quite a bit
  34     of pre- and postprocessing (which is integrated with the provided Doxygen builder) to fix some
  35     doxygen problems and generate a (IMHO) more readable layout.
  36
  37     \section senfutil Building Projects using SENF
  38
  39     When building projects using senf, SENFSCons has a very simple helper module \ref senfutil to
  40     make the building of libraries utilizing senf simpler:
  41     \code
  42     import sys
  43     sys.path.extend(('senf/senfscons','/usr/lib/senf/senfscons'))
  44     import os.path, glob, senfutil
  45
  46     env = Environment()
  47
  48     senfutil.SetupForSENF( env )
  49
  50     env.Append(
  51
  52         LIBS            = [ ],
  53         CXXFLAGS        = [ '-Wall', '-Woverloaded-virtual' ],
  54         LINKFLAGS       = [ ],
  55
  56         CXXFLAGS_debug  = [ ],
  57         LINKFLAGS_debug = [ ],
  58         LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
  59
  60         CXXFLAGS_final  = [ '-O3' ],
  61         LINKFLAGS_final = [ ],
  62         LOGLEVELS_final = [ ],
  63
  64         SENF_BUILDOPTS  = [ ],
  65
  66     )
  67
  68     env.Default(
  69         env.Program( target = 'udpforward',
  70                      source = glob.glob('*.cc') )
  71     )
  72
  73     env.Clean(DEFAULT_TARGETS, [ 'udpforward.log', 'udpforward.pid' ])
  74     \endcode
  75
  76     This example builds a simple binary from a number of source files (all '.cc' files). It links
  77     against the SENF library and automatically sets all the correct compiler options using
  78     <tt>senfutil.SetupForSENF( env )</tt>.
  79
  80     This script automatically uses a SENF installation either symlinked or imported into the current
  81     project in directory 'senf' or, if this directory does not exist, a globaly installed SENF. A
  82     locally installed SENF is automatically recompiled if needed. Parallel building is also
  83     supported.
  84
  85     This script automatically supports the \c final and \c LOGLEVELS command line parameters. The
  86     LOGLEVELS parameter uses a much more readable syntax than SENF_LOG_CONF:
  87     <pre>
  88     $ scons -j2 final=1 \
  89           LOGLEVELS='senf::log::Debug||IMPORTANT myapp::Transactions|mytrans::Area|VERBOSE'
  90     </pre>
  91
  92     \section layout The Project Layout
  93
  94     A Project using the SENFSCons infrastructure will always use a consistent directory layout. The
  95     top-level directory will contain one subdirectory for every module. The main target will often
  96     be considered to be just another module using the facilities provided by library modules.
  97
  98     The top-level project directory must contain the SENFSCons module in 'senfscons'.
  99
 100     The top-level \c SConstruct file will set up the global project configuration (which libraries
 101     are used etc) and will then automatically load all module \c SConscript files.
 102
 103     Documentation is generated per module. This simplifies reusing modules in other projects. The
 104     framework however semi-automatically creates the necessary cross-reference information to
 105     cross-link the different module documentations. The unit-tests as well are run on a per-module
 106     basis.
 107
 108     \section Standard Build Configuration
 109
 110     When the \c SConsctruct and \c SConscript files are build using the default SENFSCons helpers,
 111     by default all libraries and binaries are built. Some additional targets are
 112
 113     <dl><dt><tt>scons all_tests</tt></dt><dd>Build all unit tests</dd>
 114
 115     <dt><tt>scons all_docs</tt></dt><dd>Build documentation of all modules</dd>
 116
 117     <dt><tt>scons all</tt></dt><dd>Build all targets including binaries, libraries, documentation,
 118     tests and possible further targets </dd>
 119
 120     <dt><tt>scons -u doc</tt></dt><dd>Run from within a module directory will build the
 121     documentation of that module</dd>
 122
 123     <dt><tt>scons -u test</tt></dt><dd>Run from within a module directory will build and run the
 124     unit test of that module</dd></dl>
 125
 126     To clean any of the targets use the SCons \c -c parameter.
 127
 128     The build environment can be configured \e locally using \ref sconfig in the project root
 129     directory.
 130
 131     \see
 132         \ref sconstruct \n
 133         \ref sconscript \n
 134         \ref sconfig  \n
 135         \ref builder
 136  */
 137
 138 /** \page sconstruct The Top-Level 'SConstruct' File
 139
 140     The top-level \c SConstruct file sets up the build, configures used libraries and parameters and
 141     invokes the module \c SConscript files. To simplify the configuration, the SENFScons python
 142     package is provided. This package has helper utilities to simplify standard tasks.
 143
 144     In \c senfscons/SConstruct.template you may find an example SConstruct file. Copy this to the
 145     project root (under the name \c SConstruct) to start a new project. You can then modify and
 146     configure it to your wishes.
 147
 148     The general structure of the \c SConstruct file is
 149     \li make the \c senfscons directory accessible
 150     \li tell the SENFScons infrastructure, which frameworks you intend to use and let SENFScons
 151         built a construction environment for you
 152     \li configure the construction environment
 153     \li load module sconscript file
 154     \li specify global build targets
 155
 156     The first part, <i>making the \c senfscons directory accessible</i> will always stay the
 157     same. See the template file for how this is done.
 158
 159     <i>Simplifying the use of more complex frameworks</i> is one of the most important things why
 160     SENFScons exists. If you only use very simple libraries, the configuration is quite
 161     simple. However for more complex frameworks the configuration can get quite complicated. This is
 162     simplified using the SENFScons framework statements. They all reside in the \c SENFSCons package
 163     and have a prefix of \c Use. See \ref use.
 164
 165     After all frameworks are configured, you can use SEFNScons.MakeEnvironment() to create a
 166     correctly configured construction environment.
 167
 168     To <i>configure the construction environment</i> you can set Variables in the construction
 169     environment. See the SCons manpage for a list of supported variables. Some additional variables
 170     are available with the new builders introduced with SENFSCons. Those are documented with the
 171     builder module documentation.
 172
 173     <i>Loading the module \c SConscript files</i> will normally always be performed the same way
 174     using \c glob.glob() to automatically include any subdirectory module.
 175
 176     You may then <i>specify global build targets</i>. You can use standard SCons targets or use all
 177     the target helpers provided with SENFSCons. Two standard helpers should always be included:
 178     SENFSCons.StandardTargets() and SENFSCons.GlobalTargets(). You can find more target helpers at
 179     \ref target
 180
 181     The SConstruct file is an ordinary python file. It is loaded by SCons prior to building the
 182     software. Just remember, you can use all of python and all of SCons here. SENFScons just
 183     provides some additional helpers to make things simpler and more concise.
 184
 185     \see
 186         \ref use \n
 187         \ref target
 188  */
 189
 190 /** \page sconscript The Module 'SConscript' Files
 191
 192     Every module (that is subdirectory) is built by that modules \c SConscript file. In \c
 193     SConscript.template you can find a template of such a file.
 194
 195     Every \c SConscript file starts by importing the construction environment. The \c SConscript
 196     file is an ordinary \c SConscript file as used by SCons. You may use any of the SCons facilities
 197     to define targets. However, you will mostly use the \ref target.
 198
 199     Every \c SConscript file should call \c SENFSCons.StandardTargets() to initialize the standard
 200     targets of every module.
 201
 202     \see
 203         \ref target
 204  */
 205
 206 /** \page sconfig The 'SConfig' File
 207
 208     To configure the build environment to the local environment, a \c SConfig file may be created in
 209     the projects root directory. The supported parameters are
 210
 211     <dl>
 212         <dt>\c CXX</dt>
 213             <dd>C++ compiler to use</dd>
 214         <dt>\c EXTRA_DEFINES</dt>
 215             <dd>preprocessor symbols to be defined locally</dd>
 216         <dt>\c EXTRA_LIBS</dt>
 217             <dd>additional libraries needed for a local build</dd>
 218     </dl>
 219
 220     Additionally, the \ref use define additional configuration variables which may be set here.
 221  */
 222
 223 }
 224
 225 \f
 226 // Local Variables:
 227 // mode: c++
 228 // fill-column: 100
 229 // c-file-style: "senf"
 230 // indent-tabs-mode: nil
 231 // ispell-local-dictionary: "american"
 232 // mode: flyspell
 233 // mode: auto-fill
 234 // End: