X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Mainpage.dox;h=51f251561ed585a69b87212cd835aea8e5fad3bd;hb=331547d2a137f796eb5fcb390502aece3e01bb16;hp=d37ba40d6d218b45b3cd51b3819264252caec621;hpb=558583531d5042ece06b19fcd10132d2d1bc5ad0;p=senf.git
diff --git a/Mainpage.dox b/Mainpage.dox
index d37ba40..51f2515 100644
--- a/Mainpage.dox
+++ b/Mainpage.dox
@@ -1,9 +1,367 @@
/** \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
+ 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
+*/
+
+/** \page 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.
+
+ 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.
+
+ \see \ref build \n
+ \ref components \n
+ \ref svnsetup \n
+ \ref overview
+
+ \section Preliminaries
+
+ Before starting the devlopment, 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/)
+
+
+ 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)
+ */
+
+/** \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
+ 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 components \n
+ \ref svnsetup
+
+ \section 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 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.
+
+ \section 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 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 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
+
+ \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.
+
+ \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++ demangler 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 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 .
+
+ 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 senfscons 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.
+
+ For example, if you want to use the \c Scheduler and \c Socket
+ module, the file will look like
+
+
+ senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
+ 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
+
+ exit the editor and the property will be set. Now run
+
+
+ $ svn update
+
+ and the code will be checked out into the corresponding
+ directories.
+
+ \section new_conf Configuring SENFSCons
+
+ To set up the build environment, copy the
+ senfscons/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.
+
+ 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
+ senfscons/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
+
+
+ $ svn propedit svn:ignore .
+
+ and add \c SConfig as a new line to the property.
+
+ \section new_build Building the project
+
+ You should now be able to build your project using
+
+
+ $ 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
+ */
// Local Variables:
// mode: c++
+// mode: flyspell
+// mode: auto-fill
+// ispell-local-dictionary: "american"
// End:
+