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="http://developer.berlios.de/projects/senf"><b><i>The BerliOS project page</i></b></a>\n
  34          <a href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework"><b><i>The SENF Wiki at BerliOS</i></b></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
  52
  53     \section Preliminaries
  54
  55     Before starting the devlopment, make sure to fulfill the following
  56     requirements:
  57
  58     \li GNU g++, version at least 3.4
  59     \li The Boost libraries (http://www.boost.org)
  60     \li The SCons build tool (http://www.scons.org)
  61
  62     If you want to build the documentation, you additionally need
  63
  64     \li Doxygen (http://www.doxygen.org)
  65     \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
  66
  67
  68     The library is only tested with gcc-3.4 and 4.0 on Linux. On other
  69     POSIX platforms with a BSD Socket API, the library should be
  70     usable, possibly with some tweaking (except for the Scheduler,
  71     which relies on \c epoll)
  72
  73     \todo
  74     \li Preliminaries: SVN access, Dependencies
  75     \li Building the library -> Configuration
  76     \li Setting up a project using this library (svn:externals)
  77     \li Library components
  78     \li coding standards and patterns
  79  */
  80
  81 /** \page build Building the framework
  82
  83     This procedure will test building the complete framework
  84     including the unit tests and the Sniffer test application. This
  85     build is \e not needed to use the framework since every project
  86     will include the full SENF source code itself (via Subversion).
  87
  88     After you have successfully built the library tests, you can
  89     continue to setup your own project using SENF.
  90
  91     \see \ref components \n
  92          \ref svnsetup
  93
  94     \section checkout Getting the code
  95
  96     To access the code, check out the code from the BerliOS
  97     repository. Change to your development directory and use the
  98     following subversion command
  99
 100     <pre class="fragment">
 101       $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf</pre>
 102
 103     This will create a new directory \c senf within the current
 104     directory. For further documentation on the use of Subversion, see
 105     the \c svn manpage or the subversion homepage at
 106     http://subversion.tigris.org. A very good introduction and
 107     reference to subversion is available at
 108     http://svnbook.red-bean.com.
 109
 110     \section compile Building
 111
 112     To build the library, execute all unit tests and build the Sniffer
 113     test application, use
 114
 115     <pre class="fragment">
 116       $ scons
 117       $ scons all_tests</pre>
 118
 119     in the \c senf directory. This assumes, that you want to build the
 120     library with your default gcc and requires the boost libraries to
 121     be available in the system include paths. If this is not the case,
 122     you can take a look at <tt>SConfig.template</tt> file. Copy this
 123     file to <tt>SConfig</tt> and comment out all the variables you
 124     don't want to change (The \e values in the template file are just
 125     arbitrary examples).
 126  */
 127
 128 /** \page components The SENF modules
 129
 130     The framework is made up of several modular components. When using
 131     the library, it is possible to selectively choose to use only a
 132     subset of the implemented modules.
 133
 134     \see \ref build \n
 135          \ref svnsetup
 136
 137     \section libSocket libSocket: C++ abstraction of the BSD socket API
 138
 139     This library provides a high performance and object oriented
 140     abstraction of the standard socket API. It utilizes a flexible and
 141     extensible policy based design. The library provides predefined
 142     types for the important socket types (UDP and TCP sockets etc)
 143     including raw and packet sockets. \n
 144
 145     \see <a href="../../Socket/doc/html/index.html">libSocket API
 146     reference</a>
 147
 148     \section libPackets libPackets: Network packet manipulation
 149
 150     This libarary provides a very flexible infrastructure to
 151     parse, create and otherwise manipulate packetized network
 152     data. Included is a library of several protocol parsers covering
 153     the basic IPv4 and IPv6 network protocols down to the Ethernet
 154     layer.
 155
 156     \see <a href="../../Packets/doc/html/index.html">libPackets API
 157     reference</a>
 158
 159     \section libScheduler libScheduler: Asynchronous event handling
 160
 161     The scheduler library provides an object oriented interface to the
 162     standard UNIX \c select type event dispatcher. It is based on the
 163     high performance \c epoll system call. It provides support for
 164     read/write events as well as simple timer based events.
 165
 166     \see <a href="../../Scheduler/doc/html/index.html">libScheduler API
 167     reference</a>
 168
 169     \section libUtils libUtils: Collection of arbitrary utilities
 170
 171     This library is used be most all of the other modules for
 172     miscellaneous tools and utilities. We have
 173
 174     \li Simple functions to manage daemon processes
 175     \li Standard exception classes
 176     \li satcom::lib::intrusive_refcount to simplify the implementation
 177         of classes usable with boost::intrusive_ptr
 178     \li boost::bind extensions
 179     \li An interface to the \c g++ demangler integrated with type_info
 180     \li Typedefs and rudimentary methods to simplify handling
 181         high-resolution time values
 182
 183     \see <a href="../../Utils/doc/html/index.html">libUtils API
 184     reference</a>
 185
 186     \section senfscons SENFSCons, the SENF build environment
 187
 188     SENF relies on SCons (http://www.scons.org) to build. To further
 189     simplify the common tasks, SENF includes a library of custom
 190     routines and builders comprising a very concise build
 191     environment. Included are a number of templates to help
 192     bootstrapping a new project or component.
 193
 194     \see <a href="../../satscons/doc/html/index.html">SENFSCons
 195     reference</a>
 196  */
 197
 198 /** \page svnsetup Setting up a new project using SENF via SVN
 199
 200     The preferred way to use SENF in a new project is to rely on
 201     Subversion and make use of the SENFSCons build environment. The
 202     following sections will describe, how this setup works.
 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 satscons 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         satscons http://svn.berlios.de/svnroot/repos/senf/trunk/satscons
 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     \todo \li Configuring and building -> reference to the SENFSCons
 253               dok
 254  */
 255
 256 /** \page example Sniffer: A simple Example application
 257
 258  */
 259
 260     \section code Coding practices
 261
 262     The library heavily depends on the features of modern C++. As
 263     such, it depends on a fairly recent and standards compliant C++
 264     compiler (the Library is developed using \c gcc with Version at
 265     least 3.4). To meet the above defined goals, the library makes
 266     quite heavy use of advanced templating techniques, so
 267     understanding the implementation will require expertise in the
 268     intricacies of C++ templates. However, it was deemed important to
 269     keep the \e visible Interface of the Library as clean and simple
 270     as possible without sacrificing the projects design goals.
 271
 272     The library heavily depends on the \e Boost libraries (see
 273     http://www.boost.org). The Boost libraries are an ever growing
 274     collection of highest quality reusable C++ components. They are
 275     designed with standardization in mind. Many of the libraries are
 276     already in queue to be part of the next generation C++ standard.
 277
 278 \f
 279 // Local Variables:
 280 // mode: c++
 281 // End:
 282