diff options
Diffstat (limited to 'cpp/README')
| -rw-r--r-- | cpp/README | 274 |
1 files changed, 251 insertions, 23 deletions
diff --git a/cpp/README b/cpp/README index d1cbed6c18..83e9d6ed5e 100644 --- a/cpp/README +++ b/cpp/README @@ -1,13 +1,7 @@ = Qpid C++ = -Qpid C++ is a C++ implementation of the AMQP protcol described at -http://amqp.org/ - -For instructions on using the Qpid broker daemon see man qpidd(1) - -For information on the C++ client API see ./html/index.html - -Note the daemon and client API can be installed separately. +Qpid C++ is a C++ implementation of the AMQP protcol described at + http://amqp.org/ The Qpid project also provides Java, Ruby and Python implementations. @@ -15,32 +9,266 @@ For additional software or information on the Qpid project go to: http://incubator.apache.org/qpid/index.html -= Building from a source distribution = +Available documentation: + qpidd(1) man page - how to run the broker daemon. + html/index.html - C++ client API. + +Note the daemon and client API can be installed separately. + +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 == - * Apache Portable Runtime 1.2.2: http://apr.apache.org - * boost 1.33.1: http://www.boost.org +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) + +=== Optional tools === + +Building from a source distribution does not require: + + * autoconf + * automake + * JDK 5.0 + +Building without testing does not require: + + * cppunit + +Building without documentaion does not require: -Optional: if you want to run the qpid unit tests: - * CppUnit 1.11.4: http://cppunit.sourceforge.net - Note: Ensure cppunit-config is in your PATH. - -If you use yum to install packages you can do: + * help2man + * doxygen + * graphviz + +=== Installing as root === + +On linux most packages can be installed using your distribution's package +management tool. For example on Fedora: # 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. + +=== Building and installing packages manually or as non-root user === + +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: -== Building == + # export PATH=~/jdk1.5.0_11/bin:$PATH -If you install boost to a non-standard location then you'll need define CXXFLAGS prior -to doing ./configure: - - export CXXFLAGS=-I${boost_prefix}/include/boost-1_33_1 +== Building from a source distribution. == -e.g. export CXXFLAGS=-I$HOME/local/boost-1.33.1/include/boost-1_33_1 +In the distribution directory Build and install with: - # ./configure + + # ./configure --prefix=<install_location> # 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) + + +== For Qpid developers: building a repository working copy == + +=== Installing the latest autotools === + +If you don't have sufficiently up-to-date autotools you can get the +latest by running 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. + +=== Building a checkout === +To get the source code from the subversion repository (trunk) do: + + # svn checkout https://svn.apache.org/repos/asf/incubator/qpid/trunk/ . + +To build a fresh checkout: + +Cd to qpid/cpp subdirectory. 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. + +=== 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 only 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 +This README describes how to build the Qpid C++ broker and client, either +from a checkout of the source or from a source distribution. |