[senf.git] / doclib / Mainpage.dox

// $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 senf_senfutil "senfutil.py" 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 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
    <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' ],
                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:
    <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: