To get started using this library, begin by checking out the code from the <a
href="http://developer.berlios.de/svn/?group_id=7489">BerliOS SVN repository</a>. You may find
- help on using the library at '\ref senf_usage'. If you are interested in SENF, feel free to subscribe
- to the <a href="http://developer.berlios.de/mail/?group_id=7489">SENF mailing lists</a>. If you
- want to contribute, read the docs and \e please adhere to the \ref senf_conventions.
+ help on using the library at '\ref senf_usage'. If you are interested in SENF, feel free to
+ subscribe to the <a href="http://developer.berlios.de/mail/?group_id=7489">SENF mailing
+ lists</a>. If you want to contribute, read the docs and \e please adhere to the \ref
+ senf_conventions.
\see \ref senf_usage\n
<a href="../../Examples/doc/html/index.html">Examples</a>
\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.
+ When building projects using %senf, SENFSCons has a very simple helper module
+ \ref senf_senfutil "senfutil.py" to make the building of libraries utilizing %senf simpler.
\see \ref senf_senfutil
*/
\autotoc
+ \c senfutil helps setting up projects which utilize SENF. It will configure all necessary
+ compiler and linker options and additionally sets up some useful defaults and utilities.
+
+ \c senfutil really serves three roles
+
+ \li detect SENF and configure the build accordingly
+ \li make some SCons extensions used within SENF available to other projects
+ \li set default compilation options in the same way, they are set when compiling SENF proper.
+
+ The last two points are of course optional.
+
+ \section senfutil_tutorial Tutorial
+
+ To utilize \c senfutil you need to do two things:
+ \li Update your \c SConstruct file
+ \li add a bootstrap \c senfutil.py to \c site_scons
+
+ Lets start with the \c SConstruct file
+ \code
+ import senfutil
+
+ env = Environment()
+ senfutil.SetupForSENF(env)
+ senfutil.DefaultOptions(env)
+
+ env.SetDefault(
+ PROJECTNAME = 'Example project',
+ PROJECTEMAIL = 'developer@domain.com',
+ DOCLINKS = [ ('Homepage', 'http://www.domain.com') ]
+ )
+
+ sources, tests = senfutil.Glob(env, exclude=['main.cc'])
+
+ objects = env.Object(sources)
+ example = env.Program('example', objects + ['main.cc'])
+ test = env.BoostUnitTest('test', objects + tests)
+
+ env.Default(example)
+
+ senfutil.Doxygen(env)
+
+ senfutil.CleanGlob('all', [ '*~', '#*#' ])
+ \endcode
+
+ This simple sample already enables a lot of functionality:
+ \li support for different \e SENF flavors (debug/normal/final)
+ \li support for different \e build flavors (debug/normal/final)
+ \li sensible default compile options for the different flavors
+ \li support for extended command-line variables
+ \li building documentation with an auto-generated Doxyfile
+ \li running unit-tests
+ \li cleaning backup and temporary files
+
+ Here a very quick rundown of the important scons commands:
+ \li Build default target:
+ <pre>
+ $ scons
+ </pre>
+ \li Build documentation and unit-tests:
+ <pre>
+ $ scons doc test
+ </pre>
+ \li clean up everything
+ <pre>
+ $ scons -c all
+ </pre>
+ \li Pass custom options on the command-line
+ <pre>
+ $ scons CXXFLAGS+=-Wextra
+ </pre>
+
+ Since \c senfutil.py is not on the standard \c python or \c SCons path, some extra steps are
+ needed to find it.
+ \li Either add the possible directories to <tt>sys.path</tt> before importing \c senfutil:
+ \code
+ import sys
+ sys.path.extend(('/usr/local/lib/senf/site_scons', '/usr/lib/senf/site_scons'))
+ import senfutil
+ \endcode
+ \li Alternatively, install the following utility script as <tt>site_scons/senfutil.py</tt> into
+ your project. This script will search for <tt>site_scons/senfutil.py</tt> in a list of
+ directories and then load the real \c senfutil.py on top of itself. The directories searched
+ include: the current directory and all parents, subdirectories named <tt>senf/</tt>,
+ <tt>Senf/</tt> or <tt>SENF/</tt> thereof, and <tt>/usr/local/lib/senf/</tt> and
+ <tt>/usr/lib/senf/</tt>
+ \include senfutil.py
+
+ \section senfutil_features
+
The \c senfutil utility for SCons helps setting up a project to compile against SENF:
\li \c senfutil adds all necessary libraries to link against
\li \c senfutil will set necessary compile options.
\li \c senfutil supports normal, debug and final project build options
+ \li \c senfutil adds support for Boost unit tests
+ \li \c senfutil implements a very simple to use enhanced doxygen build with SENF symbol
+ cross-reference
\li \c senfutil allows specifying variables on the scons command line
\li \c senfutil supports more readable compile-time SENF loglevel configuration
CXXFLAGS_final = [ '-O2' ],
CXXFLAGS_normal = [ '-O0', '-g' ],
CXXFLAGS_debug = [ '$CXXFLAGS_normal' ],
-
+
LINKFLAGS_normal = [ '-Wl,-S' ],
LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
- )
- env.Default(
- env.Program( target='udpforward', source=glob.glob('*.cc') )
+ PROJECTNAME = 'Example project',
+ PROJECTEMAIL = 'developer@domain.com',
+ DOCLINKS = [ ('Homepage', 'http://www.domain.com') ]
)
+
+ # Create a list of sources and tests. Sources are all *.cc files, test are *.test.cc
+ sources, tests = senfutil.Glob(env, exclude=['main.cc'] )
+
+ # Build objects from sources
+ objects = env.Object(sources)
+
+ # Build main binary
+ env.Default( env.Program( target='example', source=objects + ['main.cc'] ) )
+
+ # Build a boost unit-test from additional test sources
+ env.BoostUnitTest( 'test', source=objects + tests)
+
+ # Build a documentation, autogenerates a Doxyfile
+ senfutil.Doxygen(env)
\endcode
This example builds a simple binary from a number of source files (all '.cc' files). It links
select one of the build configurations 'debug', 'normal' or 'final'. The following variables are
supported each with separate values for all three configurations:
- \li \c CXXFLAGS
+ \li \c CXXFLAGS
\li \c CPPDEFINES
\li \c LINKFLAGS
\li \c LOGLEVELS
where \e optional_stream and \e optional_area are optional fully scoped C++ names (e.g. \c
senf::log::Debug) and \e level is the loglevel. There must be \e no whitespace in a single
specification, multiple specifications are either specified using an array or separated with
- whitespace.
+ whitespace.
\section senf_senfutil_default Default options
senfutil.SetupForSENF(env)
senfutil.DefaultOptions(env)
- env.Append( LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ] )
+ env.Append( LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
+ PROJECTNAME = 'Example project',
+ PROJECTEMAIL = 'developer@domain.com',
+ DOCLINKS = [ ('Homepage', 'http://www.domain.com') ] )
- env.Default(
- env.Program( target = 'udpforward', source = glob.glob('*.cc') )
- )
+ sources, tests = senfutil.Glob(env, exclude=['main.cc'] )
+
+ objects = env.Object(sources)
+ env.Default( env.Program( target='example', source=objects + ['main.cc'] ) )
+ env.BoostUnitTest( 'test', source=objects + tests)
+ senfutil.Doxygen(env)
+ \endcode
+
+ \section senf_senfutil_tests Building unit tests
+
+ Building unit tests mostly follows a standard pattern
+
+ \code
+ # Generate list of sources and tests (sources=*.cc, tests=*.test.cc)
+ extra_sources = ['main.cc']
+ sources, tests = senfutil.Glob(env, exclude=extra_sources)
+
+ # Build object files needed for both main target and unit tests
+ objects = env.Object(sources)
+
+ # Build main target, e.g. a Binary with additional sources which are not part of the unit test
+ env.Program('example', objects+extra_sources)
+
+ # Build unit tests including additional test sources
+ env.BoostUnitTest('test', objects+tests)
+ \endcode
+
+ It is important to exclude the \c main function from the unit-test build since the boost unit
+ test library provides it's own.
+
+ \section senf_senfutil_doxygen Building documentation
+
+ Documentation is built using the \c senfutil.Doxygen utility
+
+ \code
+ env.Append( PROJECTNAME = "Example project",
+ PROJECTEMAIL = "coder@example.com",
+ COPYRIGHT = "The Master Coders",
+ DOCLINKS = [ ('Homeage', 'http://www.example.com') ],
+ REVISION = 'r'+os.popen('svnversion').read().strip().lower() )
+
+ senfutil.Doxygen(env)
\endcode
+ The \c senfutil.Doxygen utility autogenerates a \c Doxyfile.
+
+ The utility will search for a SENF documentation in the \c senfdoc and \c %senf subdirectories
+ as well as via the senfutil module directory and some other standard locations. If SENF
+ documentation is found, the SENF tagfiles will automatically be added. Links will be resolved
+ to the documentation found.
+
+ \c senfutil.Doxygen takes some additional optional keyword arguments:
+ \li \c doxyheader: Path of an alternative HTML header
+ \li \c doxyfooter: Path of an alternative HTML footer
+ \li \c doxycss: Path on an alternative CSS file
+ \li \c mydoxyfile: If set to \c True, don't generate or clean the \c Doxyfile\
+ \li \c senfdoc_path: List of additional directories to search for SENF documentation
+
\section senf_senfutil_arguments 'scons' Command line arguments
\c senfutil automatically parses SCons command line arguments into the SCons build
\li The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html)
\li The \c graphviz library (http://www.graphviz.org)
-
The library is only tested with gcc-3.4 and 4.0 on Linux. On other POSIX platforms with a BSD
Socket API, the library should be usable, possibly with some tweaking (except for the Scheduler,
which relies on \c epoll)
$ scons all_tests
</pre>
- in the \c senf directory. This assumes, that you want to build the library with your default gcc
- and requires the boost libraries to be available in the system include paths. If this is not the
- case, you can take a look at <tt>SConfig.template</tt> file. Copy this file to <tt>SConfig</tt>
- and comment out all the variables you don't want to change (The \e values in the template file
- are just arbitrary examples).
+ in the \c %senf directory. This assumes, that you want to build the library with your default
+ gcc and requires the boost libraries to be available in the system include paths. If this is
+ not the case, you can take a look at <tt>SConfig.template</tt> file. Copy this file to
+ <tt>SConfig</tt> and comment out all the variables you don't want to change (The \e values in
+ the template file are just arbitrary examples).
*/
/** \page senf_setup Setting up a new project using SENF
\ref senf_setup
\section senf_conventions Coding Conventions
-
+
Here we have laid down the coding conventions used throughout the SENF framework. Please ad here
to these conventions when changing or adding code. If you use emacs, you can use the C++ IDE for
emacs from http://g0dil.de which greatly simplifies following these conventions.
\par Rationale:
This simplifies finding the implementation/header for a given class and also reduces the
size of each single file.
-
+
The implementation is divided into a number of different files:
<table class="glossary"> <tr><td>\c .h</td><td>C public header</td></tr>
<tr><td>\c .cci</td><td>C++ implementation of inline non-template functions and
members</td></tr>
-
+
<tr><td>\c .cti</td><td>C++ implementation of inline template functions and members</td></tr>
<tr><td>\c .mpp</td><td>Special include file used for external iteration by the
\li When defining simple exception classes, the 'what()' member may be defined inline if it
returns a string constant.
\li It may be OK to use inline implementations for one-line implementations in internal
- headers.
+ headers.
\li The Packet library allows inline implementations for the definition of parsers since doing
so outside the declaration just gets to verbose and parsers definitions are quite length but
very simple and straight forward.
projects / senf.git / blobdiff