-// Copyright (C) 2007
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// $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
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 usage'. If you are interested in SENF, feel free to subscribe
+ 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 conventions.
+ 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:
+ \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' ] )
- \see \ref usage\n
- \ref example
+ 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.
+
+ \see \ref senf_senfutil
*/
-/** \page usage Using the SENF framework
+/** \page senf_senfutil SENF SCons build utility
+
+ 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
+
+ \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
+ */
+
+/** \page senf_usage Using the SENF framework
The SENF Framework is a collection of loosely coupled modules. The libraries are heavily object
oriented and template based. For compatibility reasons, the libraries are therefore built
together with every project making use of the framework.
- When starting a new Projekt based on the SENF framework, it is advisable, to make use of the
+ When starting a new project based on the SENF framework, it is advisable, to make use of the
SENFSCons build environment and use SVN to manage the code repository. This is the
configuration, described in this documentation.
- \see \ref build \n
- \ref components \n
- \ref svnsetup \n
- \ref overview
+ \see \ref senf_build \n
+ \ref senf_setup \n
+ \ref senf_components \n
+ \ref senf_overview
- \section Preliminaries
+ \section senf_preliminaries Preliminaries
- Before starting the devlopment, make sure to fulfill the following requirements:
+ Before starting the development, make sure to fulfill the following requirements:
\li GNU g++, version at least 3.4
\li The Boost libraries (http://www.boost.org)
\li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
\li HTML \c tidy (http://tidy.sourceforge.net/)
\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)
+
+ \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 build Building the framework
+/** \page senf_build Building the SENF framework
This procedure will test building the complete framework including the unit tests and the
Sniffer test application. This build is \e not needed to use the framework since every project
After you have successfully built the library tests, you can continue to setup your own project
using SENF.
- \see \ref components \n
- \ref svnsetup
+ \see \ref senf_setup \n
+ \ref senf_components \n
+ \ref senf_overview
- \section checkout Getting the code
+ \section senf_checkout Getting the code
To access the code, check out the code from the BerliOS repository. Change to your development
directory and use the following subversion command
</pre>
This will create a new directory \c senf within the current directory. For further documentation
- on the use of Subversion, see the \c svn manpage or the subversion homepage at
+ on the use of Subversion, see the \c svn man-page or the subversion homepage at
http://subversion.tigris.org. A very good introduction and reference to subversion is available
at http://svnbook.red-bean.com.
- \section compile Building
+ \section senf_compile Building
To build the library, execute all unit tests and build the Sniffer test application, use
are just arbitrary examples).
*/
-/** \page components The SENF modules
+/** \page senf_setup Setting up a new project using SENF
+
+ The most simple way to use SENF for now is to checkout the svn repository and build SENF
+ yourselves. After you have built SENF, reference your SENF build directory from your build
+ environment. The most flexible way to do this, is to use a symbolic link to your SENF build.
+
+ Here an example \c SConstruct file for a project using SENF. This script expects SENF to be
+ found in the <tt>%senf</tt> sub-directory of the directory, where the \c SConstruct file is
+ found. This may either be a SENF checkout (if managing your project via subversion, you can use
+ <tt>svn:externals</tt> for this) or a symbolic link to your SENF checkout.
+
+ \code
+ import glob
+
+ env = Environment(
+
+ LIBS = [ 'senf', 'boost_regex', 'boost_iostreams' ],
+ CXXFLAGS = [ '-Wall', '-Woverloaded-virtual', '-Wno-long-long' ],
+
+ )
+
+ env.Program(
+ target = 'mytarget',
+ source = glob.glob('*.cc'),
+ );
+ \endcode
+
+ 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
+ */
+
+/** \page senf_components The SENF modules
The framework is made up of several modular components. When using the library, it is possible
to selectively choose to use only a subset of the implemented modules.
- \see \ref build \n
- \ref svnsetup
+ \see \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 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>
\section libSocket libSocket: C++ abstraction of the BSD socket API
This library provides a high performance and object oriented abstraction of the standard socket
API. It utilizes a flexible and extensible policy based design. The library provides predefined
- types for the important socket types (UDP and TCP sockets etc) including raw and packet
- sockets. \n
+ types for the important socket types (UDP and TCP sockets etc) including raw and packet sockets.
- \see <a href="../../Socket/doc/html/index.html">libSocket API
- reference</a>
+ \see <a href="../../Socket/doc/html/index.html">libSocket API reference</a>
\section libPackets libPackets: Network packet manipulation
- This libarary provides a very flexible infrastructure to parse, create and otherwise manipulate
+ This library provides a very flexible infrastructure to parse, create and otherwise manipulate
packetized network data. Included is a library of several protocol parsers covering the basic
IPv4 and IPv6 network protocols down to the Ethernet layer.
- \see <a href="../../Packets/doc/html/index.html">libPackets API
- reference</a>
+ \see <a href="../../Packets/doc/html/index.html">libPackets API reference</a>
\section libScheduler libScheduler: Asynchronous event handling
\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>
\see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a>
*/
-/** \page svnsetup Setting up a new project using SENF
-
- The preferred way to use SENF in a new project is to rely on Subversion and make use of the
- SENFSCons build environment. The following sections will describe, how this setup works.
-
- \see \ref build \n
- \ref components \n
- \ref overview
-
- \section svnext Setting up the project repository
-
- The most seamless integration is possible if you rely on Subversion to manage the new
- project. Subversion does support 'external repositories'. This allows to import code from a
- foreign repository into the checkout without importing it into your repository. The code will
- always stay at the remote repository, updates are automatically available.
-
- First setup a new empty repository as described for example in the Subversion book at
- http://svnbook.red-bean.com or as mandated by your site policy. We will call the project 'Foo'
- and assume, that the project has been checked out into the 'Foo' directory.
-
- You now have to decide, which modules you want to use. Every module resides in it's own
- subdirectory in the SENF repository. Instead of directly checking out the code, we will use \c
- svn:externals. This will instruct \c svn to auutomatically check out the needed directories from
- the BerliOS SENF repository. Change to the 'Foo' directory and type
-
- <pre>
- $ svn propedit svn:externals .
- </pre>
-
- The default editor (probably VI) will be started with the current value of the svn:externals
- property (which will probably be empty). Now add all the modules you want plus \c senfscons and
- possibly \c doclib (if you want to build the documentation). You will almost certainly neeed the
- \c Utils module, since all other modules depend on it.
-
- For example, if you want to use the \c Scheduler and \c Socket module, the file will look like
-
- <pre>
- senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
- Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
- Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
- Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket
- </pre>
-
- exit the editor and the property will be set. Now run
-
- <pre>
- $ svn update
- </pre>
-
- and the code will be checked out into the corresponding directories.
-
- \section new_conf Configuring SENFSCons
-
- To set up the build environment, copy the <tt>senfscons/SConstruct.template</tt> to
- <tt>SConstruct</tt> in the project root. The default setup of this file is to build all
- subdirectories (using the \c SConscript files of the subdirectories). You can add additonal
- global targets and configuration parameters here.
-
- If you want to use a non-default compiler or the boost library is not installed in the system
- directories, you will have to copy <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in
- the project root and edit it there. You should \e never add \c SConfig to the repository since
- it should only contain local settings necessary for building on your local system. You should
- therefore add \c SConfig to the list of files ignored by Subversion in the project root. In the
- project root execute
-
- <pre>
- $ svn propedit svn:ignore .
- </pre>
-
- and add \c SConfig as a new line to the property.
-
- \section new_build Building the project
-
- You should now be able to build your project using
-
- <pre>
- $ scons
- </pre>
-
- If you have not changed the \c SConstruct file, this will build all modules you have importet
- into your project. To build and execute the unit tests, use
-
- <pre>
- $ scons all_tests
- </pre>
-
- you can also build only a subdirectory by changing to it and running
-
- <pre>
- $ scons -u [target]
- </pre>
-
- \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
- <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
- <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
- <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
- */
-
-/** \page overview Introduction to the framework
+/** \page senf_overview Introduction to the framework
The SENF framework is relatively complex and makes use of advanced features of the C++
language. To make the most efficient use of the framework, you should have at least a basic
standard library. It is designed, to integrate well into both libraries and to use the same
concepts and ideas.
- \section startup Getting starting developing with SENF
+ \section senf_startup Getting starting developing with SENF
To introduce the framework and it's general structure, a simple example application is provided
in the SENF repository in the \c Sniffer module. Peruse this example to get a first look at how
\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.
The simplest way to get started is: copy the Sniffer application and start to modify it.
- \see \ref example \n
- \ref components \n
- \ref svnsetup \n
- \ref build
+ \see <a href="../../Examples/doc/html/index.html">Examples</a> \n
+ \ref senf_components \n
+ \ref senf_setup
- \section conventions Coding Conventions
+ \section senf_conventions Coding Conventions
- Here we have laid down the coding conventions used throughout the SENF framework. Please adhere
+ 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.
- \subsection conventions_file_naming File Naming
+ \subsection senf_conventions_file_naming File Naming
Files should be named according to the main class they define. A single header file should
define only one main class. Exceptions to this rule are OK.
<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 fuanctions 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
Boost.Preprocessor library</td></tr> </table>
\par Rationale:
- There are two part's to this: First, separating the implementation of inlines and tempaltes
+ There are two part's to this: First, separating the implementation of inlines and templates
out of the header file makes the header file much easier to read. This is important, since
the header file will be used as a reference by the developers.
\par
an implementation from one of the inline files into one of the non-inline files will change
the type of implementation accordingly.
- \subsection conventions_type_naming Type Naming
+ \subsection senf_conventions_type_naming Type Naming
SENF prefers the use of the CapitalziedLettersToSeparateWords convention for class names. In
this case, class names must start with a capital letter. There are some exceptions to this rule:
name. This can also be used by the editor to highlight type names correctly. Additionally,
this convention is compact and does not add additional or repeated overhead.
- \subsection conventions_impl Implementation
+ \subsection senf_conventions_impl Implementation
Only in very few places, SENF allows the use of inline implementations (not to be confused with
inline functions). An \e implementation is inline, if it is written directly into the class
Together with splitting inlines and non-inlines into separate files, this allows to
automatically include the inline definitions at the right places. See above.
+ Private data members are named with a trailing underscore character.
+
+ \par Rationale:
+ This helps distinguishing local variables from parameter names. The trailing underscore
+ does not interfere with other naming conventions and is allowed by the standard (underscore
+ at the beginning of the name are problematic since some classes of names beginning with an
+ underscore are reserved for the standard library implementation)
*/
\f
+// :vim:textwidth=100
// Local Variables:
// mode: c++
// fill-column: 100
// c-file-style: "senf"
// indent-tabs-mode: nil
// ispell-local-dictionary: "american"
+// compile-command: "scons doc"
// mode: flyspell
// mode: auto-fill
// End:
projects / senf.git / blobdiff