//
// 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.
+// The contents of this file are subject to the Fraunhofer FOKUS Public License
+// Version 1.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// http://senf.berlios.de/license.html
//
-// 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.
+// The Fraunhofer FOKUS Public License Version 1.0 is based on,
+// but modifies the Mozilla Public License Version 1.1.
+// See the full license text for the amendments.
//
-// 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.
+// Software distributed under the License is distributed on an "AS IS" basis,
+// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+// for the specific language governing rights and limitations under the License.
+//
+// The Original Code is Fraunhofer FOKUS code.
+//
+// The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
+// (registered association), Hansastraße 27 c, 80686 Munich, Germany.
+//
+// Contributor(s):
+// Stefan Bund <g0dil@berlios.de>
+
/** \mainpage SENF: The Simple and Extensible Network Framework
\section start Getting started
- 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.
+ You may check the Downloads section for binary library releases. However, in all probability you
+ will have to compile SENF for yourself.
- \see \ref senf_usage\n
- <a href="../../Examples/doc/html/index.html">Examples</a>
+ 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.
- \section senfutil_overview Building Projects using SENF
-
- When building projects using %senf, SENFSCons has a very simple helper module
- \ref senf_senfutil to make the building of libraries utilizing %senf simpler.
-
- \see \ref senf_senfutil
+ \see
+ \ref senf_introduction \n
+ \ref senf_build \n
+ \ref senf_senfutil for linking against the SENF library\n
+ <a href="../../Examples/doc/html/index.html">Examples</a>
*/
/** \page senf_senfutil SENF SCons build utility (senfutil.py)
\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 the SENF library 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
CXXFLAGS_final = [ '-O2' ],
CXXFLAGS_normal = [ '-O0', '-g' ],
CXXFLAGS_debug = [ '$CXXFLAGS_normal' ],
-
+
LINKFLAGS_normal = [ '-Wl,-S' ],
LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
# Build objects from sources
objects = env.Object(sources)
-
+
# Build main binary
env.Default( env.Program( target='example', source=objects + ['main.cc'] ) )
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
# 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.
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.
+ 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
using '+='.
*/
-/** \page senf_usage Using the SENF framework
+/** \page senf_introduction 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
+ understanding of C++ templates and the standard library concepts.
+
+ The library implementation at places makes heavy use of advanced template techniques and relies
+ on some very advanced template libraries from Boost. The aim was however for the \e external
+ interface of the library to be as simple as possible without sacrificing important functionality
+ or adversely impacting the runtime performance.
+
+ As already mentioned several times, the library relies on Boost (http://www.boost.org) as a
+ generic library of high quality reusable C++ components. It also makes frequent use of the
+ standard library. It is designed, to integrate well into both libraries and to use the same
+ concepts and ideas.
- 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.
+ \section senf_startup Getting starting developing with SENF
+
+ To introduce the framework and it's general structure, some simple example applications are
+ provided in the SENF repository. Peruse those examples to get a first look at how to make use of
+ SENF.
+
+ When building a network Application with SENF, you will use several modules:
+
+ \li One of the central SENF libraries is the <a
+ href="../../senf/PPI/doc/html/index.html">Packet Processing Infrastructure (PPI)</a>. Using
+ this library, it is very simple to develop flexible packet networks of interconnected
+ modules.
+ \li Use the <a href="../../senf/Socket/doc/html/index.html">Socket library</a> for network
+ communication needs. This library includes support for raw and packet sockets to allow low
+ level network access.
+ \li Use the <a href="../../senf/Scheduler/doc/html/index.html">Scheduler library</a> to
+ coordinate the asynchronous event processing. This drastically reduces the number of threads
+ needed in your application and will greatly enhance the overall responsiveness.
+ \li To interpret low level network packets, use the <a
+ href="../../senf/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
+ protocols and is highly extensible with new protocols.
+ \li Go over the <a href="../../senf/Utils/doc/html/index.html">Utils library</a>. It contains
+ small helpers to simplify tasks like daemonization, exception handling, debugging and so
+ on. Additionally, %Utils contains several larger supplementary modules for <a
+ href="../../senf/Utils/Logger/doc/html/index.html">Logging</a>, <a
+ href="../../senf/Utils/Console/doc/html/index.html">Configuration</a> (including interactive
+ configuration via a network terminal) and <a
+ href="../../senf/Utils/Daemon/doc/html/index.html">Daemon management</a>.
- 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.
+ The simplest way to get started is: copy the Sniffer application and start to modify it.
- \see \ref senf_build \n
- \ref senf_setup \n
- \ref senf_components \n
- \ref senf_overview
+ \see <a href="../../Examples/doc/html/index.html">Examples</a> \n
+ \ref senf_components \n
+ \ref senf_senfutil \n
+ \ref senf_build
- \section senf_preliminaries Preliminaries
+ \section senf_dependencies Dependencies
Before starting the development, make sure to fulfill the following requirements:
\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.
+ The library is tested and developed on Linux. It should be relatively simple to port SENF to
+ other POSIX platforms.
*/
/** \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
- will include the full SENF source code itself (via Subversion).
-
- After you have successfully built the library tests, you can continue to setup your own project
- using SENF.
-
- \see \ref senf_setup \n
- \ref senf_components \n
- \ref senf_overview
+ This procedure will build the complete framework including the unit tests and the example
+ applications. After you have successfully built the library tests, you can continue to setup
+ your own project linking against SENF.
\section senf_checkout Getting the code
http://subversion.tigris.org. A very good introduction and reference to subversion is available
at http://svnbook.red-bean.com.
- \section senf_compile Building
+ Additionally ensure, you have installed all necessary \ref senf_dependencies.
- To build the library, execute all unit tests and build the Sniffer test application, use
+ \section senf_compile Building
+ To build the library, execute all unit tests and build all examples applications, use
<pre>
- $ scons
- $ scons all_tests
+ $ scons default examples 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).
- */
-
-/** \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
+ 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 take a look a the
+ \c SConstruct file for configuration variables. You may either specify the variables on the
+ command line or place them into a \c SConscript.local file.
*/
/** \page senf_components The SENF modules
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>
+ \see <a href="../../senf/PPI/doc/html/index.html">libPPI API reference</a>
\section libSocket libSocket: C++ abstraction of the BSD socket API
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.
- \see <a href="../../Socket/doc/html/index.html">libSocket API reference</a>
+ \see <a href="../../senf/Socket/doc/html/index.html">libSocket API reference</a>
\section libPackets libPackets: Network packet manipulation
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="../../senf/Packets/doc/html/index.html">libPackets API reference</a>
\section libScheduler libScheduler: Asynchronous event handling
event dispatcher. It is based on the high performance \c epoll system call. It provides support
for read/write events as well as simple timer based events.
- \see <a href="../../Scheduler/doc/html/index.html">libScheduler API reference</a>
+ \see <a href="../../senf/Scheduler/doc/html/index.html">libScheduler API reference</a>
\section libUtils libUtils: Collection of arbitrary utilities
\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>
-
- \section senfscons SENFSCons, the SENF build environment
-
- SENF relies on SCons (http://www.scons.org) to build. To further simplify the common tasks, SENF
- includes a library of custom routines and builders comprising a very concise build
- environment. Included are a number of templates to help bootstrapping a new project or
- component.
-
- \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a>
+ \see <a href="../../senf/Utils/doc/html/index.html">libUtils API reference</a>
*/
-/** \page senf_overview Introduction to the framework
+/** \page senf_conventions Coding Conventions
- 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
- understanding of C++ templates and the standard library concepts.
-
- The library implementation at places makes heavy use of advanced template techniques and relies
- on some very advanced template libraries from Boost. The aim was however for the \e external
- interface of the library to be as simple as possible without sacrificing important functionality
- or adversely impacting the runtime performance.
-
- As already mentioned several times, the library relies on Boost (http://www.boost.org) as a
- generic library of high quality reusable C++ components. It also makes frequent use of the
- standard library. It is designed, to integrate well into both libraries and to use the same
- concepts and ideas.
-
- \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
- to make use of SENF.
-
- When building a network Application with SENF, you will use several modules:
-
- \li Use the <a href="../../Socket/doc/html/index.html">Socket library</a> for network
- communication needs. This library includes support for raw and packet sockets to allow low
- level network access.
- \li Use the <a href="../../Scheduler/doc/html/index.html">Scheduler library</a> to coordinate
- the asynchronous event processing. This drastically reduces the number of threads needed in
- your application and will greatly enhance the overall responsiveness.
- \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
- 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 <a href="../../Examples/doc/html/index.html">Examples</a> \n
- \ref senf_components \n
- \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