X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Mainpage.dox;h=049d80cdd272c2d120bc003cfaae22f5888ba2d2;hb=5443435c4c2b6e4386c5334b5b8358273f2bae93;hp=74b54758dbcc31a9df4fb9322a5aecfce4314678;hpb=05633cf2fb569dad4bf2118ec5203e61974b35f5;p=senf.git diff --git a/Mainpage.dox b/Mainpage.dox index 74b5475..049d80c 100644 --- a/Mainpage.dox +++ b/Mainpage.dox @@ -1,11 +1,31 @@ +// $Id$ +// +// Copyright (C) 2007 +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY +// Stefan Bund +// +// This program is free software; you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation; either version 2 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program; if not, write to the +// Free Software Foundation, Inc., +// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + /** \mainpage SENF: The Simple and Extensible Network Framework - The SENF Simple and Extensible Network Framework aims to be a - complete set of libraries to facilitate the development of network - applications focusing on network protocols on the layers below the - application layer. However, the framework includes many general - purpose utilities and will be expedient to use well beyond its - primary objective. + The SENF Simple and Extensible Network Framework aims to be a complete set of libraries to + facilitate the development of network applications focusing on network protocols on the layers + below the application layer. However, the framework includes many general purpose utilities and + will be expedient to use well beyond its primary objective. \section Goals @@ -14,47 +34,39 @@ \li modular framework design \li utilizing the power of modern C++ \li very low overhead for frequently called members - \li extensible design + \li extensible design \li concise interface \section start Getting started - To get started using this library, begin by checking out the code - from the BerliOS SVN - repository. You may find help on using the library at '\ref - usage'. If you are interested in SENF, feel free to subscribe - to the SENF - mailing lists. - - \see \ref usage\n - \ref example\n - The BerliOS project page\n - The SENF Wiki at BerliOS + To get started using this library, begin by checking out the code from the BerliOS SVN repository. You may find + help on using the library at '\ref senf_usage'. If you are interested in SENF, feel free to subscribe + to the SENF mailing lists. If you + want to contribute, read the docs and \e please adhere to the \ref senf_conventions. + + \see \ref senf_usage\n + Examples */ -/** \page usage Using the SENF framework +/** \page senf_usage Using the SENF framework - The SENF Framework is a collection of lossly coupled - modules. The libraries are heavily object oriented and template - based. For compatibility reasons, the libraries are therefore - built together with every project making use of the framework. + The SENF Framework is a collection of loosely coupled modules. The libraries are heavily object + oriented and template based. For compatibility reasons, the libraries are therefore built + together with every project making use of the framework. - When starting a new Projekt based on the SENF framework, it is - advisable, to make use of the SENFSCons build environment and use - SVN to manage the code repository. This is the configuration, - described in this documentation. + When starting a new project based on the SENF framework, it is advisable, to make use of the + SENFSCons build environment and use SVN to manage the code repository. This is the + configuration, described in this documentation. - \see \ref build \n - \ref components \n - \ref svnsetup \n - \ref overview + \see \ref senf_build \n + \ref senf_setup \n + \ref senf_components \n + \ref senf_overview - \section Preliminaries + \section senf_preliminaries Preliminaries - Before starting the devlopment, make sure to fulfill the following - requirements: + Before starting the development, make sure to fulfill the following requirements: \li GNU g++, version at least 3.4 \li The Boost libraries (http://www.boost.org) @@ -64,304 +76,329 @@ \li Doxygen (http://www.doxygen.org) \li The \c dia diagram editor (http://www.gnome.org/projects/dia/) + \li HTML \c tidy (http://tidy.sourceforge.net/) + \li The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html) + \li The \c graphviz library (http://www.graphviz.org) - The library is only tested with gcc-3.4 and 4.0 on Linux. On other - POSIX platforms with a BSD Socket API, the library should be - usable, possibly with some tweaking (except for the Scheduler, + The library is only tested with gcc-3.4 and 4.0 on Linux. On other POSIX platforms with a BSD + Socket API, the library should be usable, possibly with some tweaking (except for the Scheduler, which relies on \c epoll) + + \section senf_compiler_options Compiler and Linker Options + + If SENF is compiled in debug mode (SENF_DEBUG is defined), exception messages will automatically + include a stack backtrace. For this to work, you need to add the -rdynamic option to all link + commands. This feature depends on gcc and the GNU-libc. + + It is very important that both the SENF library and the application using it are compiled + \e both either with or without this compiler switch (-DSENF_DEBUG). Otherwise, the compiler will + emit error messages which might be hard to debug. */ -/** \page build Building the framework - - This procedure will test building the complete framework - including the unit tests and the Sniffer test application. This - build is \e not needed to use the framework since every project +/** \page senf_build Building the SENF framework + + This procedure will test building the complete framework including the unit tests and the + Sniffer test application. This build is \e not needed to use the framework since every project will include the full SENF source code itself (via Subversion). - After you have successfully built the library tests, you can - continue to setup your own project using SENF. + After you have successfully built the library tests, you can continue to setup your own project + using SENF. - \see \ref components \n - \ref svnsetup + \see \ref senf_setup \n + \ref senf_components \n + \ref senf_overview - \section checkout Getting the code + \section senf_checkout Getting the code - To access the code, check out the code from the BerliOS - repository. Change to your development directory and use the - following subversion command + To access the code, check out the code from the BerliOS repository. Change to your development + directory and use the following subversion command - 
-      $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
+ 
+    $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
+
- This will create a new directory \c senf within the current - directory. For further documentation on the use of Subversion, see - the \c svn manpage or the subversion homepage at - http://subversion.tigris.org. A very good introduction and - reference to subversion is available at - http://svnbook.red-bean.com. + This will create a new directory \c senf within the current directory. For further documentation + on the use of Subversion, see the \c svn man-page or the subversion homepage at + http://subversion.tigris.org. A very good introduction and reference to subversion is available + at http://svnbook.red-bean.com. - \section compile Building + \section senf_compile Building - To build the library, execute all unit tests and build the Sniffer - test application, use + To build the library, execute all unit tests and build the Sniffer test application, use - 
-      $ scons
-      $ scons all_tests
+ 
+    $ scons
+    $ scons all_tests
+
- in the \c senf directory. This assumes, that you want to build the - library with your default gcc and requires the boost libraries to - be available in the system include paths. If this is not the case, - you can take a look at SConfig.template file. Copy this - file to SConfig and comment out all the variables you - don't want to change (The \e values in the template file are just - arbitrary examples). + in the \c senf directory. This assumes, that you want to build the library with your default gcc + and requires the boost libraries to be available in the system include paths. If this is not the + case, you can take a look at SConfig.template file. Copy this file to SConfig + and comment out all the variables you don't want to change (The \e values in the template file + are just arbitrary examples). */ -/** \page components The SENF modules +/** \page senf_setup Setting up a new project using SENF - The framework is made up of several modular components. When using - the library, it is possible to selectively choose to use only a - subset of the implemented modules. + The most simple way to use SENF for now is to checkout the svn repository and build SENF + yourselves. After you have built SENF, reference your SENF build directory from your build + environment. The most flexible way to do this, is to use a symbolic link to your SENF build. + + Here an example \c SConstruct file for a project using SENF. This script expects SENF to be + found in the %senf sub-directory of the directory, where the \c SConstruct file is + found. This may either be a SENF checkout (if managing your project via subversion, you can use + svn:externals for this) or a symbolic link to your SENF checkout. + + \code + import glob + + env = Environment( + + LIBS = [ 'senf', 'boost_regex', 'boost_iostreams' ], + CXXFLAGS = [ '-Wall', '-Woverloaded-virtual', '-Wno-long-long' ], + + ) + + env.Program( + target = 'mytarget', + source = glob.glob('*.cc'), + ); + \endcode + + When building against a self-built SENF which will probably be in debug mode, the '-DSENF_DEBUG' + option must be added to the compile command. + + The most simple way to build using SENF is to use a very simple SCons helper which automatically + supports debug and final builds, uses SENF either centrally installed or locally built and has + some other nice features. See Building Projects using SENF + for more info and an example for this utility. + + \see \ref senf_components \n + \ref senf_overview + */ + +/** \page senf_components The SENF modules + + The framework is made up of several modular components. When using the library, it is possible + to selectively choose to use only a subset of the implemented modules. + + \see \ref senf_overview + + \section libPPI libPPI: Packet Processing Infrastructure + + The Packet Processing Infrastructure implements a modular framework for implementing packet + oriented network applications. The library provides a large set of pre-defined modules as well + as the necessary helpers to implement application specific processing modules. + + \see libPPI API reference - \see \ref build \n - \ref svnsetup - \section libSocket libSocket: C++ abstraction of the BSD socket API - This library provides a high performance and object oriented - abstraction of the standard socket API. It utilizes a flexible and - extensible policy based design. The library provides predefined - types for the important socket types (UDP and TCP sockets etc) - including raw and packet sockets. \n + This library provides a high performance and object oriented abstraction of the standard socket + API. It utilizes a flexible and extensible policy based design. The library provides predefined + types for the important socket types (UDP and TCP sockets etc) including raw and packet sockets. - \see libSocket API - reference + \see libSocket API reference \section libPackets libPackets: Network packet manipulation - This libarary provides a very flexible infrastructure to - parse, create and otherwise manipulate packetized network - data. Included is a library of several protocol parsers covering - the basic IPv4 and IPv6 network protocols down to the Ethernet - layer. + This library provides a very flexible infrastructure to parse, create and otherwise manipulate + packetized network data. Included is a library of several protocol parsers covering the basic + IPv4 and IPv6 network protocols down to the Ethernet layer. - \see libPackets API - reference + \see libPackets API reference \section libScheduler libScheduler: Asynchronous event handling - The scheduler library provides an object oriented interface to the - standard UNIX \c select type event dispatcher. It is based on the - high performance \c epoll system call. It provides support for - read/write events as well as simple timer based events. + The scheduler library provides an object oriented interface to the standard UNIX \c select type + event dispatcher. It is based on the high performance \c epoll system call. It provides support + for read/write events as well as simple timer based events. - \see libScheduler API - reference + \see libScheduler API reference \section libUtils libUtils: Collection of arbitrary utilities - This library is used be most all of the other modules for - miscellaneous tools and utilities. We have + This library is used be most all of the other modules for miscellaneous tools and utilities. We + have \li Simple functions to manage daemon processes - \li Standard exception classes - \li satcom::lib::intrusive_refcount to simplify the implementation - of classes usable with boost::intrusive_ptr + \li Standard exception classes + \li senf::intrusive_refcount to simplify the implementation of classes usable with + boost::intrusive_ptr \li boost::bind extensions - \li An interface to the \c g++ demangler integrated with type_info - \li Typedefs and rudimentary methods to simplify handling - high-resolution time values + \li An interface to the \c g++ de-mangler integrated with type_info + \li Typedefs and rudimentary methods to simplify handling high-resolution time values - \see libUtils API - reference + \see libUtils API reference \section senfscons SENFSCons, the SENF build environment - SENF relies on SCons (http://www.scons.org) to build. To further - simplify the common tasks, SENF includes a library of custom - routines and builders comprising a very concise build - environment. Included are a number of templates to help - bootstrapping a new project or component. + SENF relies on SCons (http://www.scons.org) to build. To further simplify the common tasks, SENF + includes a library of custom routines and builders comprising a very concise build + environment. Included are a number of templates to help bootstrapping a new project or + component. - \see SENFSCons - reference + \see SENFSCons reference */ -/** \page svnsetup Setting up a new project using SENF - - The preferred way to use SENF in a new project is to rely on - Subversion and make use of the SENFSCons build environment. The - following sections will describe, how this setup works. - - \see \ref build \n - \ref components \n - \ref overview - - \section svnext Setting up the project repository - - The most seamless integration is possible if you rely on - Subversion to manage the new project. Subversion does support - 'external repositories'. This allows to import code from a foreign - repository into the checkout without importing it into your - repository. The code will always stay at the remote repository, - updates are automatically available. - - First setup a new empty repository as described for example in the - Subversion book at http://svnbook.red-bean.com or as mandated by - your site policy. We will call the project 'Foo' and assume, that - the project has been checked out into the 'Foo' directory. - - You now have to decide, which modules you want to use. Every - module resides in it's own subdirectory in the SENF - repository. Instead of directly checking out the code, we will use - \c svn:externals. This will instruct \c svn to auutomatically - check out the needed directories from the BerliOS SENF - repository. Change to the 'Foo' directory and type - - 
-        $ svn propedit svn:externals .
+/** \page senf_overview Introduction to the framework - The default editor (probably VI) will be started with the current - value of the svn:externals property (which will probably be - empty). Now add all the modules you want plus \c satscons and - possibly \c doclib (if you want to build the documentation). You - will almost certainly neeed the \c Utils module, since all other - modules depend on it. + The SENF framework is relatively complex and makes use of advanced features of the C++ + language. To make the most efficient use of the framework, you should have at least a basic + understanding of C++ templates and the standard library concepts. - For example, if you want to use the \c Scheduler and \c Socket - module, the file will look like + The library implementation at places makes heavy use of advanced template techniques and relies + on some very advanced template libraries from Boost. The aim was however for the \e external + interface of the library to be as simple as possible without sacrificing important functionality + or adversely impacting the runtime performance. - 
-        satscons http://svn.berlios.de/svnroot/repos/senf/trunk/satscons
-        Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
-        Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
-        Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket
+ As already mentioned several times, the library relies on Boost (http://www.boost.org) as a + generic library of high quality reusable C++ components. It also makes frequent use of the + standard library. It is designed, to integrate well into both libraries and to use the same + concepts and ideas. - exit the editor and the property will be set. Now run + \section senf_startup Getting starting developing with SENF - 
-        $ svn update
+ To introduce the framework and it's general structure, a simple example application is provided + in the SENF repository in the \c Sniffer module. Peruse this example to get a first look at how + to make use of SENF. - and the code will be checked out into the corresponding - directories. + When building a network Application with SENF, you will use several modules: - \section new_conf Configuring SENFSCons + \li Use the Socket library for network + communication needs. This library includes support for raw and packet sockets to allow low + level network access. + \li Use the Scheduler library to coordinate + the asynchronous event processing. This drastically reduces the number of threads needed in + your application and will greatly enhance the overall responsiveness. + \li To interpret low level network packets, use the Packets library. This library will provide + efficient and convenient access to all protocol fields. It supports parsing as well as + modifying and creating packets. It has default support for the most important Internet + protocols and is highly extensible with new protocols. + \li Go over the Utils library. It contains small + helpers to simplify tasks like daemonization, exception handling, debugging and so on. - To set up the build environment, copy the - satscons/SConstruct.template to Satscons in the - project root. The default setup of this file is to build all - subdirectories (using the \c SConscript files of the - subdirectories). You can add additonal global targets and - configuration parameters here. + The simplest way to get started is: copy the Sniffer application and start to modify it. - If you want to use a non-default compiler or the boost library is - not installed in the system directories, you will have to copy - satscons/SConfig.template to SConfig in the - project root and edit it there. You should \e never add \c SConfig - to the repository since it should only contain local settings - necessary for building on your local system. You should therefore - add \c SConfig to the list of files ignored by Subversion in the - project root. In the project root execute + \see Examples \n + \ref senf_components \n + \ref senf_setup - 
-      $ svn propedit svn:ignore .
+ \section senf_conventions Coding Conventions + + Here we have laid down the coding conventions used throughout the SENF framework. Please ad here + to these conventions when changing or adding code. If you use emacs, you can use the C++ IDE for + emacs from http://g0dil.de which greatly simplifies following these conventions. - and add \c SConfig as a new line to the property. + \subsection senf_conventions_file_naming File Naming - \section new_build Building the project + Files should be named according to the main class they define. A single header file should + define only one main class. Exceptions to this rule are OK. - You should now be able to build your project using + \par Rationale: + This simplifies finding the implementation/header for a given class and also reduces the + size of each single file. + + The implementation is divided into a number of different files: - 
-      $ scons
+ - If you have not changed the \c SConstruct file, this will build - all modules you have importet into your project. To build and - execute the unit tests, use + - 
-      $ scons all_tests
+ - you can also build only a subdirectory by changing to it and - running - - 
-      $ scons -u [target]
+ - \see SENFSCons reference \n - SCons documentation \n - Subversion online book \n - Subversion Homepage - */ + -/** \page overview Introduction to the framework - - The SENF framework is relatively complex and makes use of advanced - features of the C++ language. To make the most efficient use of - the framework, you should have at least a basic understanding of - C++ templates and the standard library concepts. - - The library implementation at places makes heavy use of advanced - template techniques and relies on some very advanced template - libraries from Boost. The aim was however for the \e external - interface of the library to be as simple as possible without - sacrificing important functionality or adversely impacting the - runtime performance. - - As already mentioned several times, the library relies on Boost - (http://www.boost.org) as a generic library of high quality - reusable C++ components. It also makes frequent use of the - standard library. It is designed, to integrate well into both - libraries and to use the same concepts and ideas. - - \section startup Getting starting developing with SENF - - To introduce the framework and it's general structure, a simple - example application is provided in the SENF repository in the \c - Sniffer module. Peruse this example to get a first look at how to - make use of SENF. - - When building a network Application with SENF, you will use - several modules: + + + - \li Use the Socket - library for network communication needs. This library - includes support for raw and packet sockets to allow low level - network access. - \li Use the Scheduler - library to coordinate the asynchronous event - processing. This drastically reduces the number of threads - needed in your application and will greatly enhance the overall - responsiveness. - \li To interpret low level network packets, use the Packets - library. This library will provide efficient and - convenient access to all protocol fields. It supports parsing as - well as modifying and creating packets. It has default support - for the most important TCP protocols and is highly extensible - with new protocols. - \li Go over the Utils - library. It contains small helpers to - simplify tasks like daemonization, exception handling, - debugging and so on. - - The simplest way to get started is: copy the Sniffer application - and start to modify it. - - \see \ref example \n - \ref components \n - \ref svnsetup \n - \ref build + + +
\c .hC public header
\c .hhC++ public header
\c .ihC++ internal header used only by the implementation. This header will + probably be included indirectly by the public header but is not meant to be perused by the + library user
\c .cC implementation
\c .ccC++ implementation of non-inline non-template functions and + members
\c .ctC++ implementation of non-inline template functions and members
\c .cciC++ implementation of inline non-template functions and + members
\c .ctiC++ implementation of inline template functions and members
\c .mppSpecial include file used for external iteration by the + Boost.Preprocessor library
+ + \par Rationale: + There are two part's to this: First, separating the implementation of inlines and templates + out of the header file makes the header file much easier to read. This is important, since + the header file will be used as a reference by the developers. + \par + Separating inline from non-inline members is used together with the \c prefix_ convention + below to ensure the correct placement of inline vs non-inline members in the source + code. The C++ language requires, that inline members must be included into \e every + compilation unit, non-inline members however must be included \e only in one compilation + unit. Placing the inline members into a separate file allows to automate this: Simply moving + an implementation from one of the inline files into one of the non-inline files will change + the type of implementation accordingly. + + \subsection senf_conventions_type_naming Type Naming + + SENF prefers the use of the CapitalziedLettersToSeparateWords convention for class names. In + this case, class names must start with a capital letter. There are some exceptions to this rule: + Types which define new basic data types to be used like other built-in types may be named using + lowercase letters plus underscores. Also, if a type or class is directly related to some other + library (STL or Boost) which uses the underscore convention, it might be more sensible to follow + this convention. This is open to debate. + + \par Rationale: + Naming types with capital letters nicely gives a visual clue, that a symbol is a type + name. This can also be used by the editor to highlight type names correctly. Additionally, + this convention is compact and does not add additional or repeated overhead. + + \subsection senf_conventions_impl Implementation + + Only in very few places, SENF allows the use of inline implementations (not to be confused with + inline functions). An \e implementation is inline, if it is written directly into the class + definition in the header file. Again there are exceptions to this rule but they are very few: + \li When defining simple exception classes, the 'what()' member may be defined inline if it + returns a string constant. + \li It may be OK to use inline implementations for one-line implementations in internal + headers. + \li The Packet library allows inline implementations for the definition of parsers since doing + so outside the declaration just gets to verbose and parsers definitions are quite length but + very simple and straight forward. + + \par Rationale: + Implementing members inline inside the class declaration makes the declaration much harder + to read. Since the declaration in the header file will be used as a reference by the + developer, the header files should be as readable as possible. + + Every function or method implementation in one of the implementation files must \e always be + prefixed with \c prefix_. This symbol is defined at the beginning of the file and undefined at + the end. The symbol must be defined to be \c inline in the \c .cti and \c .cci files and must be + defined empty in the \c .cc and \c .ct files. + + \par Rationale: + Together with splitting inlines and non-inlines into separate files, this allows to + automatically include the inline definitions at the right places. See above. + + Private data members are named with a trailing underscore character. + + \par Rationale: + This helps distinguishing local variables from parameter names. The trailing underscore + does not interfere with other naming conventions and is allowed by the standard (underscore + at the beginning of the name are problematic since some classes of names beginning with an + underscore are reserved for the standard library implementation) */ +// :vim:textwidth=100 // Local Variables: // mode: c++ +// fill-column: 100 +// c-file-style: "senf" +// indent-tabs-mode: nil +// ispell-local-dictionary: "american" +// compile-command: "scons doc" // mode: flyspell // mode: auto-fill -// ispell-local-dictionary: "american" // End: -