\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.
+
+ \see \ref senf_senfutil
*/
+/** \page senf_senfutil SENF SCons build utility (senfutil.py)
+
+ \autotoc
+
+ 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 allows specifying variables on the scons command line
+ \li \c senfutil supports more readable compile-time SENF loglevel configuration
+
+ Using the utility is quite simple
+
+ \code
+ import sys
+ sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons'))
+ import glob, senfutil
+
+ env = Environment()
+ senfutil.SetupForSENF(env)
+ # senfutil.DefaultOptions(env)
+
+ # Set or change SCons environment variables with env.Append, env.Replace or env.SetDefault
+ env.Append(
+ CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
+ 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') )
+ )
+ \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 globally installed SENF.
+
+ \section senf_senfutil_options Build options
+
+ \c senfutil supports the <tt>debug=1</tt> or <tt>final=1</tt> build options. These parameters
+ 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 CPPDEFINES
+ \li \c LINKFLAGS
+ \li \c LOGLEVELS
+
+ \c senfutil will detect the type of SENF library used (final or not) and set the correct compile
+ options.
+
+ \section senf_senfutil_loglevels Specifying compile-time loglevels
+
+ To simplify specifying the compile-time loglevel configuration, the build variable \c LOGLEVELS
+ (and it's build configuration specific variants) may be set. This variable will be parsed and
+ converted into the correct \c SENF_LOG_CONF definition. The \c LOGLEVELS Syntax is
+
+ \par "" \e optional_stream \c | \e optional_area | \e level
+
+ 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.
+
+ \section senf_senfutil_default Default options
+
+ In the example above, all compile options are set manually. To specify the default customary
+ compile options for SENF programs, \c senfutil.DefaultOptions(env) is provided. This function is
+ identical to:
+
+ \code
+ senfutil.DefaultOptions(env) =>
+ env.Append(
+ CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
+ CXXFLAGS_final = [ '-O2' ],
+ CXXFLAGS_normal = [ '-O0', '-g' ],
+ CXXFLAGS_debug = [ '$CXXFLAGS_normal' ],
+
+ LINKFLAGS_normal = [ '-Wl,-S' ],
+ )
+ \endcode
+
+ Thus above example can be simplified to
+ \code
+ import sys
+ sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons'))
+ import glob, senfutil
+
+ env = Environment()
+ senfutil.SetupForSENF(env)
+ senfutil.DefaultOptions(env)
+
+ env.Append( LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ] )
+
+ env.Default(
+ env.Program( target = 'udpforward', source = glob.glob('*.cc') )
+ )
+ \endcode
+
+ \section senf_senfutil_arguments 'scons' Command line arguments
+
+ \c senfutil automatically parses SCons command line arguments into the SCons build
+ environment. This allows specifying any parameter on the command line:
+ <pre>
+ $ scons CXX=myg++ CXXFLAGS+=-mtune=geode
+ </pre>
+ You may either set variables unconditionally using '=' or append values to the end of a list
+ using '+='.
+ */
+
/** \page senf_usage Using the SENF framework
The SENF Framework is a collection of loosely coupled modules. The libraries are heavily object
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)
+
+ \section senf_compiler_options Compiler and Linker Options
+
+ If SENF is compiled in debug mode (SENF_DEBUG is defined), exception messages will automatically
+ include a stack backtrace. For this to work, you need to add the -rdynamic option to all link
+ commands. This feature depends on gcc and the GNU-libc.
+
+ It is <B>very important</B> that both the SENF library and the application using it are compiled
+ \e both either with or without this compiler switch (-DSENF_DEBUG). Otherwise, the compiler will
+ emit error messages which might be hard to debug.
*/
/** \page senf_build Building the SENF framework
<tt>svn:externals</tt> for this) or a symbolic link to your SENF checkout.
\code
- import os.path, glob
+ import glob
env = Environment(
- LIBS = [ 'senf', 'iberty', 'boost_regex', 'boost_iostreams' ],
+ LIBS = [ 'senf', 'boost_regex', 'boost_iostreams' ],
CXXFLAGS = [ '-Wall', '-Woverloaded-virtual', '-Wno-long-long' ],
)
- # If we have a symbolic link 'senf' pointing to our own senf build, use it (and assume
- # it's in debug mode)
- if os.path.exists('senf'):
- print "\nUsing SENF in 'senf'\n"
- env.Append(
-
- CPPDEFINES = [ 'SENF_DEBUG' ],
- LIBPATH = [ 'senf' ],
- CPPPATH = [ 'senf/include' ],
- CXXFLAGS = [ '-O0', '-g', '-fno-inline' ],
- LINKFLAGS = [ '-g', '-rdynamic' ],
-
- )
- env.Execute([ 'scons -C senf libsenf.a' ])
- else:
- print "\nUsing system installed SENF\n"
-
- # replace 'mytarget' with the name of your target executable
env.Program(
target = 'mytarget',
source = glob.glob('*.cc'),
);
\endcode
- This script automatically set's up the build correctly when using a self-compiled SENF in debug
- mode (which is the default mode):
- \li It links in all the required libraries in the correct order: First \c libsenf, then the
- other needed libraries \c liberty, \c libboost_regex and \c libboost_iostreams.
- \li It defines the <tt>SENF_DEBUG</tt> preprocessor symbol correctly
- \li It correctly sets the include and library path
- \li It adds sensible debug flags
- \li It adds <tt>-rdynamic</tt> to the link command. This is needed to get a nice backtrace from
- exceptions.
- \li It automatically rebuilds SENF if needed
+ When building against a self-built SENF which will probably be in debug mode, the '-DSENF_DEBUG'
+ option must be added to the compile command.
+
+ The most simple way to build using SENF is to use a very simple SCons helper which automatically
+ supports debug and final builds, uses SENF either centrally installed or locally built and has
+ some other nice features. See <a
+ href="../../senfscons/doc/html/index.html#senfutil_overview">Building Projects using SENF</a>
+ for more info and an example for this utility.
\see \ref senf_components \n
\ref senf_overview
\section libPPI libPPI: Packet Processing Infrastructure
The Packet Processing Infrastructure implements a modular framework for implementing packet
- oriented network applications. The library provides a larget set of pre-defined modules as well
+ oriented network applications. The library provides a large set of pre-defined modules as well
as the necessary helpers to implement application specific processing modules.
\see <a href="../../PPI/doc/html/index.html">libPPI API reference</a>
\li senf::intrusive_refcount to simplify the implementation of classes usable with
boost::intrusive_ptr
\li boost::bind extensions
- \li An interface to the \c g++ demangler integrated with type_info
+ \li An interface to the \c g++ de-mangler integrated with type_info
\li Typedefs and rudimentary methods to simplify handling high-resolution time values
\see <a href="../../Utils/doc/html/index.html">libUtils API reference</a>
\li To interpret low level network packets, use the <a
href="../../Packets/doc/html/index.html">Packets library</a>. This library will provide
efficient and convenient access to all protocol fields. It supports parsing as well as
- modifying and creating packets. It has default support for the most important internet
+ modifying and creating packets. It has default support for the most important Internet
protocols and is highly extensible with new protocols.
\li Go over the <a href="../../Utils/doc/html/index.html">Utils library</a>. It contains small
helpers to simplify tasks like daemonization, exception handling, debugging and so on.
*/
\f
+// :vim:textwidth=100
// Local Variables:
// mode: c++
// fill-column: 100