// $Id$ // // Copyright (C) 2007 // Fraunhofer Institute for Open Communication Systems (FOKUS) // // 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 // // 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. // // 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 /** \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 You may check the Downloads section for binary library releases. However, in all probability you will have to compile SENF for yourself. If you are interested in SENF, feel free to subscribe to the SENF mailing lists. If you want to contribute, read the docs and \e please adhere to the \ref senf_conventions. \see \ref senf_introduction \n \ref senf_build \n \ref senf_senfutil for linking against the SENF library\n Examples */ /** \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: 
        $ scons
\li Build documentation and unit-tests: 
        $ scons doc test
\li clean up everything 
        $ scons -c all
\li Pass custom options on the command-line 
        $ scons CXXFLAGS+=-Wextra
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 sys.path 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 site_scons/senfutil.py into your project. This script will search for site_scons/senfutil.py 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 senf/, Senf/ or SENF/ thereof, and /usr/local/lib/senf/ and /usr/lib/senf/ \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 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' ], 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 against the SENF library and automatically sets all the correct compiler options using senfutil.SetupForSENF( env ). 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 debug=1 or final=1 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' ], 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) 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 environment. This allows specifying any parameter on the command line: 
    $ scons CXX=myg++ CXXFLAGS+=-mtune=geode
You may either set variables unconditionally using '=' or append values to the end of a list using '+='. */ /** \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. \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 Packet Processing Infrastructure (PPI). Using this library, it is very simple to develop flexible packet networks of interconnected modules. \li Use the Socket library for network communication needs. This library includes support for raw and packet sockets to allow low level network access. \li Use the Scheduler library 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 Packets library. 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 Utils library. It contains small helpers to simplify tasks like daemonization, exception handling, debugging and so on. Additionally, %Utils contains several larger supplementary modules for Logging, Configuration (including interactive configuration via a network terminal) and Daemon management. The simplest way to get started is: copy the Sniffer application and start to modify it. \see Examples \n \ref senf_components \n \ref senf_senfutil \n \ref senf_build \section senf_dependencies Dependencies 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 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 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 To access the code, check out the code from the BerliOS repository. Change to your development directory and use the following subversion command 
    $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
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. Additionally ensure, you have installed all necessary \ref senf_dependencies. \section senf_compile Building To build the library, execute all unit tests and build all examples applications, use 
    $ scons default examples all_tests
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 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 libPPI API reference \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 libSocket API reference \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 libPackets API reference \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 libScheduler API reference \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 libUtils API reference */ /** \page 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:
\c .hC public header
\c .hhC++ public header
\c .ihC++ 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
\c .cC implementation
\c .ccC++ implementation of non-inline non-template functions and members
\c .ctC++ implementation of non-inline template functions and members
\c .cciC++ implementation of inline non-template functions and members
\c .ctiC++ implementation of inline template functions and members
\c .mppSpecial include file used for external iteration by the Boost.Preprocessor library
\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) */ // :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: