+++ /dev/null
-// $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:
projects / senf.git / blobdiff