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 layout The Project Layout
  38
  39     A Project using the SENFSCons infrastructure will always use a consistent directory layout. The
  40     top-level directory will contain one subdirectory for every module. The main target will often
  41     be considered to be just another module using the facilities provided by library modules.
  42
  43     The top-level project directory must contain the SENFSCons module in 'senfscons'.
  44
  45     The top-level \c SConstruct file will set up the global project configuration (which libraries
  46     are used etc) and will then automatically load all module \c SConscript files.
  47
  48     Documentation is generated per module. This simplifies reusing modules in other projects. The
  49     framework however semi-automatically creates the necessary cross-reference information to
  50     cross-link the different module documentations. The unit-tests as well are run on a per-module
  51     basis.
  52
  53     \section Standard Build Configuration
  54
  55     When the \c SConsctruct and \c SConscript files are build using the default SENFSCons helpers,
  56     by default all libraries and binaries are built. Some additional targets are
  57
  58     <dl><dt><tt>scons all_tests</tt></dt><dd>Build all unit tests</dd>
  59
  60     <dt><tt>scons all_docs</tt></dt><dd>Build documentation of all modules</dd>
  61
  62     <dt><tt>scons all</tt></dt><dd>Build all targets including binaries, libraries, documentation,
  63     tests and possible further targets </dd>
  64
  65     <dt><tt>scons -u doc</tt></dt><dd>Run from within a module directory will build the
  66     documentation of that module</dd>
  67
  68     <dt><tt>scons -u test</tt></dt><dd>Run from within a module directory will build and run the
  69     unit test of that module</dd></dl>
  70
  71     To clean any of the targets use the SCons \c -c parameter.
  72
  73     The build environment can be configured \e locally using \ref sconfig in the project root
  74     directory.
  75
  76     \see
  77         \ref sconstruct \n
  78         \ref sconscript \n
  79         \ref sconfig  \n
  80         \ref builder
  81  */
  82
  83 /** \page sconstruct The Top-Level 'SConstruct' File
  84
  85     The top-level \c SConstruct file sets up the build, configures used libraries and parameters and
  86     invokes the module \c SConscript files. To simplify the configuration, the SENFScons python
  87     package is provided. This package has helper utilities to simplify standard tasks.
  88
  89     In \c senfscons/SConstruct.template you may find an example SConstruct file. Copy this to the
  90     project root (under the name \c SConstruct) to start a new project. You can then modify and
  91     configure it to your wishes.
  92
  93     The general structure of the \c SConstruct file is
  94     \li make the \c senfscons directory accessible
  95     \li tell the SENFScons infrastructure, which frameworks you intend to use and let SENFScons
  96         built a construction environment for you
  97     \li configure the construction environment
  98     \li load module sconscript file
  99     \li specify global build targets
 100
 101     The first part, <i>making the \c senfscons directory accessible</i> will always stay the
 102     same. See the template file for how this is done.
 103
 104     <i>Simplifying the use of more complex frameworks</i> is one of the most important things why
 105     SENFScons exists. If you only use very simple libraries, the configuration is quite
 106     simple. However for more complex frameworks the configuration can get quite complicated. This is
 107     simplified using the SENFScons framework statements. They all reside in the \c SENFSCons package
 108     and have a prefix of \c Use. See \ref use.
 109
 110     After all frameworks are configured, you can use SEFNScons.MakeEnvironment() to create a
 111     correctly configured construction environment.
 112
 113     To <i>configure the construction environment</i> you can set Variables in the construction
 114     environment. See the SCons manpage for a list of supported variables. Some additional variables
 115     are available with the new builders introduced with SENFSCons. Those are documented with the
 116     builder module documentation.
 117
 118     <i>Loading the module \c SConscript files</i> will normally always be performed the same way
 119     using \c glob.glob() to automatically include any subdirectory module.
 120
 121     You may then <i>specify global build targets</i>. You can use standard SCons targets or use all
 122     the target helpers provided with SENFSCons. Two standard helpers should always be included:
 123     SENFSCons.StandardTargets() and SENFSCons.GlobalTargets(). You can find more target helpers at
 124     \ref target
 125
 126     The SConstruct file is an ordinary python file. It is loaded by SCons prior to building the
 127     software. Just remember, you can use all of python and all of SCons here. SENFScons just
 128     provides some additional helpers to make things simpler and more concise.
 129
 130     \see
 131         \ref use \n
 132         \ref target
 133  */
 134
 135 /** \page sconscript The Module 'SConscript' Files
 136
 137     Every module (that is subdirectory) is built by that modules \c SConscript file. In \c
 138     SConscript.template you can find a template of such a file.
 139
 140     Every \c SConscript file starts by importing the construction environment. The \c SConscript
 141     file is an ordinary \c SConscript file as used by SCons. You may use any of the SCons facilities
 142     to define targets. However, you will mostly use the \ref target.
 143
 144     Every \c SConscript file should call \c SENFSCons.StandardTargets() to initialize the standard
 145     targets of every module.
 146
 147     \see
 148         \ref target
 149  */
 150
 151 /** \page sconfig The 'SConfig' File
 152
 153     To configure the build environment to the local environment, a \c SConfig file may be created in
 154     the projects root directory. The supported parameters are
 155
 156     <dl>
 157         <dt>\c CXX</dt>
 158             <dd>C++ compiler to use</dd>
 159         <dt>\c EXTRA_DEFINES</dt>
 160             <dd>preprocessor symbols to be defined locally</dd>
 161         <dt>\c EXTRA_LIBS</dt>
 162             <dd>additional libraries needed for a local build</dd>
 163     </dl>
 164
 165     Additionally, the \ref use define additional configuration variables which may be set here.
 166  */
 167
 168 }
 169
 170 \f
 171 // Local Variables:
 172 // mode: c++
 173 // fill-column: 100
 174 // c-file-style: "senf"
 175 // indent-tabs-mode: nil
 176 // ispell-local-dictionary: "american"
 177 // mode: flyspell
 178 // mode: auto-fill
 179 // End: