4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
7 // Version 1.0 (the "License"); you may not use this file except in compliance
8 // with the License. You may obtain a copy of the License at
9 // http://senf.berlios.de/license.html
11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
12 // but modifies the Mozilla Public License Version 1.1.
13 // See the full license text for the amendments.
15 // Software distributed under the License is distributed on an "AS IS" basis,
16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
17 // for the specific language governing rights and limitations under the License.
19 // The Original Code is Fraunhofer FOKUS code.
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
25 // Stefan Bund <g0dil@berlios.de>
28 /** \mainpage SENF: The Simple and Extensible Network Framework
30 The SENF Simple and Extensible Network Framework aims to be a complete set of libraries to
31 facilitate the development of network applications focusing on network protocols on the layers
32 below the application layer. However, the framework includes many general purpose utilities and
33 will be expedient to use well beyond its primary objective.
37 The main goals of this library are (in no particular order):
39 \li modular framework design
40 \li utilizing the power of modern C++
41 \li very low overhead for frequently called members
45 \section start Getting started
47 You may check the Downloads section for binary library releases. However, in all probability you
48 will have to compile SENF for yourself.
50 If you are interested in SENF, feel free to subscribe to the <a
51 href="http://developer.berlios.de/mail/?group_id=7489">SENF mailing lists</a>. If you want to
52 contribute, read the docs and \e please adhere to the \ref senf_conventions.
55 \ref senf_introduction \n
57 \ref senf_senfutil for linking against the SENF library\n
58 <a href="../../Examples/doc/html/index.html">Examples</a>
61 /** \page senf_senfutil SENF SCons build utility (senfutil.py)
65 \c senfutil helps setting up projects which utilize SENF. It will configure all necessary
66 compiler and linker options and additionally sets up some useful defaults and utilities.
68 \c senfutil really serves three roles
70 \li detect the SENF library and configure the build accordingly
71 \li make some SCons extensions used within SENF available to other projects
72 \li set default compilation options in the same way, they are set when compiling SENF proper.
74 The last two points are of course optional.
76 \section senfutil_tutorial Tutorial
78 To utilize \c senfutil you need to do two things:
79 \li Update your \c SConstruct file
80 \li add a bootstrap \c senfutil.py to \c site_scons
82 Lets start with the \c SConstruct file
87 senfutil.SetupForSENF(env)
88 senfutil.DefaultOptions(env)
91 PROJECTNAME = 'Example project',
92 PROJECTEMAIL = 'developer@domain.com',
93 DOCLINKS = [ ('Homepage', 'http://www.domain.com') ]
96 sources, tests = senfutil.Glob(env, exclude=['main.cc'])
98 objects = env.Object(sources)
99 example = env.Program('example', objects + ['main.cc'])
100 test = env.BoostUnitTest('test', objects + tests)
104 senfutil.Doxygen(env)
106 senfutil.CleanGlob('all', [ '*~', '#*#' ])
109 This simple sample already enables a lot of functionality:
110 \li support for different \e SENF flavors (debug/normal/final)
111 \li support for different \e build flavors (debug/normal/final)
112 \li sensible default compile options for the different flavors
113 \li support for extended command-line variables
114 \li building documentation with an auto-generated Doxyfile
115 \li running unit-tests
116 \li cleaning backup and temporary files
118 Here a very quick rundown of the important scons commands:
119 \li Build default target:
123 \li Build documentation and unit-tests:
127 \li clean up everything
131 \li Pass custom options on the command-line
133 $ scons CXXFLAGS+=-Wextra
136 Since \c senfutil.py is not on the standard \c python or \c SCons path, some extra steps are
138 \li Either add the possible directories to <tt>sys.path</tt> before importing \c senfutil:
141 sys.path.extend(('/usr/local/lib/senf/site_scons', '/usr/lib/senf/site_scons'))
144 \li Alternatively, install the following utility script as <tt>site_scons/senfutil.py</tt> into
145 your project. This script will search for <tt>site_scons/senfutil.py</tt> in a list of
146 directories and then load the real \c senfutil.py on top of itself. The directories searched
147 include: the current directory and all parents, subdirectories named <tt>senf/</tt>,
148 <tt>Senf/</tt> or <tt>SENF/</tt> thereof, and <tt>/usr/local/lib/senf/</tt> and
149 <tt>/usr/lib/senf/</tt>
152 \section senfutil_features
154 The \c senfutil utility for SCons helps setting up a project to compile against SENF:
156 \li \c senfutil adds all necessary libraries to link against
157 \li \c senfutil will set necessary compile options.
158 \li \c senfutil supports normal, debug and final project build options
159 \li \c senfutil adds support for Boost unit tests
160 \li \c senfutil implements a very simple to use enhanced doxygen build with SENF symbol
162 \li \c senfutil allows specifying variables on the scons command line
163 \li \c senfutil supports more readable compile-time SENF loglevel configuration
165 Using the utility is quite simple
169 sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons'))
170 import glob, senfutil
173 senfutil.SetupForSENF(env)
174 # senfutil.DefaultOptions(env)
176 # Set or change SCons environment variables with env.Append, env.Replace or env.SetDefault
178 CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
179 CXXFLAGS_final = [ '-O2' ],
180 CXXFLAGS_normal = [ '-O0', '-g' ],
181 CXXFLAGS_debug = [ '$CXXFLAGS_normal' ],
183 LINKFLAGS_normal = [ '-Wl,-S' ],
185 LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
187 PROJECTNAME = 'Example project',
188 PROJECTEMAIL = 'developer@domain.com',
189 DOCLINKS = [ ('Homepage', 'http://www.domain.com') ]
192 # Create a list of sources and tests. Sources are all *.cc files, test are *.test.cc
193 sources, tests = senfutil.Glob(env, exclude=['main.cc'] )
195 # Build objects from sources
196 objects = env.Object(sources)
199 env.Default( env.Program( target='example', source=objects + ['main.cc'] ) )
201 # Build a boost unit-test from additional test sources
202 env.BoostUnitTest( 'test', source=objects + tests)
204 # Build a documentation, autogenerates a Doxyfile
205 senfutil.Doxygen(env)
208 This example builds a simple binary from a number of source files (all '.cc' files). It links
209 against the SENF library and automatically sets all the correct compiler options using
210 <tt>senfutil.SetupForSENF( env )</tt>.
212 This script automatically uses a SENF installation either symlinked or imported into the current
213 project in directory 'senf' or, if this directory does not exist, a globally installed SENF.
215 \section senf_senfutil_options Build options
217 \c senfutil supports the <tt>debug=1</tt> or <tt>final=1</tt> build options. These parameters
218 select one of the build configurations 'debug', 'normal' or 'final'. The following variables are
219 supported each with separate values for all three configurations:
226 \c senfutil will detect the type of SENF library used (final or not) and set the correct compile
229 \section senf_senfutil_loglevels Specifying compile-time loglevels
231 To simplify specifying the compile-time loglevel configuration, the build variable \c LOGLEVELS
232 (and it's build configuration specific variants) may be set. This variable will be parsed and
233 converted into the correct \c SENF_LOG_CONF definition. The \c LOGLEVELS Syntax is
235 \par "" \e optional_stream \c | \e optional_area | \e level
237 where \e optional_stream and \e optional_area are optional fully scoped C++ names (e.g. \c
238 senf::log::Debug) and \e level is the loglevel. There must be \e no whitespace in a single
239 specification, multiple specifications are either specified using an array or separated with
242 \section senf_senfutil_default Default options
244 In the example above, all compile options are set manually. To specify the default customary
245 compile options for SENF programs, \c senfutil.DefaultOptions(env) is provided. This function is
249 senfutil.DefaultOptions(env) =>
251 CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
252 CXXFLAGS_final = [ '-O2' ],
253 CXXFLAGS_normal = [ '-O0', '-g' ],
254 CXXFLAGS_debug = [ '$CXXFLAGS_normal' ],
256 LINKFLAGS_normal = [ '-Wl,-S' ],
260 Thus above example can be simplified to
263 sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons'))
264 import glob, senfutil
267 senfutil.SetupForSENF(env)
268 senfutil.DefaultOptions(env)
270 env.Append( LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
271 PROJECTNAME = 'Example project',
272 PROJECTEMAIL = 'developer@domain.com',
273 DOCLINKS = [ ('Homepage', 'http://www.domain.com') ] )
275 sources, tests = senfutil.Glob(env, exclude=['main.cc'] )
277 objects = env.Object(sources)
278 env.Default( env.Program( target='example', source=objects + ['main.cc'] ) )
279 env.BoostUnitTest( 'test', source=objects + tests)
280 senfutil.Doxygen(env)
283 \section senf_senfutil_tests Building unit tests
285 Building unit tests mostly follows a standard pattern
288 # Generate list of sources and tests (sources=*.cc, tests=*.test.cc)
289 extra_sources = ['main.cc']
290 sources, tests = senfutil.Glob(env, exclude=extra_sources)
292 # Build object files needed for both main target and unit tests
293 objects = env.Object(sources)
295 # Build main target, e.g. a Binary with additional sources which are not part of the unit test
296 env.Program('example', objects+extra_sources)
298 # Build unit tests including additional test sources
299 env.BoostUnitTest('test', objects+tests)
302 It is important to exclude the \c main function from the unit-test build since the boost unit
303 test library provides it's own.
305 \section senf_senfutil_doxygen Building documentation
307 Documentation is built using the \c senfutil.Doxygen utility
310 env.Append( PROJECTNAME = "Example project",
311 PROJECTEMAIL = "coder@example.com",
312 COPYRIGHT = "The Master Coders",
313 DOCLINKS = [ ('Homeage', 'http://www.example.com') ],
314 REVISION = 'r'+os.popen('svnversion').read().strip().lower() )
316 senfutil.Doxygen(env)
319 The \c senfutil.Doxygen utility autogenerates a \c Doxyfile.
321 The utility will search for a SENF documentation in the \c senfdoc and \c %senf subdirectories
322 as well as via the senfutil module directory and some other standard locations. If SENF
323 documentation is found, the SENF tagfiles will automatically be added. Links will be resolved
324 to the documentation found.
326 \c senfutil.Doxygen takes some additional optional keyword arguments:
327 \li \c doxyheader: Path of an alternative HTML header
328 \li \c doxyfooter: Path of an alternative HTML footer
329 \li \c doxycss: Path on an alternative CSS file
330 \li \c mydoxyfile: If set to \c True, don't generate or clean the \c Doxyfile\
331 \li \c senfdoc_path: List of additional directories to search for SENF documentation
333 \section senf_senfutil_arguments 'scons' Command line arguments
335 \c senfutil automatically parses SCons command line arguments into the SCons build
336 environment. This allows specifying any parameter on the command line:
338 $ scons CXX=myg++ CXXFLAGS+=-mtune=geode
340 You may either set variables unconditionally using '=' or append values to the end of a list
344 /** \page senf_introduction Introduction to the framework
346 The SENF framework is relatively complex and makes use of advanced features of the C++
347 language. To make the most efficient use of the framework, you should have at least a basic
348 understanding of C++ templates and the standard library concepts.
350 The library implementation at places makes heavy use of advanced template techniques and relies
351 on some very advanced template libraries from Boost. The aim was however for the \e external
352 interface of the library to be as simple as possible without sacrificing important functionality
353 or adversely impacting the runtime performance.
355 As already mentioned several times, the library relies on Boost (http://www.boost.org) as a
356 generic library of high quality reusable C++ components. It also makes frequent use of the
357 standard library. It is designed, to integrate well into both libraries and to use the same
360 \section senf_startup Getting starting developing with SENF
362 To introduce the framework and it's general structure, some simple example applications are
363 provided in the SENF repository. Peruse those examples to get a first look at how to make use of
366 When building a network Application with SENF, you will use several modules:
368 \li One of the central SENF libraries is the <a
369 href="../../senf/PPI/doc/html/index.html">Packet Processing Infrastructure (PPI)</a>. Using
370 this library, it is very simple to develop flexible packet networks of interconnected
372 \li Use the <a href="../../senf/Socket/doc/html/index.html">Socket library</a> for network
373 communication needs. This library includes support for raw and packet sockets to allow low
374 level network access.
375 \li Use the <a href="../../senf/Scheduler/doc/html/index.html">Scheduler library</a> to
376 coordinate the asynchronous event processing. This drastically reduces the number of threads
377 needed in your application and will greatly enhance the overall responsiveness.
378 \li To interpret low level network packets, use the <a
379 href="../../senf/Packets/doc/html/index.html">Packets library</a>. This library will provide
380 efficient and convenient access to all protocol fields. It supports parsing as well as
381 modifying and creating packets. It has default support for the most important Internet
382 protocols and is highly extensible with new protocols.
383 \li Go over the <a href="../../senf/Utils/doc/html/index.html">Utils library</a>. It contains
384 small helpers to simplify tasks like daemonization, exception handling, debugging and so
385 on. Additionally, %Utils contains several larger supplementary modules for <a
386 href="../../senf/Utils/Logger/doc/html/index.html">Logging</a>, <a
387 href="../../senf/Utils/Console/doc/html/index.html">Configuration</a> (including interactive
388 configuration via a network terminal) and <a
389 href="../../senf/Utils/Daemon/doc/html/index.html">Daemon management</a>.
391 The simplest way to get started is: copy the Sniffer application and start to modify it.
393 \see <a href="../../Examples/doc/html/index.html">Examples</a> \n
394 \ref senf_components \n
395 \ref senf_senfutil \n
398 \section senf_dependencies Dependencies
400 Before starting the development, make sure to fulfill the following requirements:
402 \li GNU g++, version at least 3.4
403 \li The Boost libraries (http://www.boost.org)
404 \li The SCons build tool (http://www.scons.org)
406 If you want to build the documentation, you additionally need
408 \li Doxygen (http://www.doxygen.org)
409 \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
410 \li HTML \c tidy (http://tidy.sourceforge.net/)
411 \li The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html)
412 \li The \c graphviz library (http://www.graphviz.org)
414 The library is tested and developed on Linux. It should be relatively simple to port SENF to
415 other POSIX platforms.
418 /** \page senf_build Building the SENF framework
420 This procedure will build the complete framework including the unit tests and the example
421 applications. After you have successfully built the library tests, you can continue to setup
422 your own project linking against SENF.
424 \section senf_checkout Getting the code
426 To access the code, check out the code from the BerliOS repository. Change to your development
427 directory and use the following subversion command
430 $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
433 This will create a new directory \c senf within the current directory. For further documentation
434 on the use of Subversion, see the \c svn man-page or the subversion homepage at
435 http://subversion.tigris.org. A very good introduction and reference to subversion is available
436 at http://svnbook.red-bean.com.
438 Additionally ensure, you have installed all necessary \ref senf_dependencies.
440 \section senf_compile Building
442 To build the library, execute all unit tests and build all examples applications, use
444 $ scons default examples all_tests
446 This assumes, that you want to build the library with your default gcc and requires the boost
447 libraries to be available in the system include paths. If this is not the case take a look a the
448 \c SConstruct file for configuration variables. You may either specify the variables on the
449 command line or place them into a \c SConscript.local file.
452 /** \page senf_components The SENF modules
454 The framework is made up of several modular components. When using the library, it is possible
455 to selectively choose to use only a subset of the implemented modules.
457 \see \ref senf_overview
459 \section libPPI libPPI: Packet Processing Infrastructure
461 The Packet Processing Infrastructure implements a modular framework for implementing packet
462 oriented network applications. The library provides a large set of pre-defined modules as well
463 as the necessary helpers to implement application specific processing modules.
465 \see <a href="../../senf/PPI/doc/html/index.html">libPPI API reference</a>
467 \section libSocket libSocket: C++ abstraction of the BSD socket API
469 This library provides a high performance and object oriented abstraction of the standard socket
470 API. It utilizes a flexible and extensible policy based design. The library provides predefined
471 types for the important socket types (UDP and TCP sockets etc) including raw and packet sockets.
473 \see <a href="../../senf/Socket/doc/html/index.html">libSocket API reference</a>
475 \section libPackets libPackets: Network packet manipulation
477 This library provides a very flexible infrastructure to parse, create and otherwise manipulate
478 packetized network data. Included is a library of several protocol parsers covering the basic
479 IPv4 and IPv6 network protocols down to the Ethernet layer.
481 \see <a href="../../senf/Packets/doc/html/index.html">libPackets API reference</a>
483 \section libScheduler libScheduler: Asynchronous event handling
485 The scheduler library provides an object oriented interface to the standard UNIX \c select type
486 event dispatcher. It is based on the high performance \c epoll system call. It provides support
487 for read/write events as well as simple timer based events.
489 \see <a href="../../senf/Scheduler/doc/html/index.html">libScheduler API reference</a>
491 \section libUtils libUtils: Collection of arbitrary utilities
493 This library is used be most all of the other modules for miscellaneous tools and utilities. We
496 \li Simple functions to manage daemon processes
497 \li Standard exception classes
498 \li senf::intrusive_refcount to simplify the implementation of classes usable with
500 \li boost::bind extensions
501 \li An interface to the \c g++ de-mangler integrated with type_info
502 \li Typedefs and rudimentary methods to simplify handling high-resolution time values
504 \see <a href="../../senf/Utils/doc/html/index.html">libUtils API reference</a>
507 /** \page senf_conventions Coding Conventions
509 Here we have laid down the coding conventions used throughout the SENF framework. Please ad here
510 to these conventions when changing or adding code. If you use emacs, you can use the C++ IDE for
511 emacs from http://g0dil.de which greatly simplifies following these conventions.
513 \subsection senf_conventions_file_naming File Naming
515 Files should be named according to the main class they define. A single header file should
516 define only one main class. Exceptions to this rule are OK.
519 This simplifies finding the implementation/header for a given class and also reduces the
520 size of each single file.
522 The implementation is divided into a number of different files:
524 <table class="glossary"> <tr><td>\c .h</td><td>C public header</td></tr>
526 <tr><td>\c .hh</td><td>C++ public header</td></tr>
528 <tr><td>\c .ih</td><td>C++ internal header used only by the implementation. This header will
529 probably be included indirectly by the public header but is not meant to be perused by the
530 library user</td></tr>
532 <tr><td>\c .c</td><td>C implementation</td></tr>
534 <tr><td>\c .cc</td><td>C++ implementation of non-inline non-template functions and
537 <tr><td>\c .ct</td><td>C++ implementation of non-inline template functions and members</td></tr>
539 <tr><td>\c .cci</td><td>C++ implementation of inline non-template functions and
542 <tr><td>\c .cti</td><td>C++ implementation of inline template functions and members</td></tr>
544 <tr><td>\c .mpp</td><td>Special include file used for external iteration by the
545 Boost.Preprocessor library</td></tr> </table>
548 There are two part's to this: First, separating the implementation of inlines and templates
549 out of the header file makes the header file much easier to read. This is important, since
550 the header file will be used as a reference by the developers.
552 Separating inline from non-inline members is used together with the \c prefix_ convention
553 below to ensure the correct placement of inline vs non-inline members in the source
554 code. The C++ language requires, that inline members must be included into \e every
555 compilation unit, non-inline members however must be included \e only in one compilation
556 unit. Placing the inline members into a separate file allows to automate this: Simply moving
557 an implementation from one of the inline files into one of the non-inline files will change
558 the type of implementation accordingly.
560 \subsection senf_conventions_type_naming Type Naming
562 SENF prefers the use of the CapitalziedLettersToSeparateWords convention for class names. In
563 this case, class names must start with a capital letter. There are some exceptions to this rule:
564 Types which define new basic data types to be used like other built-in types may be named using
565 lowercase letters plus underscores. Also, if a type or class is directly related to some other
566 library (STL or Boost) which uses the underscore convention, it might be more sensible to follow
567 this convention. This is open to debate.
570 Naming types with capital letters nicely gives a visual clue, that a symbol is a type
571 name. This can also be used by the editor to highlight type names correctly. Additionally,
572 this convention is compact and does not add additional or repeated overhead.
574 \subsection senf_conventions_impl Implementation
576 Only in very few places, SENF allows the use of inline implementations (not to be confused with
577 inline functions). An \e implementation is inline, if it is written directly into the class
578 definition in the header file. Again there are exceptions to this rule but they are very few:
579 \li When defining simple exception classes, the 'what()' member may be defined inline if it
580 returns a string constant.
581 \li It may be OK to use inline implementations for one-line implementations in internal
583 \li The Packet library allows inline implementations for the definition of parsers since doing
584 so outside the declaration just gets to verbose and parsers definitions are quite length but
585 very simple and straight forward.
588 Implementing members inline inside the class declaration makes the declaration much harder
589 to read. Since the declaration in the header file will be used as a reference by the
590 developer, the header files should be as readable as possible.
592 Every function or method implementation in one of the implementation files must \e always be
593 prefixed with \c prefix_. This symbol is defined at the beginning of the file and undefined at
594 the end. The symbol must be defined to be \c inline in the \c .cti and \c .cci files and must be
595 defined empty in the \c .cc and \c .ct files.
598 Together with splitting inlines and non-inlines into separate files, this allows to
599 automatically include the inline definitions at the right places. See above.
601 Private data members are named with a trailing underscore character.
604 This helps distinguishing local variables from parameter names. The trailing underscore
605 does not interfere with other naming conventions and is allowed by the standard (underscore
606 at the beginning of the name are problematic since some classes of names beginning with an
607 underscore are reserved for the standard library implementation)
611 // :vim:textwidth=100
615 // c-file-style: "senf"
616 // indent-tabs-mode: nil
617 // ispell-local-dictionary: "american"
618 // compile-command: "scons doc"