4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
25 /** \mainpage The Senf Build Environment
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.
37 \section senfutil Building Projects using SENF
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:
43 sys.path.extend(('senf/senfscons','/usr/lib/senf/senfscons'))
44 import os.path, glob, senfutil
48 senfutil.SetupForSENF( env )
53 CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
57 LINKFLAGS_debug = [ ],
58 LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
60 CXXFLAGS_final = [ '-O3' ],
61 LINKFLAGS_final = [ ],
62 LOGLEVELS_final = [ ],
69 env.Program( target = 'udpforward',
70 source = glob.glob('*.cc') )
73 env.Clean(DEFAULT_TARGETS, [ 'udpforward.log', 'udpforward.pid' ])
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>.
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
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:
89 LOGLEVELS='senf::log::Debug||IMPORTANT myapp::Transactions|mytrans::Area|VERBOSE'
92 \section layout The Project Layout
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.
98 The top-level project directory must contain the SENFSCons module in 'senfscons'.
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.
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
108 \section Standard Build Configuration
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
113 <dl><dt><tt>scons all_tests</tt></dt><dd>Build all unit tests</dd>
115 <dt><tt>scons all_docs</tt></dt><dd>Build documentation of all modules</dd>
117 <dt><tt>scons all</tt></dt><dd>Build all targets including binaries, libraries, documentation,
118 tests and possible further targets </dd>
120 <dt><tt>scons -u doc</tt></dt><dd>Run from within a module directory will build the
121 documentation of that module</dd>
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>
126 To clean any of the targets use the SCons \c -c parameter.
128 The build environment can be configured \e locally using \ref sconfig in the project root
138 /** \page sconstruct The Top-Level 'SConstruct' File
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.
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.
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
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.
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.
165 After all frameworks are configured, you can use SEFNScons.MakeEnvironment() to create a
166 correctly configured construction environment.
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.
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.
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
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.
190 /** \page sconscript The Module 'SConscript' Files
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.
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.
199 Every \c SConscript file should call \c SENFSCons.StandardTargets() to initialize the standard
200 targets of every module.
206 /** \page sconfig The 'SConfig' File
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
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>
220 Additionally, the \ref use define additional configuration variables which may be set here.
229 // c-file-style: "senf"
230 // indent-tabs-mode: nil
231 // ispell-local-dictionary: "american"