--- /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.
+
+/** \mainpage SENF: The Simple and Extensible Network Framework
+
+ The SENF Simple and Extensible Network Framework aims to be a complete set of libraries to
+ facilitate the development of network applications focusing on network protocols on the layers
+ below the application layer. However, the framework includes many general purpose utilities and
+ will be expedient to use well beyond its primary objective.
+
+ \section Goals
+
+ The main goals of this library are (in no particular order):
+
+ \li modular framework design
+ \li utilizing the power of modern C++
+ \li very low overhead for frequently called members
+ \li extensible design
+ \li concise interface
+
+ \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.
+
+ \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
+ 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 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 senf_build \n
+ \ref senf_setup \n
+ \ref senf_components \n
+ \ref senf_overview
+
+ \section senf_preliminaries Preliminaries
+
+ 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 SCons build tool (http://www.scons.org)
+
+ If you want to build the documentation, you additionally need
+
+ \li Doxygen (http://www.doxygen.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 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
+
+ \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>
+ $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
+ </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 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 senf_compile Building
+
+ To build the library, execute all unit tests and build the Sniffer test application, use
+
+ <pre>
+ $ scons
+ $ 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).
+ */
+
+/** \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 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.
+
+ \see <a href="../../Socket/doc/html/index.html">libSocket API reference</a>
+
+ \section libPackets libPackets: Network packet manipulation
+
+ 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>
+
+ \section libScheduler libScheduler: Asynchronous event handling
+
+ The scheduler library provides an object oriented interface to the standard UNIX \c select type
+ 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>
+
+ \section libUtils libUtils: Collection of arbitrary utilities
+
+ This library is used be most all of the other modules for miscellaneous tools and utilities. We
+ have
+
+ \li Simple functions to manage daemon processes
+ \li Standard exception classes
+ \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++ 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>
+ */
+
+/** \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
+ 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.
+
+ \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.
+
+ \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 .hh</td><td>C++ public header</td></tr>
+
+ <tr><td>\c .ih</td><td>C++ internal header used only by the implementation. This header will
+ probably be included indirectly by the public header but is not meant to be perused by the
+ library user</td></tr>
+
+ <tr><td>\c .c</td><td>C implementation</td></tr>
+
+ <tr><td>\c .cc</td><td>C++ implementation of non-inline non-template functions and
+ members</td></tr>
+
+ <tr><td>\c .ct</td><td>C++ implementation of non-inline template functions and members</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
+ Boost.Preprocessor library</td></tr> </table>
+
+ \par Rationale:
+ 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
+ Separating inline from non-inline members is used together with the \c prefix_ convention
+ below to ensure the correct placement of inline vs non-inline members in the source
+ code. The C++ language requires, that inline members must be included into \e every
+ compilation unit, non-inline members however must be included \e only in one compilation
+ unit. Placing the inline members into a separate file allows to automate this: Simply moving
+ an implementation from one of the inline files into one of the non-inline files will change
+ the type of implementation accordingly.
+
+ \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:
+ Types which define new basic data types to be used like other built-in types may be named using
+ lowercase letters plus underscores. Also, if a type or class is directly related to some other
+ library (STL or Boost) which uses the underscore convention, it might be more sensible to follow
+ this convention. This is open to debate.
+
+ \par Rationale:
+ Naming types with capital letters nicely gives a visual clue, that a symbol is a type
+ 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 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
+ definition in the header file. Again there are exceptions to this rule but they are very few:
+ \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.
+ \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.
+
+ \par Rationale:
+ Implementing members inline inside the class declaration makes the declaration much harder
+ to read. Since the declaration in the header file will be used as a reference by the
+ developer, the header files should be as readable as possible.
+
+ Every function or method implementation in one of the implementation files must \e always be
+ prefixed with \c prefix_. This symbol is defined at the beginning of the file and undefined at
+ the end. The symbol must be defined to be \c inline in the \c .cti and \c .cci files and must be
+ defined empty in the \c .cc and \c .ct files.
+
+ \par Rationale:
+ 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