path: root/cpp/README-dev

= Developer guide to C++ codebase =

== Extra stuff ==
sudo cp /usr/share/aclocal/pkg.m4 `aclocal --print-ac-dir`

== Prerequisites ==

If you have taken the sources from SVN you will need the following
packages (or later)

We prefer to avoid spending time accommodating older versions of these
packages, so please make sure that you have the latest stable version.

 * All the prerequisites listed in README-dist.
 * GNU make   <http://www.gnu.org/software/make/>
 * autoconf   <http://www.gnu.org/software/autoconf/>
 * automake   <http://www.gnu.org/software/automake/>
 * cppunit    <http://cppunit.sourceforge.net>
 * help2man   <http://www.gnu.org/software/help2man/>
 * libtool    <http://www.gnu.org/software/libtool/>
 * pkgconfig  <http://pkgconfig.freedesktop.org/wiki/> (aka pkg-config)

Note: Ensure cppunit-config and apr-1-config are in your PATH.

Optional: to re-generated generated code from the XML specification:

 * java 5

Optional: to generate documentation you need:

 * doxygen    <http://sourceforge.net/projects/doxygen/>
 * graphviz   <http://www.graphviz.org/>
 * help2man   <http://www.gnu.org/software/help2man/>

== Setting up on Fedora 6 ==

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

To get the latest versions of autoconf, automake, libtools and other
dependencies, run the script qpid-autotools-install:

1. Decide where you would like to install the tools. It should be in a
   local directory so that you do not need root privileges. (Suggest
   $HOME/qpid-tools.) Create an empty directory.
2. Modify your environment variable PATH to ensure that the bin directory
   within this directory comes first in the PATH string:
   PATH=$HOME/qpid-tools/bin:$PATH
3. Set PKG_CONFIG_PATH=$HOME/qpid-tools/lib/pkgconfig:/usr/lib/pkgconfig
   (or if it already exists, make sure that the above path to your
   qpid-tools directory is first).
4. Run the install utility from the cpp directory:
   ./qpid-autotools-install --prefix=$HOME/qpid-tools --skip-check
   (Note that --prefix will only accept an absolute path, so don't use
   ~/qpid-tools.) The utility will download, compile and install the
   required tools into the qpid-tools directory (this may take a little
   time). Watch for any notices about paths at the end of the install -
   this means that your environment is not correct - see steps 2 and 3
   above.
   NOTE: If you omit the --skip-check option, the check of the build
   can add up to an hour to what is normally a few minutes of install
   time.
5. Perform a check: from the command-line run "which automake" and
   ensure that it finds the automake in your qpid-tools directory. If not,
   check that the build completed normally and your environment.
6. (Optional) If having the build artifacts lying around bothers you, delete
   the (hidden) build directory cpp/.build-auto-tools.

To see help, run ./qpid-autotools-install --help.

== 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
  ./configure

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.)

If you are developing code yourself, or if you want to help
us keep the code as tight and robust as possible, consider enabling
the use of valgrind.  If you configure like this:

  ./configure --enable-valgrind

that will arrange (assuming you have valgrind installed) for "make check"
to run tests via valgrind.  That makes the tests run more slowly, but
helps detect certain types of bugs, as well as memory leaks.  If you run
"make check" and valgrind detects a leak that is not listed as being
"ignorable-for-now", the test script in question will fail.  However,
recording whether a leak is ignorable is not easy, when the stack
signature, libraries, compiler, O/S, architecture, etc., may all vary,
so if you see a new leak, try to figure out if it's one you can fix
before adding it to the list.

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 --prefix=/tmp/x && make && make check)
  (cd .build-dbg
   ../configure CXXFLAGS=-g --prefix=/tmp/x \
     && make && make check)

Since it's common to want to bootstrap & test a working copy with
default configuration you can say:
 ./bootstrap -build

Which is equivalent to
 ./bootstrap && ./configure && 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