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