\section Goals
- The main goals where (in no particular order)
+ The main goals of this library are (in no particular order):
\li modular framework design
\li utilizing the power of modern C++
\li extensible design
\li concise interface
- \section Components
+ \section start Getting started
+
+ To get started using this library, begin by checking out the code
+ from the <a
+ href="http://developer.berlios.de/svn/?group_id=7489">BerliOS SVN
+ repository</a>. You may find help on using the library at '\ref
+ usage'. If you are interested in SENF, feel free to subscribe
+ to the <a
+ href="http://developer.berlios.de/mail/?group_id=7489">SENF
+ mailing lists</a>.
+
+ \see \ref usage\n
+ \ref example\n
+ <a class="ext" href="http://developer.berlios.de/projects/senf">The BerliOS project page</a>\n
+ <a class="ext" href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">The SENF Wiki at BerliOS</a>
+*/
+
+/** \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
+
+ <pre class="fragment">
+ $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf</pre>
+
+ 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
+
+ <pre class="fragment">
+ $ scons
+ $ scons all_tests</pre>
+
+ 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 <tt>SConfig.template</tt> file. Copy this
+ file to <tt>SConfig</tt> 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. The modules are
+ subset of the implemented modules.
+
+ \see \ref build \n
+ \ref svnsetup
- \subsection libSocket libSocket: C++ abstraction of the BSD socket API
+ \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
\see <a href="../../Socket/doc/html/index.html">libSocket API
reference</a>
- \subsection libPackets libPackets: Network packet manipulation
+ \section libPackets libPackets: Network packet manipulation
This libarary provides a very flexible infrastructure to
parse, create and otherwise manipulate packetized network
\see <a href="../../Packets/doc/html/index.html">libPackets API
reference</a>
- \subsection libScheduler libScheduler: Asynchronous event handling
+ \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
\see <a href="../../Scheduler/doc/html/index.html">libScheduler API
reference</a>
- \subsection libUtils libUtils: Collection of arbitrary utilities
+ \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 satcom::lib::intrusive_refcount to simplify the implementation
+ \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
\see <a href="../../Utils/doc/html/index.html">libUtils API
reference</a>
- \section code Coding practices
-
- The library heavily depends on the features of modern C++. As
- such, it depends on a fairly recent and standards compliant C++
- compiler (the Library is developed using \c gcc with Version at
- least 3.4). To meet the above defined goals, the library makes
- quite heavy use of advanced templating techniques, so
- understanding the implementation will require expertise in the
- intricacies of C++ templates. However, it was deemed important to
- keep the \e visible Interface of the Library as clean and simple
- as possible without sacrificing the projects design goals.
-
- The library heavily depends on the \e Boost libraries (see
- http://www.boost.org). The Boost libraries are an ever growing
- collection of highest quality reusable C++ components. They are
- designed with standardization in mind. Many of the libraries are
- already in queue to be part of the next generation C++ standard.
-
- \section Dependencies
-
- \li A standards compliant, modern C++ compiler. The library as
- such is developed under Linux using \c gcc with Version
- above 3.4
- \li The Boost libraries from http://www.boost.org
- \li The SCons build tool (see http://www.scons.org)
- \li Linux. The library only makes use of the POSIX API's, however
- it has not been tested beyond Linux, so if you are somewhere
- else, you are on your own. However, we will greatly appreciate
- feedback and patches for other platforms.
-*/
+ \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 <a href="../../senfscons/doc/html/index.html">SENFSCons
+ reference</a>
+ */
+
+/** \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
+
+ <pre class="fragment">
+ $ svn propedit svn:externals .</pre>
+
+ 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
+
+ <pre class="fragment">
+ 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</pre>
+
+ exit the editor and the property will be set. Now run
+
+ <pre class="fragment">
+ $ svn update</pre>
+
+ and the code will be checked out into the corresponding
+ directories.
+
+ \section new_conf Configuring SENFSCons
+
+ To set up the build environment, copy the
+ <tt>senfscons/SConstruct.template</tt> to <tt>Satscons</tt> 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
+ <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> 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
+
+ <pre class="fragment">
+ $ svn propedit svn:ignore .</pre>
+
+ 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
+
+ <pre class="fragment">
+ $ scons</pre>
+
+ 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
+
+ <pre class="fragment">
+ $ scons all_tests</pre>
+
+ you can also build only a subdirectory by changing to it and
+ running
+
+ <pre class="fragment">
+ $ scons -u [target]</pre>
+
+ \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
+ <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
+ <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
+ <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
+ */
+
+/** \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 <a href="../../Socket/doc/html/index.html">Socket
+ library</a> for network communication needs. This library
+ includes support for raw and packet sockets to allow low level
+ network access.
+ \li Use the <a
+ href="../../Scheduler/doc/html/index.html">Scheduler
+ library</a> 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 <a
+ href="../../Packets/doc/html/index.html">Packets
+ library</a>. 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 <a href="../../Utils/doc/html/index.html">Utils
+ library</a>. 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
+ */
\f
// Local Variables:
// mode: c++
+// mode: flyspell
+// mode: auto-fill
+// ispell-local-dictionary: "american"
// End:
+
projects / senf.git / blobdiff