Mainpage.dox

   1 /** \mainpage SENF: The Simple and Extensible Network Framework
   2
   3     The SENF Simple and Extensible Network Framework aims to be a
   4     complete set of libraries to facilitate the development of network
   5     applications focusing on network protocols on the layers below the
   6     application layer. However, the framework includes many general
   7     purpose utilities and will be expedient to use well beyond its
   8     primary objective.
   9
  10     \section Goals
  11
  12     The main goals of this library are (in no particular order):
  13
  14     \li modular framework design
  15     \li utilizing the power of modern C++
  16     \li very low overhead for frequently called members
  17     \li extensible design
  18     \li concise interface
  19
  20     \section start Getting started
  21
  22     To get started using this library, begin by checking out the code
  23     from the <a
  24     href="http://developer.berlios.de/svn/?group_id=7489">BerliOS SVN
  25     repository</a>. You may find help on using the library at '\ref
  26     usage'. If you are interested in SENF, feel free to subscribe
  27     to the <a
  28     href="http://developer.berlios.de/mail/?group_id=7489">SENF
  29     mailing lists</a>.
  30
  31     \see \ref usage\n
  32          \ref example\n
  33          <a href="xref.html">Current status: Cross reference of action points</a>\n
  34          <a class="ext" href="http://developer.berlios.de/projects/senf">The BerliOS project page</a>\n
  35          <a class="ext" href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">The SENF Wiki at BerliOS</a>
  36 */
  37
  38 /** \page usage Using the SENF framework
  39
  40     The SENF Framework is a collection of lossly coupled
  41     modules. The libraries are heavily object oriented and template
  42     based. For compatibility reasons, the libraries are therefore
  43     built together with every project making use of the framework.
  44
  45     When starting a new Projekt based on the SENF framework, it is
  46     advisable, to make use of the SENFSCons build environment and use
  47     SVN to manage the code repository. This is the configuration,
  48     described in this documentation.
  49
  50     \see \ref build \n
  51          \ref components \n
  52          \ref svnsetup \n
  53          \ref overview
  54
  55     \section Preliminaries
  56
  57     Before starting the devlopment, make sure to fulfill the following
  58     requirements:
  59
  60     \li GNU g++, version at least 3.4
  61     \li The Boost libraries (http://www.boost.org)
  62     \li The SCons build tool (http://www.scons.org)
  63
  64     If you want to build the documentation, you additionally need
  65
  66     \li Doxygen (http://www.doxygen.org)
  67     \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
  68
  69
  70     The library is only tested with gcc-3.4 and 4.0 on Linux. On other
  71     POSIX platforms with a BSD Socket API, the library should be
  72     usable, possibly with some tweaking (except for the Scheduler,
  73     which relies on \c epoll)
  74  */
  75
  76 /** \page build Building the framework
  77
  78     This procedure will test building the complete framework
  79     including the unit tests and the Sniffer test application. This
  80     build is \e not needed to use the framework since every project
  81     will include the full SENF source code itself (via Subversion).
  82
  83     After you have successfully built the library tests, you can
  84     continue to setup your own project using SENF.
  85
  86     \see \ref components \n
  87          \ref svnsetup
  88
  89     \section checkout Getting the code
  90
  91     To access the code, check out the code from the BerliOS
  92     repository. Change to your development directory and use the
  93     following subversion command
  94
  95     <pre class="fragment">
  96       $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf</pre>
  97
  98     This will create a new directory \c senf within the current
  99     directory. For further documentation on the use of Subversion, see
 100     the \c svn manpage or the subversion homepage at
 101     http://subversion.tigris.org. A very good introduction and
 102     reference to subversion is available at
 103     http://svnbook.red-bean.com.
 104
 105     \section compile Building
 106
 107     To build the library, execute all unit tests and build the Sniffer
 108     test application, use
 109
 110     <pre class="fragment">
 111       $ scons
 112       $ scons all_tests</pre>
 113
 114     in the \c senf directory. This assumes, that you want to build the
 115     library with your default gcc and requires the boost libraries to
 116     be available in the system include paths. If this is not the case,
 117     you can take a look at <tt>SConfig.template</tt> file. Copy this
 118     file to <tt>SConfig</tt> and comment out all the variables you
 119     don't want to change (The \e values in the template file are just
 120     arbitrary examples).
 121  */
 122
 123 /** \page components The SENF modules
 124
 125     The framework is made up of several modular components. When using
 126     the library, it is possible to selectively choose to use only a
 127     subset of the implemented modules.
 128
 129     \see \ref build \n
 130          \ref svnsetup
 131
 132     \section libSocket libSocket: C++ abstraction of the BSD socket API
 133
 134     This library provides a high performance and object oriented
 135     abstraction of the standard socket API. It utilizes a flexible and
 136     extensible policy based design. The library provides predefined
 137     types for the important socket types (UDP and TCP sockets etc)
 138     including raw and packet sockets. \n
 139
 140     \see <a href="../../Socket/doc/html/index.html">libSocket API
 141     reference</a>
 142
 143     \section libPackets libPackets: Network packet manipulation
 144
 145     This libarary provides a very flexible infrastructure to
 146     parse, create and otherwise manipulate packetized network
 147     data. Included is a library of several protocol parsers covering
 148     the basic IPv4 and IPv6 network protocols down to the Ethernet
 149     layer.
 150
 151     \see <a href="../../Packets/doc/html/index.html">libPackets API
 152     reference</a>
 153
 154     \section libScheduler libScheduler: Asynchronous event handling
 155
 156     The scheduler library provides an object oriented interface to the
 157     standard UNIX \c select type event dispatcher. It is based on the
 158     high performance \c epoll system call. It provides support for
 159     read/write events as well as simple timer based events.
 160
 161     \see <a href="../../Scheduler/doc/html/index.html">libScheduler API
 162     reference</a>
 163
 164     \section libUtils libUtils: Collection of arbitrary utilities
 165
 166     This library is used be most all of the other modules for
 167     miscellaneous tools and utilities. We have
 168
 169     \li Simple functions to manage daemon processes
 170     \li Standard exception classes
 171     \li senf::intrusive_refcount to simplify the implementation
 172         of classes usable with boost::intrusive_ptr
 173     \li boost::bind extensions
 174     \li An interface to the \c g++ demangler integrated with type_info
 175     \li Typedefs and rudimentary methods to simplify handling
 176         high-resolution time values
 177
 178     \see <a href="../../Utils/doc/html/index.html">libUtils API
 179     reference</a>
 180
 181     \section senfscons SENFSCons, the SENF build environment
 182
 183     SENF relies on SCons (http://www.scons.org) to build. To further
 184     simplify the common tasks, SENF includes a library of custom
 185     routines and builders comprising a very concise build
 186     environment. Included are a number of templates to help
 187     bootstrapping a new project or component.
 188
 189     \see <a href="../../senfscons/doc/html/index.html">SENFSCons
 190     reference</a>
 191  */
 192
 193 /** \page svnsetup Setting up a new project using SENF
 194
 195     The preferred way to use SENF in a new project is to rely on
 196     Subversion and make use of the SENFSCons build environment. The
 197     following sections will describe, how this setup works.
 198
 199     \see \ref build \n
 200          \ref components \n
 201          \ref overview
 202
 203     \section svnext Setting up the project repository
 204
 205     The most seamless integration is possible if you rely on
 206     Subversion to manage the new project. Subversion does support
 207     'external repositories'. This allows to import code from a foreign
 208     repository into the checkout without importing it into your
 209     repository. The code will always stay at the remote repository,
 210     updates are automatically available.
 211
 212     First setup a new empty repository as described for example in the
 213     Subversion book at http://svnbook.red-bean.com or as mandated by
 214     your site policy. We will call the project 'Foo' and assume, that
 215     the project has been checked out into the 'Foo' directory.
 216
 217     You now have to decide, which modules you want to use. Every
 218     module resides in it's own subdirectory in the SENF
 219     repository. Instead of directly checking out the code, we will use
 220     \c svn:externals. This will instruct \c svn to auutomatically
 221     check out the needed directories from the BerliOS SENF
 222     repository. Change to the 'Foo' directory and type
 223
 224       <pre class="fragment">
 225         $ svn propedit svn:externals .</pre>
 226
 227     The default editor (probably VI) will be started with the current
 228     value of the svn:externals property (which will probably be
 229     empty). Now add all the modules you want plus \c senfscons and
 230     possibly \c doclib (if you want to build the documentation). You
 231     will almost certainly neeed the \c Utils module, since all other
 232     modules depend on it.
 233
 234     For example, if you want to use the \c Scheduler and \c Socket
 235     module, the file will look like
 236
 237       <pre class="fragment">
 238         senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
 239         Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
 240         Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
 241         Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket</pre>
 242
 243     exit the editor and the property will be set. Now run
 244
 245       <pre class="fragment">
 246         $ svn update</pre>
 247
 248     and the code will be checked out into the corresponding
 249     directories.
 250
 251     \section new_conf Configuring SENFSCons
 252
 253     To set up the build environment, copy the
 254     <tt>senfscons/SConstruct.template</tt> to <tt>Satscons</tt> in the
 255     project root. The default setup of this file is to build all
 256     subdirectories (using the \c SConscript files of the
 257     subdirectories). You can add additonal global targets and
 258     configuration parameters here.
 259
 260     If you want to use a non-default compiler or the boost library is
 261     not installed in the system directories, you will have to copy
 262     <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in the
 263     project root and edit it there. You should \e never add \c SConfig
 264     to the repository since it should only contain local settings
 265     necessary for building on your local system. You should therefore
 266     add \c SConfig to the list of files ignored by Subversion in the
 267     project root. In the project root execute
 268
 269     <pre class="fragment">
 270       $ svn propedit svn:ignore .</pre>
 271
 272     and add \c SConfig as a new line to the property.
 273
 274     \section new_build Building the project
 275
 276     You should now be able to build your project using
 277
 278     <pre class="fragment">
 279       $ scons</pre>
 280
 281     If you have not changed the \c SConstruct file, this will build
 282     all modules you have importet into your project. To build and
 283     execute the unit tests, use
 284
 285     <pre class="fragment">
 286       $ scons all_tests</pre>
 287
 288     you can also build only a subdirectory by changing to it and
 289     running
 290
 291     <pre class="fragment">
 292       $ scons -u [target]</pre>
 293
 294     \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
 295          <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
 296          <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
 297          <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
 298  */
 299
 300 /** \page overview Introduction to the framework
 301
 302     The SENF framework is relatively complex and makes use of advanced
 303     features of the C++ language. To make the most efficient use of
 304     the framework, you should have at least a basic understanding of
 305     C++ templates and the standard library concepts.
 306
 307     The library implementation at places makes heavy use of advanced
 308     template techniques and relies on some very advanced template
 309     libraries from Boost. The aim was however for the \e external
 310     interface of the library to be as simple as possible without
 311     sacrificing important functionality or adversely impacting the
 312     runtime performance.
 313
 314     As already mentioned several times, the library relies on Boost
 315     (http://www.boost.org) as a generic library of high quality
 316     reusable C++ components. It also makes frequent use of the
 317     standard library. It is designed, to integrate well into both
 318     libraries and to use the same concepts and ideas.
 319
 320     \section startup Getting starting developing with SENF
 321
 322     To introduce the framework and it's general structure, a simple
 323     example application is provided in the SENF repository in the \c
 324     Sniffer module. Peruse this example to get a first look at how to
 325     make use of SENF.
 326
 327     When building a network Application with SENF, you will use
 328     several modules:
 329
 330     \li Use the <a href="../../Socket/doc/html/index.html">Socket
 331         library</a> for network communication needs. This library
 332         includes support for raw and packet sockets to allow low level
 333         network access.
 334     \li Use the <a
 335         href="../../Scheduler/doc/html/index.html">Scheduler
 336         library</a> to coordinate the asynchronous event
 337         processing. This drastically reduces the number of threads
 338         needed in your application and will greatly enhance the overall
 339         responsiveness.
 340     \li To interpret low level network packets, use the <a
 341         href="../../Packets/doc/html/index.html">Packets
 342         library</a>. This library will provide efficient and
 343         convenient access to all protocol fields. It supports parsing as
 344         well as modifying and creating packets. It has default support
 345         for the most important TCP protocols and is highly extensible
 346         with new protocols.
 347     \li Go over the <a href="../../Utils/doc/html/index.html">Utils
 348         library</a>. It contains small helpers to
 349         simplify tasks like daemonization, exception handling,
 350         debugging and so on.
 351
 352     The simplest way to get started is: copy the Sniffer application
 353     and start to modify it.
 354
 355     \see \ref example \n
 356          \ref components \n
 357          \ref svnsetup \n
 358          \ref build
 359  */
 360
 361 \f
 362 // Local Variables:
 363 // mode: c++
 364 // mode: flyspell
 365 // mode: auto-fill
 366 // ispell-local-dictionary: "american"
 367 // End:
 368