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
  33 */
  34
  35 /** \page usage Using the SENF framework
  36
  37     The SENF Framework is a collection of loosely coupled
  38     modules. The libraries are heavily object oriented and template
  39     based. For compatibility reasons, the libraries are therefore
  40     built together with every project making use of the framework.
  41
  42     When starting a new Projekt based on the SENF framework, it is
  43     advisable, to make use of the SENFSCons build environment and use
  44     SVN to manage the code repository. This is the configuration,
  45     described in this documentation.
  46
  47     \see \ref build \n
  48          \ref components \n
  49          \ref svnsetup \n
  50          \ref overview
  51
  52     \section Preliminaries
  53
  54     Before starting the devlopment, make sure to fulfill the following
  55     requirements:
  56
  57     \li GNU g++, version at least 3.4
  58     \li The Boost libraries (http://www.boost.org)
  59     \li The SCons build tool (http://www.scons.org)
  60
  61     If you want to build the documentation, you additionally need
  62
  63     \li Doxygen (http://www.doxygen.org)
  64     \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
  65     \li HTML \c tidy (http://tidy.sourceforge.net/)
  66     \li The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html)
  67
  68
  69     The library is only tested with gcc-3.4 and 4.0 on Linux. On other
  70     POSIX platforms with a BSD Socket API, the library should be
  71     usable, possibly with some tweaking (except for the Scheduler,
  72     which relies on \c epoll)
  73  */
  74
  75 /** \page build Building the framework
  76
  77     This procedure will test building the complete framework
  78     including the unit tests and the Sniffer test application. This
  79     build is \e not needed to use the framework since every project
  80     will include the full SENF source code itself (via Subversion).
  81
  82     After you have successfully built the library tests, you can
  83     continue to setup your own project using SENF.
  84
  85     \see \ref components \n
  86          \ref svnsetup
  87
  88     \section checkout Getting the code
  89
  90     To access the code, check out the code from the BerliOS
  91     repository. Change to your development directory and use the
  92     following subversion command
  93
  94     <pre>
  95     $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
  96     </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>
 111     $ scons
 112     $ scons all_tests
 113     </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>
 226     $ svn propedit svn:externals .
 227     </pre>
 228
 229     The default editor (probably VI) will be started with the current
 230     value of the svn:externals property (which will probably be
 231     empty). Now add all the modules you want plus \c senfscons and
 232     possibly \c doclib (if you want to build the documentation). You
 233     will almost certainly neeed the \c Utils module, since all other
 234     modules depend on it.
 235
 236     For example, if you want to use the \c Scheduler and \c Socket
 237     module, the file will look like
 238
 239     <pre>
 240     senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
 241     Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
 242     Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
 243     Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket
 244     </pre>
 245
 246     exit the editor and the property will be set. Now run
 247
 248     <pre>
 249     $ svn update
 250     </pre>
 251
 252     and the code will be checked out into the corresponding
 253     directories.
 254
 255     \section new_conf Configuring SENFSCons
 256
 257     To set up the build environment, copy the
 258     <tt>senfscons/SConstruct.template</tt> to <tt>SConstruct</tt> in
 259     the project root. The default setup of this file is to build all
 260     subdirectories (using the \c SConscript files of the
 261     subdirectories). You can add additonal global targets and
 262     configuration parameters here.
 263
 264     If you want to use a non-default compiler or the boost library is
 265     not installed in the system directories, you will have to copy
 266     <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in the
 267     project root and edit it there. You should \e never add \c SConfig
 268     to the repository since it should only contain local settings
 269     necessary for building on your local system. You should therefore
 270     add \c SConfig to the list of files ignored by Subversion in the
 271     project root. In the project root execute
 272
 273     <pre>
 274     $ svn propedit svn:ignore .
 275     </pre>
 276
 277     and add \c SConfig as a new line to the property.
 278
 279     \section new_build Building the project
 280
 281     You should now be able to build your project using
 282
 283     <pre>
 284     $ scons
 285     </pre>
 286
 287     If you have not changed the \c SConstruct file, this will build
 288     all modules you have importet into your project. To build and
 289     execute the unit tests, use
 290
 291     <pre>
 292     $ scons all_tests
 293     </pre>
 294
 295     you can also build only a subdirectory by changing to it and
 296     running
 297
 298     <pre>
 299     $ scons -u [target]
 300     </pre>
 301
 302     \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
 303          <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
 304          <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
 305          <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
 306  */
 307
 308 /** \page overview Introduction to the framework
 309
 310     The SENF framework is relatively complex and makes use of advanced
 311     features of the C++ language. To make the most efficient use of
 312     the framework, you should have at least a basic understanding of
 313     C++ templates and the standard library concepts.
 314
 315     The library implementation at places makes heavy use of advanced
 316     template techniques and relies on some very advanced template
 317     libraries from Boost. The aim was however for the \e external
 318     interface of the library to be as simple as possible without
 319     sacrificing important functionality or adversely impacting the
 320     runtime performance.
 321
 322     As already mentioned several times, the library relies on Boost
 323     (http://www.boost.org) as a generic library of high quality
 324     reusable C++ components. It also makes frequent use of the
 325     standard library. It is designed, to integrate well into both
 326     libraries and to use the same concepts and ideas.
 327
 328     \section startup Getting starting developing with SENF
 329
 330     To introduce the framework and it's general structure, a simple
 331     example application is provided in the SENF repository in the \c
 332     Sniffer module. Peruse this example to get a first look at how to
 333     make use of SENF.
 334
 335     When building a network Application with SENF, you will use
 336     several modules:
 337
 338     \li Use the <a href="../../Socket/doc/html/index.html">Socket
 339         library</a> for network communication needs. This library
 340         includes support for raw and packet sockets to allow low level
 341         network access.
 342     \li Use the <a
 343         href="../../Scheduler/doc/html/index.html">Scheduler
 344         library</a> to coordinate the asynchronous event
 345         processing. This drastically reduces the number of threads
 346         needed in your application and will greatly enhance the overall
 347         responsiveness.
 348     \li To interpret low level network packets, use the <a
 349         href="../../Packets/doc/html/index.html">Packets
 350         library</a>. This library will provide efficient and
 351         convenient access to all protocol fields. It supports parsing as
 352         well as modifying and creating packets. It has default support
 353         for the most important internet protocols and is highly
 354         extensible with new protocols.
 355     \li Go over the <a href="../../Utils/doc/html/index.html">Utils
 356         library</a>. It contains small helpers to
 357         simplify tasks like daemonization, exception handling,
 358         debugging and so on.
 359
 360     The simplest way to get started is: copy the Sniffer application
 361     and start to modify it.
 362
 363     \see \ref example \n
 364          \ref components \n
 365          \ref svnsetup \n
 366          \ref build
 367  */
 368
 369 \f
 370 // Local Variables:
 371 // mode: c++
 372 // fill-column: 100
 373 // c-file-style: "senf"
 374 // indent-tabs-mode: nil
 375 // ispell-local-dictionary: "american"
 376 // mode: flyspell
 377 // mode: auto-fill
 378 // End: