= Developer guide to C++ codebase =

== Prerequisites ==

As per README-dist plus:
 * autoconf 2.59: http://www.gnu.org/software/autoconf
 * automake 1.9.6: http://www.gnu.org/software/automake
 * libtool 1.5: http://www.gnu.org/software/libtool
 * CppUnit 1.10.2: http://cppunit.sourceforge.net

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, do the command from the README-dist then:

# yum install apr-devel cppunit-devel boost-devel doxygen graphviz

== Recent changes ==

There have been two major changes on the C++ hierarchy:
  - adds autoconf, automake, libtool support
  - makes the hierarchy flatter and renames a few files (e.g., Queue.h,
  Queue.cpp) that appeared twice, once under client/ and again under broker/.

In the process, I've changed many #include directives, mostly
to remove a qpid/ or qpid/framing/ prefix from the file name argument.
Although most changes were to .cpp and .h files under qpid/cpp/, there
were also several to template files under qpid/gentools, and even one
to CppGenerator.java.

Nearly all files are moved to a new position in the hierarchy.
The new hierarchy looks like this:

  src               # this is the new home of qpidd.cpp
  tests             # all tests are here.  See Makefile.am.
  gen               # As before, all generated files go here.
  lib               # This is just a container for the 3 lib dirs:
  lib/client
  lib/broker
  lib/common
  lib/common/framing
  lib/common/sys
  lib/common/sys/posix
  lib/common/sys/apr
  build-aux
  m4

== Building ==

As we smooth off the rough edges with the new build setup the steps
for the most common development tasks will be scripted and/or
simplified and this README will be updated accordingly.

Before building a fresh checkout do:
 ./bootstrap

This generates config, makefiles and the like - check the script for
details. You only need to do this once, "make" will keep everything up
to date thereafter (including re-generating configuration & Makefiles
if the automake templates change etc.)

To build and test everything:
  make
  make check

This builds in the source tree. You can have multiple builds in the
same working copy with different configuration. For example you can do
the following to build twice, once for debug, the other with
optimization:

  make distclean
  mkdir .build-dbg .build-opt
  (cd .build-opt
   ../configure --enable-warnings --prefix=/tmp/x && make && make check)
  (cd .build-dbg
   ../configure --enable-warnings CXXFLAGS=-g --prefix=/tmp/x \
     && make && make check)

=== Portability ===

All system calls are abstracted by classes under lib/common/sys. This
provides an object-oriented C++ API and contains platform-specific
code.

These wrappers are mainly inline by-value classes so they impose no
run-time penalty compared do direct system calls.

Initially we will have a full linux implementation and a portable
implementation sufficient for the client using the APR portability
library. The implementations may change in future but the interface
for qpid code outside the qpid/sys namespace should remain stable.


=== 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