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