[senf.git] / Mainpage.dox

/** \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
    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>.

    \see \ref usage\n
         \ref example\n
         <a href="xref.html">Current status: Cross reference of action points</a>\n
         <a class="ext" href="http://developer.berlios.de/projects/senf">The BerliOS project page</a>\n
         <a class="ext" href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">The SENF Wiki at BerliOS</a>
*/

/** \page usage Using the SENF framework

    The SENF Framework is a collection of loosely coupled
    modules. The libraries are heavily object oriented and template
    based. For compatibility reasons, the libraries are therefore
    built together with every project making use of the framework.

    When starting a new Projekt based on the SENF framework, it is
    advisable, to make use of the SENFSCons build environment and use
    SVN to manage the code repository. This is the configuration,
    described in this documentation.

    \see \ref build \n
         \ref components \n
         \ref svnsetup \n
         \ref overview

    \section Preliminaries

    Before starting the devlopment, 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)


    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)
 */

/** \page build Building the 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 components \n
         \ref svnsetup

    \section 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 class="fragment">
      $ 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 manpage or the subversion homepage at
    http://subversion.tigris.org. A very good introduction and
    reference to subversion is available at
    http://svnbook.red-bean.com.

    \section compile Building

    To build the library, execute all unit tests and build the Sniffer
    test application, use

    <pre class="fragment">
      $ 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 components The SENF modules

    The framework is made up of several modular components. When using
    the library, it is possible to selectively choose to use only a
    subset of the implemented modules.

    \see \ref build \n
         \ref svnsetup
    
    \section libSocket libSocket: C++ abstraction of the BSD socket API

    This library provides a high performance and object oriented
    abstraction of the standard socket API. It utilizes a flexible and
    extensible policy based design. The library provides predefined
    types for the important socket types (UDP and TCP sockets etc)
    including raw and packet sockets. \n

    \see <a href="../../Socket/doc/html/index.html">libSocket API
    reference</a>

    \section libPackets libPackets: Network packet manipulation

    This libarary provides a very flexible infrastructure to
    parse, create and otherwise manipulate 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++ demangler 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 svnsetup Setting up a new project using SENF
    
    The preferred way to use SENF in a new project is to rely on
    Subversion and make use of the SENFSCons build environment. The
    following sections will describe, how this setup works.

    \see \ref build \n
         \ref components \n
         \ref overview

    \section svnext Setting up the project repository

    The most seamless integration is possible if you rely on
    Subversion to manage the new project. Subversion does support
    'external repositories'. This allows to import code from a foreign
    repository into the checkout without importing it into your
    repository. The code will always stay at the remote repository,
    updates are automatically available.

    First setup a new empty repository as described for example in the
    Subversion book at http://svnbook.red-bean.com or as mandated by
    your site policy. We will call the project 'Foo' and assume, that
    the project has been checked out into the 'Foo' directory.

    You now have to decide, which modules you want to use. Every
    module resides in it's own subdirectory in the SENF
    repository. Instead of directly checking out the code, we will use
    \c svn:externals. This will instruct \c svn to auutomatically
    check out the needed directories from the BerliOS SENF
    repository. Change to the 'Foo' directory and type
    
      <pre class="fragment">
        $ svn propedit svn:externals .</pre>

    The default editor (probably VI) will be started with the current
    value of the svn:externals property (which will probably be
    empty). Now add all the modules you want plus \c senfscons and
    possibly \c doclib (if you want to build the documentation). You
    will almost certainly neeed the \c Utils module, since all other
    modules depend on it.

    For example, if you want to use the \c Scheduler and \c Socket
    module, the file will look like

      <pre class="fragment">
        senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
        Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
        Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
        Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket</pre>

    exit the editor and the property will be set. Now run

      <pre class="fragment">
        $ svn update</pre>

    and the code will be checked out into the corresponding
    directories. 

    \section new_conf Configuring SENFSCons

    To set up the build environment, copy the
    <tt>senfscons/SConstruct.template</tt> to <tt>SConstruct</tt> in
    the project root. The default setup of this file is to build all
    subdirectories (using the \c SConscript files of the
    subdirectories). You can add additonal global targets and
    configuration parameters here.

    If you want to use a non-default compiler or the boost library is
    not installed in the system directories, you will have to copy
    <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in the
    project root and edit it there. You should \e never add \c SConfig
    to the repository since it should only contain local settings
    necessary for building on your local system. You should therefore
    add \c SConfig to the list of files ignored by Subversion in the
    project root. In the project root execute

    <pre class="fragment">
      $ svn propedit svn:ignore .</pre>

    and add \c SConfig as a new line to the property.

    \section new_build Building the project

    You should now be able to build your project using

    <pre class="fragment">
      $ scons</pre>

    If you have not changed the \c SConstruct file, this will build
    all modules you have importet into your project. To build and
    execute the unit tests, use

    <pre class="fragment">
      $ scons all_tests</pre>

    you can also build only a subdirectory by changing to it and
    running
    
    <pre class="fragment">
      $ scons -u [target]</pre>

    \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
         <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
         <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
         <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
 */

/** \page overview Introduction to the framework
    
    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 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 \ref example \n
         \ref components \n
         \ref svnsetup \n
         \ref build
 */

\f
// Local Variables:
// mode: c++
// mode: flyspell
// mode: auto-fill
// ispell-local-dictionary: "american"
// End: