X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=doclib%2FMainpage.dox;fp=doclib%2FMainpage.dox;h=2fd5529deb153fe22e9550932616a11267e10ca1;hb=84bd150c667e693c7ba6c31819b3f155f53e514a;hp=0000000000000000000000000000000000000000;hpb=4b94735961fc9474411a1ca200c3a00f744ec3f1;p=senf.git diff --git a/doclib/Mainpage.dox b/doclib/Mainpage.dox new file mode 100644 index 0000000..2fd5529 --- /dev/null +++ b/doclib/Mainpage.dox @@ -0,0 +1,531 @@ +// $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. + + \section Goals + + The main goals of this library are (in no particular order): + + \li modular framework design + \li utilizing the power of modern C++ + \li very low overhead for frequently called members + \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 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 + + \section senfutil_overview Building Projects using SENF + + When building projects using senf, SENFSCons has a very simple helper module \ref senfutil to + make the building of libraries utilizing senf simpler. + + \see \ref senf_senfutil +*/ + +/** \page senf_senfutil SENF SCons build utility (senfutil.py) + + \autotoc + + The \c senfutil utility for SCons helps setting up a project to compile against SENF: + + \li \c senfutil adds all necessary libraries to link against + \li \c senfutil will set necessary compile options. + \li \c senfutil supports normal, debug and final project build options + \li \c senfutil allows specifying variables on the scons command line + \li \c senfutil supports more readable compile-time SENF loglevel configuration + + Using the utility is quite simple + + \code + import sys + sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons')) + import glob, senfutil + + env = Environment() + senfutil.SetupForSENF(env) + # senfutil.DefaultOptions(env) + + # Set or change SCons environment variables with env.Append, env.Replace or env.SetDefault + env.Append( + CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ], + CXXFLAGS_final = [ '-O2' ], + CXXFLAGS_normal = [ '-O0', '-g' ], + CXXFLAGS_debug = [ '$CXXFLAGS_normal' ], + + LINKFLAGS_normal = [ '-Wl,-S' ], + + LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ], + ) + + env.Default( + env.Program( target='udpforward', source=glob.glob('*.cc') ) + ) + \endcode + + This example builds a simple binary from a number of source files (all '.cc' files). It links + against the SENF library and automatically sets all the correct compiler options using + senfutil.SetupForSENF( env ). + + This script automatically uses a SENF installation either symlinked or imported into the current + project in directory 'senf' or, if this directory does not exist, a globally installed SENF. + + \section senf_senfutil_options Build options + + \c senfutil supports the debug=1 or final=1 build options. These parameters + select one of the build configurations 'debug', 'normal' or 'final'. The following variables are + supported each with separate values for all three configurations: + + \li \c CXXFLAGS + \li \c CPPDEFINES + \li \c LINKFLAGS + \li \c LOGLEVELS + + \c senfutil will detect the type of SENF library used (final or not) and set the correct compile + options. + + \section senf_senfutil_loglevels Specifying compile-time loglevels + + To simplify specifying the compile-time loglevel configuration, the build variable \c LOGLEVELS + (and it's build configuration specific variants) may be set. This variable will be parsed and + converted into the correct \c SENF_LOG_CONF definition. The \c LOGLEVELS Syntax is + + \par "" \e optional_stream \c | \e optional_area | \e level + + where \e optional_stream and \e optional_area are optional fully scoped C++ names (e.g. \c + senf::log::Debug) and \e level is the loglevel. There must be \e no whitespace in a single + specification, multiple specifications are either specified using an array or separated with + whitespace. + + \section senf_senfutil_default Default options + + In the example above, all compile options are set manually. To specify the default customary + compile options for SENF programs, \c senfutil.DefaultOptions(env) is provided. This function is + identical to: + + \code + senfutil.DefaultOptions(env) => + env.Append( + CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ], + CXXFLAGS_final = [ '-O2' ], + CXXFLAGS_normal = [ '-O0', '-g' ], + CXXFLAGS_debug = [ '$CXXFLAGS_normal' ], + + LINKFLAGS_normal = [ '-Wl,-S' ], + ) + \endcode + + Thus above example can be simplified to + \code + import sys + sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons')) + import glob, senfutil + + env = Environment() + senfutil.SetupForSENF(env) + senfutil.DefaultOptions(env) + + env.Append( LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ] ) + + env.Default( + env.Program( target = 'udpforward', source = glob.glob('*.cc') ) + ) + \endcode + + \section senf_senfutil_arguments 'scons' Command line arguments + + \c senfutil automatically parses SCons command line arguments into the SCons build + environment. This allows specifying any parameter on the command line: + 
+    $ scons CXX=myg++ CXXFLAGS+=-mtune=geode
+
+ You may either set variables unconditionally using '=' or append values to the end of a list + using '+='. + */ + +/** \page senf_usage Using the SENF 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 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 senf_build \n + \ref senf_setup \n + \ref senf_components \n + \ref senf_overview + + \section senf_preliminaries Preliminaries + + 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) + \li The SCons build tool (http://www.scons.org) + + If you want to build the documentation, you additionally need + + \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, + 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 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. + + \see \ref senf_setup \n + \ref senf_components \n + \ref senf_overview + + \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 + + 
+    $ 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 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 senf_compile Building + + To build the library, execute all unit tests and build the Sniffer test application, use + + 
+    $ 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). + */ + +/** \page senf_setup Setting up a new project using SENF + + 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 + + \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. + + \see libSocket API reference + + \section libPackets libPackets: Network packet manipulation + + 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 + + \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. + + \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 + + \li Simple functions to manage daemon processes + \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++ de-mangler integrated with type_info + \li Typedefs and rudimentary methods to simplify handling high-resolution time values + + \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. + + \see SENFSCons reference + */ + +/** \page senf_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 senf_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 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. + + The simplest way to get started is: copy the Sniffer application and start to modify it. + + \see Examples \n + \ref senf_components \n + \ref senf_setup + + \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. + + \subsection senf_conventions_file_naming File Naming + + 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. + + \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: + + + + + + + + + + + + + + + + + +
\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 +// End: