From: g0dil Date: Thu, 14 Dec 2006 17:33:31 +0000 (+0000) Subject: Documentation updates X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=8dfae1a53657036ad5dedadc77b91d2841266ba8;p=senf.git Documentation updates git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@163 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Doxyfile b/Doxyfile index d928062..0bbcdbb 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1,5 +1,5 @@ PROJECT_NAME = Overview -PROJECT_NUMBER = "Version 0.0.1" +PROJECT_NUMBER = OUTPUT_DIRECTORY = doc CREATE_SUBDIRS = NO @@ -71,7 +71,7 @@ FILE_PATTERNS = *.dox RECURSIVE = NO EXCLUDE = doc EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = *~ .#* +EXCLUDE_PATTERNS = .* EXAMPLE_PATH = EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO diff --git a/Mainpage.dox b/Mainpage.dox index 216699d..02c250b 100644 --- a/Mainpage.dox +++ b/Mainpage.dox @@ -9,7 +9,7 @@ \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++ @@ -17,13 +17,124 @@ \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 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 + + \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) + + \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 + */ + +/** \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. 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 @@ -34,7 +145,7 @@ \see libSocket API reference - \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 @@ -45,7 +156,7 @@ \see libPackets API reference - \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 @@ -55,7 +166,7 @@ \see libScheduler API reference - \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 @@ -72,6 +183,80 @@ \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 via SVN + + 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. + + \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 satscons 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 + + 
+        satscons http://svn.berlios.de/svnroot/repos/senf/trunk/satscons
+        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. + + \todo \li Configuring and building -> reference to the SENFSCons + dok + */ + +/** \page example Sniffer: A simple Example application + + */ + \section code Coding practices The library heavily depends on the features of modern C++. As @@ -90,20 +275,8 @@ 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. -*/ - // Local Variables: // mode: c++ // End: + diff --git a/SConstruct b/SConstruct index 5271e8d..0dd5710 100644 --- a/SConstruct +++ b/SConstruct @@ -8,9 +8,7 @@ import SatSCons SatSCons.UseBoost() SatSCons.UseSTLPort() -SatSCons.UseDoxygen() env = SatSCons.MakeEnvironment() -env.Tool('Dia2Png', [ 'satscons' ]) env.Append( CPPPATH = [ '#' ], diff --git a/doclib/Doxyfile.global b/doclib/Doxyfile.global index f0453ea..54d2c9b 100644 --- a/doclib/Doxyfile.global +++ b/doclib/Doxyfile.global @@ -83,7 +83,7 @@ FILE_PATTERNS = *.c *.cc *.cci *.ct *.cti *.h *.hh *.ih *.mmc *.dox RECURSIVE = NO EXCLUDE = doc EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = *.test.cc *~ .#* +EXCLUDE_PATTERNS = *.test.cc *~ .* EXAMPLE_PATH = EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO diff --git a/doclib/doxy-footer.html b/doclib/doxy-footer.html index a1f0ee4..db391aa 100644 --- a/doclib/doxy-footer.html +++ b/doclib/doxy-footer.html @@ -1 +1,11 @@ - +
+ + + + diff --git a/doclib/doxy-header-overview.html b/doclib/doxy-header-overview.html index 54a5236..f5746e3 100644 --- a/doclib/doxy-header-overview.html +++ b/doclib/doxy-header-overview.html @@ -12,18 +12,20 @@ div.tabs ul li.$projectname a { background-color: #EDE497; } -
-
- +
diff --git a/doclib/doxy-header.html b/doclib/doxy-header.html index d156d1c..c3bfb92 100644 --- a/doclib/doxy-header.html +++ b/doclib/doxy-header.html @@ -12,18 +12,20 @@ div.tabs ul li.$projectname a { background-color: #EDE497; } -
-
- +
diff --git a/doclib/senf.css b/doclib/senf.css index da9d09b..386ab21 100644 --- a/doclib/senf.css +++ b/doclib/senf.css @@ -30,15 +30,20 @@ body { padding: 4px 0 0 0; height: 18px; background-color: #EDE497; + color: #726921; font-size: 13px; font-weight: normal; - color: #726921; white-space: nowrap; } -#content { - /* Non-0 top padding to fix margin inhertance from first non-float elt */ - padding: 1px 10px 10px 142px; +#content1 { + padding: 0 10px 10px 142px; + border-bottom: 1px solid #AF9D00; +} + +#content2 { + /* need non-zero top padding here to prevent margin propagation */ + padding: 10px 0 0 0; max-width: 60em; } @@ -48,7 +53,7 @@ div.tabs { clear: left; background-color: #FDF7C3; border: 1px solid #AF9D00; - margin: 10px 0 0 -132px; + margin: 0 0 10px -132px; width: 120px; overflow: hidden; } @@ -101,3 +106,26 @@ div.qindex { padding: 2px; line-height: 140%; } + +#footer { + clear: both; + padding: 4px 10px 4px 142px; + color: #726921; + white-space: nowrap; + text-align: right; + max-width: 60em; +} + +#footer span { + font-size: 10px; +} + +#footer a, #footer a:active, #footer a:visited { + color: #726921; + text-decoration: none; +} + +#footer a:hover { + background-color: inherit; + text-decoration: underline; +} \ No newline at end of file diff --git a/satscons/Doxyfile b/satscons/Doxyfile new file mode 100644 index 0000000..2f7e474 --- /dev/null +++ b/satscons/Doxyfile @@ -0,0 +1,4 @@ +PROJECT_NAME = SENFSCons +PROJECT_NUMBER = "Version 0.0.1" + +@INCLUDE = ../doclib/Doxyfile.global \ No newline at end of file diff --git a/satscons/Doxygen.py b/satscons/Doxygen.py index c934dc0..8ec61fc 100644 --- a/satscons/Doxygen.py +++ b/satscons/Doxygen.py @@ -81,12 +81,11 @@ def DoxyfileParse(file_contents, dir, data = None): # compress lists of len 1 into single strings for (k, v) in data.items(): - if k == "@INCLUDE" : continue if len(v) == 0: data.pop(k) # items in the following list will be kept as lists and not converted to strings - if k in ["INPUT", "FILE_PATTERNS", "EXCLUDE_PATTERNS"]: + if k in ["INPUT", "FILE_PATTERNS", "EXCLUDE_PATTERNS", "@INCLUDE", "TAGFILES"]: continue if len(v) == 1: @@ -101,6 +100,10 @@ def DoxySourceScan(node, env, path): Doxygen Doxyfile source scanner. This should scan the Doxygen file and add any files used to generate docs to the list of source files. """ + dep_add_keys = [ + '@INCLUDE', 'HTML_HEADER', 'HTML_FOOTER', 'TAGFILES' + ] + default_file_patterns = [ '*.c', '*.cc', '*.cxx', '*.cpp', '*.c++', '*.java', '*.ii', '*.ixx', '*.ipp', '*.i++', '*.inl', '*.h', '*.hh ', '*.hxx', '*.hpp', '*.h++', @@ -112,45 +115,34 @@ def DoxySourceScan(node, env, path): '*~', ] - sources = [] - - data = DoxyfileParse(node.get_contents(), str(node.dir)) - - if data.get("RECURSIVE", "NO") == "YES": - recursive = True - else: - recursive = False - - file_patterns = data.get("FILE_PATTERNS", default_file_patterns) + sources = [] + basedir = str(node.dir) + data = DoxyfileParse(node.get_contents(), basedir) + recursive = ( data.get("RECURSIVE", "NO") == "YES" ) + file_patterns = data.get("FILE_PATTERNS", default_file_patterns) exclude_patterns = data.get("EXCLUDE_PATTERNS", default_exclude_patterns) for i in data.get("INPUT", [ "." ]): - input = os.path.normpath(os.path.join(str(node.dir),i)) + input = os.path.normpath(os.path.join(basedir,i)) if os.path.isfile(input): sources.append(input) elif os.path.isdir(input): - if recursive: - entries = os.walk(input) - else: - entries = [ (input, [], os.listdir(input)) ] + if recursive : entries = os.walk(input) + else : entries = [ (input, [], os.listdir(input)) ] for root, dirs, files in entries: for f in files: - filename = os.path.join(root, f) - - pattern_check = reduce(lambda x, y: x or bool(fnmatch(filename, y)), file_patterns, False) - exclude_check = reduce(lambda x, y: x and fnmatch(filename, y), exclude_patterns, True) - - if pattern_check and not exclude_check: + filename = os.path.normpath(os.path.join(root, f)) + if ( reduce(lambda x, y: x or fnmatch(filename, y), + file_patterns, False) + and not reduce(lambda x, y: x or fnmatch(filename, y), + exclude_patterns, False) ): sources.append(filename) - sources.extend([ os.path.normpath(os.path.join(str(node.dir),x)) - for x in data.get("@INCLUDE",[]) ]) - - for key in ('HTML_HEADER','HTML_FOOTER','TAGFILES'): + for key in dep_add_keys: if data.has_key(key): elt = data[key] if type(elt) is type ("") : elt = [ elt ] - sources.extend([ os.path.normpath(os.path.join(str(node.dir),f)) + sources.extend([ os.path.normpath(os.path.join(basedir,f)) for f in elt ]) sources = map( lambda path: env.File(path), sources ) diff --git a/satscons/SConscript b/satscons/SConscript new file mode 100644 index 0000000..7c154a0 --- /dev/null +++ b/satscons/SConscript @@ -0,0 +1,7 @@ +Import('env') +import SatSCons + +########################################################################### + +SatSCons.StandardTargets(env) +SatSCons.Doxygen(env) diff --git a/satscons/SatSCons.py b/satscons/SatSCons.py index 8b10deb..6c8bcc9 100644 --- a/satscons/SatSCons.py +++ b/satscons/SatSCons.py @@ -1,8 +1,15 @@ import os.path, SCons.Options, SCons.Environment, SCons.Script.SConscript, glob +SCONS_TOOLS = [ + "Doxygen", + "Dia2Png", +] + opts = None finalizers = [] +basedir = os.path.split(__file__)[0] + def InitOpts(): global opts if opts is not None: return @@ -28,7 +35,7 @@ def UseBoost(): Finalizer(FinalizeBoost) def FinalizeBoost(env): - env.Tool('BoostUnitTests', [os.path.split(__file__)[0]]) + env.Tool('BoostUnitTests', [basedir]) if env['BOOST_TOOLSET']: runtime = "" @@ -64,12 +71,6 @@ def FinalizeSTLPort(env): env.Append(LIBS = [ '$STLPORT_DEBUGLIB' ], CPPDEFINES = [ '_STLP_DEBUG' ]) -def UseDoxygen(): - Finalizer(FinalizeDoxygen) - -def FinalizeDoxygen(env): - env.Tool('Doxygen', [os.path.split(__file__)[0]]) - def MakeEnvironment(): global opts, finalizers InitOpts() @@ -85,6 +86,9 @@ def MakeEnvironment(): for finalizer in finalizers: finalizer(env) + for tool in SCONS_TOOLS: + env.Tool(tool, [basedir]) + env.Append(CXXFLAGS = [ '-Wall', '-Woverloaded-virtual', '-Wno-long-long' ], LOCALLIBDIR = [ '#' ], LIBPATH = [ '$LOCALLIBDIR' ])