= Developer guide to C++ codebase =

See DESIGN for design notes, Makefile comment for build system notes.

== Prerequisites ==

Required to build:
 * Apache Portable Runtime 1.2.7:  http://apr.apache.org
 * CppUnit 1.11.4: http://cppunit.sourceforge.net
 * boost 1.33.1: http://www.boost.org

Optional: to generate documentation from source code comments you need:
 * doxygen 1.4.6: http://sourceforge.net/projects/doxygen/ 
 * graphviz 2.8: http://www.graphviz.org/

If you use yum to install packages:
# yum install apr apr-devel cppunit cppunit-devel boost boost-devel doxygen graphviz

== Building ==

You can have mutltiple builds in the same working copy. 
For example for a release build using APR platform:

  make PLATFORM=apr TYPE=release

This will create build/apr-release containing the bin/ lib/ and test/ subdirs.

To set your preferred default create file options-local.mk with
PLATFORM=<my platform>
TYPE=<my type>

Generated code goes in build/gen and is shared between all builds.

All other build output is under build/<build name>/
 * bin/ lib/ - executables and libraries.
 * test/ - test executables, directories with unit test .so plugins.
 * obj/ - compiled .o files.
 * include - exported header files

Main targets:
 * test: (default) build & run all tests
 * all: build all
 * usage: this message
 * unittest: run unit tests
 * pythontest: run python tests.
 * doxygen: generate documentation in build/html
 * clean: cleans the current build only. Does not clean generated code.
 * spotless: cleans up all build output and removes the build directory.

The source tree is structured as follows:
 * src/ - .h and .cpp source files, directories mirror namespaces.
 * src_apr/ - source files that depend on APR
 * src_linux/ - source files optimized for Linux.
 * etc/ - Non-c++ resources, e.g. stylesheets.
 * test/ 
  * unit/ - unit tests (cppunit plugins), directories mirror namespaces.
  * include/ - .h files used by tests
  * client/ - sources for client test executables.

Build system principles:
 * Single Makefile (see http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html)
 * Calculate sources from directories, no explicit source lists.
 * Corresponding .cpp and .h files in same directory for easy editing.
 * Source directory structure mirrors C++ namespaces.

=== Unit tests ===

Unit tests are built as .so files containing CppUnit plugins. 

DllPlugInTester is provided as part of cppunit. You can use it to run
any subset of the unit tests. See Makefile for examples.

NOTE: If foobar.so is a test plugin in the current directory then
surprisingly this will fail with "can't load plugin":
 DllPluginTester foobar.so

Instead you need to say:
 DllPluginTester ./foobar.so 
 
Reason: DllPluginTester uses dlopen() which searches for shlibs 
in the standard places unless the filename contains a "/".  In
that case it just tries to open the filename.

=== System tests ===

The Python test suite ../python/run_tests is the main set of broker
system tests.

There are some C++ client test executables built under client/test.

== Doxygen ==

Doxygen generates documentation in several formats from source code
using special comments. You can use javadoc style comments if you know
javadoc, if you don't or want to know the fully story on doxygen
markup see http://www.stack.nl/~dimitri/doxygen/

Even even if the code is completely uncommented, doxygen generates
UML-esque dependency diagrams that are ''extremely'' useful in navigating
around the code, especially for newcomers.

To try it out "make doxygen" then open doxygen/html/index.html