First version of overview documentation completed

Doxyfile

@@ -72,7 +72,7 @@ RECURSIVE              = NO
 EXCLUDE                = doc
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = .*
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = Sniffer
 EXAMPLE_PATTERNS       = 
 EXAMPLE_RECURSIVE      = NO
 IMAGE_PATH             = 

Example.dox

+/** \page example Sniffer: A simple example application
+
+    \dontinclude Sniffer.cc
+
+    The Sniffer application is a simple command line network sniffer
+    like \c tcpdump or \c tethereal. The application uses a packet
+    socket to read Ethernet packets from the \c eth0 interface and
+    dumps the parsed packets out to the standard output.
+
+    We will be looking at \c Sniffer.cc in the \c Sniffer
+    directory. We start by including the necessary headers
+
+    \skip // Custom includes
+    \until Ethernet
+
+    (The additional includes are part of a short-time fix which will
+    be removed as soon as possible). The example application now
+    contains a helper routine to produce a packet hexdump. We will
+    skip this routine here and go directly to the \c main function
+    
+    \skip main
+    \until try
+
+    We catch all exceptions in a \c try block. This is good for a
+    deliverable binary. When debugging the application, it might be
+    better to let the exception \c abort the execution so you can get
+    a backtrace of the exception origin in the debugger.
+
+    We now create a packet socket and bind it to the \c eth0
+    interface. By uncommenting the last line, you may switch the
+    interface into promiscuous mode.
+
+    \until //
+
+    We will now read packets from the socket forever, that is until
+    the user hits Ctrl-C
+
+    \skip while
+    \until read
+    
+    The next step is, to parse the data read from the socket as an
+    Ethernet packet
+
+    \until ;
+    
+    Lets digest this line step by step: We declare a variable named \c
+    packet as a smart pointer to an \c EthernetPacket instance. \c ptr
+    is a typedef member of all Packet classes for the corresponding
+    smart pointer type. We then initialize this pointer with a call to
+    the static \c create member of the \c Packet class. This member
+    takes the type of Packet to parse as a template argument. We pass
+    \c EthernetPacket here. The function takes an iterator range as an
+    argument, and we pass it the complete packet just read by
+    giving the range \c begin() to \c end() of our just read \c data
+    string.
+
+    The next step is, to write out the packet to the standard output
+
+    \until \n\n
+
+    The \c dump call will write out a complete representation of the
+    parsed packet data. The Packet library will \e not try to
+    interpret payload data as long as no exact indication of the
+    payload type is available (example: A UDP Payload is not parsed
+    further unless you explicitly tell the library, how to parse it).
+    Tools like \c tethereal guess the payload type by checking port
+    numbers and the payload data, however this is not advisable for a
+    general purpose packet library.
+
+    The next line, \c hexdump, will write out the \e last packet
+    component. Packets are managed as a chain of headers. The last
+    header is normally a \c DataPacket holding the payload data.
+
+    That's it. We finish of by catching the exception and giving as
+    much detail as possible if an exception is caught
+
+    \until ;
+    \until }
+    \until }
+
+    The \c prettyName function from the \c Utils library is used, to
+    get a nice, printable representation of the \e dynamic type of the
+    exception instance. It is an interface to the g++ demangler. This
+    is necessary since the \c name member of the C++ \c type_info
+    instance is a mangled name in C++.
+
+    That's it. This is all, that's necessary to read and parse raw
+    network packets using the SENF library. To try out the example
+    application, check out the library, go to the \c Sniffer directory
+    and execute
+
+    <pre class="fragment">
+      # scons -u
+      # ./Sniffer</pre>
+
+    \see \ref components \n
+         \ref build \n
+         <a href="../../Socket/doc/html/index.html"><b>libSocket API reference</b></a> \n
+         <a href="../../Packets/doc/html/index.html"><b>libPackets API reference</b></a> \n
+         <a href="../../Utils/doc/html/index.html"><b>libUtils API reference</b></a>
+ */
+
+
+// Local Variables:
+// mode: c++
+// mode: flyspell
+// mode: auto-fill
+// ispell-local-dictionary: "american"
+// End:
+

Mainpage.dox

@@ -48,7 +48,8 @@
 
     \see \ref build \n
          \ref components \n
-         \ref svnsetup
+         \ref svnsetup \n
+         \ref overview
 
     \section Preliminaries
 
@@ -71,10 +72,6 @@
     which relies on \c epoll)
     
     \todo
-    \li Preliminaries: SVN access, Dependencies
-    \li Building the library -> Configuration
-    \li Setting up a project using this library (svn:externals)
-    \li Library components
     \li coding standards and patterns
  */
 
@@ -195,12 +192,16 @@
     reference</a>
  */
 
-/** \page svnsetup Setting up a new project using SENF via SVN
+/** \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
@@ -249,34 +250,121 @@
     and the code will be checked out into the corresponding
     directories. 
 
-    \todo \li Configuring and building -> reference to the SENFSCons
-              dok
- */
+    \section new_conf Configuring SENFSCons
+
+    To set up the build environment, copy the
+    <tt>satscons/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>satscons/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
 
-/** \page example Sniffer: A simple Example application
+    <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="../../satscons/doc/html/index.html"><b>SENFSCons reference</b></a> \n
+         <a href="http://www.scons.org/documentation.php"><b><i>SCons documentation</i></b></a> \n
+         <a href="http://svnbook.red-bean.com"><b><i>Subversion online book</i></b></a> \n
+         <a href="http://subversion.tigris.org"><b><i>Subversion Homepage</i></b></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"><b>Socket
+      	library</b></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"><b>Scheduler
+      	library</b></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"><b>Packets
+      	library</b></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"><b>Utils
+      	library</b></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
  */
 
-    \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.
-   
 
 // Local Variables:
 // mode: c++
+// mode: flyspell
+// mode: auto-fill
+// ispell-local-dictionary: "american"
 // End:
 

Sniffer/Sniffer.cc

@@ -86,7 +86,7 @@ namespace {
     }
 }
 
-int main (int argc, char * argv[])
+int main (int argc, char const * argv[])
 {
     try {
         satcom::lib::PacketSocketHandle sock;
@@ -104,7 +104,7 @@ int main (int argc, char * argv[])
             std::cout << "\n\n";
         }
     }
-    catch (std::exception & ex) {
+    catch (std::exception const & ex) {
         std::cerr << satcom::lib::prettyName(typeid(ex)) << ": " << ex.what() << "\n";
     }
 }

doclib/senf.css

@@ -5,8 +5,8 @@ body {
 }
 
 #head {
-	height: 63px;
-	border-top: 4px solid #DECD40;
+	height: 62px;
+	border-top: 5px solid #DECD40;
 	border-bottom: 1px solid #AF9D00;
 	background: url(logo-head.png) top left no-repeat;
 	background-color: #EDE497;
@@ -15,7 +15,7 @@ body {
 #head h1 {
 	margin: 0 0 0 100px;
         padding: 6px 0 0 0;
-	height: 34px;
+	height: 33px;
         background-color: #DECD40;
 	border-bottom: 1px solid #AF9D00;
         font-size: 22px;

satscons/SConstruct.template

@@ -6,7 +6,6 @@ import SatSCons
 
 SatSCons.UseBoost();
 SatSCons.UseSTLPort();
-SatSCons.UseDoxygen();
 env = SatSCons.MakeEnvironment();
 
 env.Append(