This README describes how to build the Qpid C++ broker and client, either
from a checkout of the source or from a source distribution.

== Prerequisites ==

We prefer to avoid spending time accommodating older versions of these
packages, so please make sure that you have the latest stable versions.
Known version numbers for a succesfull build are given in brackets, take
these as a recommended minimum version. Older unix versions, for example,
Redhat Linux 3, will almost certainly require some packages to be upgraded.

Qpid can be built using the gcc compiler:

 * gcc     <http://gcc.gnu.org/>            (3.2.3)

Qpid is compiled against libraries:

 * apr     <http://apr.apache.org>          (1.2.7)
 * boost   <http://www.boost.org>           (1.33.1)
 * cppunit <http://cppunit.sourceforge.net> (1.11.4)

Using tools:

 * boost-jam  <http://boost.sourceforge.net/>          (3.1.13)
 * GNU make   <http://www.gnu.org/software/make/>      (3.8.0)
 * autoconf   <http://www.gnu.org/software/autoconf/>  (2.61)
 * automake   <http://www.gnu.org/software/automake/>  (1.9.6)
 * help2man   <http://www.gnu.org/software/help2man/>  (1.36.4)
 * libtool    <http://www.gnu.org/software/libtool/>   (1.5.22)
 * pkgconfig  <http://pkgconfig.freedesktop.org/wiki/> (0.21)
 * doxygen    <ftp://ftp.stack.nl/pub/users/dimitri/>  (1.5.1)
 * graphviz   <http://www.graphviz.org/>               (2.12)
 * JDK 5.0    <http://java.sun.com/j2se/1.5.0/>        (1.5.0.11)

Building from a source distribution:

 You do not require:

 * autoconf
 * automake
 * JDK 5.0

Building without testing:

 You do not require:

 * cppunit

Building without documentaion:

 You do not require:

 * help2man
 * doxygen
 * graphviz

Installing as root:

 Many of these packages can be installed using the yum tool. For example:

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

 Follow the manual installation instruction below for any packages not available 
 through yum.

Installing and building packages not as root:

 Required dependencies can be installed and built from source distributions.
 It is recommended that you create a directory to install them to, for example,
 ~/qpid-tools. To build and install the dependency pakcages:

 1. Unzip and untar them and cd to the untared directory.
 2. do:

  # ./configure --prefix=~/qpid-tools
  # make install

 The exceptions to this are boost and JDK 5.0.
 To build the boost library:

 1. Unpack boost-jam.
 2. Add bjam in the unpacked directory to your path.
 3. Unpack boost and cd to the boost untarred directory.
 4. do:

  # bjam -sTOOLS=gcc --prefix=~/qpid-tools

 To install JDK 5.0 download and run its install script, or whatever alternative 
 instructions may be on the sun website.

 Ensure that all the build tools are available on your path, when they are
 manually installed to non-standard locations. For example:

 # export PATH=~/qpid-tools/bin:$PATH

 Ensure that pkg-config is set up correctly. For example:

 # export PKG_CONFIG_PATH=~/qpid-tools/lib/pkgconfig:/usr/local/pkgconfig
 # export PKG_CONFIG=~/qpid-tools/bin/pkg-config

 Ensure that the boost libraries are made available on the gcc library path.
 For example:

 # export CXXFLAGS=-I~/qpid-tools/include/boost-1_33_1

 Ensure that JDK 5.0 has its home location set up correctly and is added to
 the path. For example:

 # export PATH=~/jdk1.5.0_11/bin:$PATH
 # export JAVA_HOME=~/jdk1.5.0_11/

== Obtaining a source code checkout from subversion. ==

Skip this step if you have a source distribution to build from. To get the
code from the subversion repository (trunk) do:

 # svn checkout https://svn.apache.org/repos/asf/incubator/qpid/trunk/ .

== Building from a fresh checkout (Developers). ==

Cd to the qpid/cpp subdriectory. Before running make on 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.)

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.

Now follow instruction for building from a source distribution.

== Building from a source distribution. ==

Build and install with:

 # ./configure
 # make all
 # make install

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)

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