Console: Complete 'Variable' command implementation

[senf.git] / senfscons / Mainpage.dox

diff --git a/senfscons/Mainpage.dox b/senfscons/Mainpage.dox
index fb72ad1..5c81984 100644 (file)
--- a/senfscons/Mainpage.dox
+++ b/senfscons/Mainpage.dox
@@ -1,6 +1,8 @@
+// $Id$
+//
 // Copyright (C) 2007
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
 //     Stefan Bund <g0dil@berlios.de>
 //
 // This program is free software; you can redistribute it and/or modify
@@ -25,13 +27,68 @@ namespace senfscons {
     The Senf Build Environment is based on the <a href="http://www.scons.org">SCons</a> software
     construction tool. SCons is a <a href="http://www.python.org">python</a> based replacement for
     \c make. SENFScons consists of several SCons builders as well as some global configuration and
-    build utilities. SEBFScons tightly integrates the <a
+    build utilities. SENFScons tightly integrates the <a
     href="http://www.boost.org/libs/test/doc/index.html">Boost.Test</a> unit testing framework. It
     also incorporates a very flexible infrastructure to build software documentation using <a
     href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a>. This infrastructure uses quite a bit
     of pre- and postprocessing (which is integrated with the provided Doxygen builder) to fix some
     doxygen problems and generate a (IMHO) more readable layout.
 
+    \section senfutil 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:
+    \code
+    import sys
+    sys.path.extend(('senf/senfscons','/usr/lib/senf/senfscons'))
+    import os.path, glob, senfutil
+
+    env = Environment()
+
+    senfutil.SetupForSENF( env )
+
+    env.Append(
+
+        LIBS            = [ ],
+        CXXFLAGS        = [ '-Wall', '-Woverloaded-virtual' ],
+        LINKFLAGS       = [ ],
+
+        CXXFLAGS_debug  = [ ],
+        LINKFLAGS_debug = [ ],
+        LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
+
+        CXXFLAGS_final  = [ '-O3' ],
+        LINKFLAGS_final = [ ],
+        LOGLEVELS_final = [ ],
+
+        SENF_BUILDOPTS  = [ ],
+
+    )
+
+    env.Default(
+        env.Program( target = 'udpforward',
+                     source = glob.glob('*.cc') )
+    )
+
+    env.Clean(DEFAULT_TARGETS, [ 'udpforward.log', 'udpforward.pid' ])
+    \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
+    <tt>senfutil.SetupForSENF( env )</tt>.
+
+    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 globaly installed SENF. A
+    locally installed SENF is automatically recompiled if needed. Parallel building is also
+    supported.
+
+    This script automatically supports the \c final and \c LOGLEVELS command line parameters. The
+    LOGLEVELS parameter uses a much more readable syntax than SENF_LOG_CONF:
+    <pre>
+    $ scons -j2 final=1 \
+          LOGLEVELS='senf::log::Debug||IMPORTANT myapp::Transactions|mytrans::Area|VERBOSE'
+    </pre>
+
     \section layout The Project Layout
 
     A Project using the SENFSCons infrastructure will always use a consistent directory layout. The
@@ -151,9 +208,14 @@ namespace senfscons {
     To configure the build environment to the local environment, a \c SConfig file may be created in
     the projects root directory. The supported parameters are
 
-    <dl><dt>\c CXX</dt><dd>C++ compiler to use</dd>
-    <dt>\c EXTRA_DEFINES</dt><dd>preprocessor symbols to be defined locally</dd>
-    <dt>\c EXTRA_LIBS</dt><dd>additional libraries needed for a local build</dd></dl>
+    <dl>
+        <dt>\c CXX</dt>
+            <dd>C++ compiler to use</dd>
+        <dt>\c EXTRA_DEFINES</dt>
+            <dd>preprocessor symbols to be defined locally</dd>
+        <dt>\c EXTRA_LIBS</dt>
+            <dd>additional libraries needed for a local build</dd>
+    </dl>
 
     Additionally, the \ref use define additional configuration variables which may be set here.
  */