| Installing Qpid/C++ |
| =================== |
| |
| Table of Contents |
| ================= |
| 1. Introduction |
| 2. How to Build and Install Qpid from a Source Distribution |
| 3. Building a Repository Working Copy |
| 4. Tests |
| |
| 5. Prerequisites |
| 5.1. What Prerequisite Libraries to Install |
| 5.2. How to Install Prerequisite Libraries |
| 5.2.1. Using Package Management Tools |
| 5.2.2. Building Prerequisites From Source |
| 5.3. Important Environment Variable Settings |
| |
| |
| 1. Introduction |
| =============== |
| This document describes how to build the Qpid/C++ broker and client, either |
| from a checkout of the source or from a source distribution, on Linux/UNIX. |
| |
| Please see INSTALL-WINDOWS for information on building on Windows. |
| |
| There are a number of prerequisite libraries that may need to be installed. |
| If this is the first time that you have built Qpid please check the prerequisites |
| section 5. below and/or check the output from running cmake for any errors. |
| |
| As of Qpid 0.26 cmake (versions 2.6 or 2.8) is the only way to build Qpid. |
| |
| |
| 2. How to Build and Install Qpid from a Source Distribution |
| =========================================================== |
| It is strongly recommended that you use a separate build directory and do not try to |
| build in the source directory. You may use a build directory in any convenient place. |
| These instructions use a build directory inside the source tree but this isn't essential. |
| |
| In the cpp distribution directory (<qpid>/cpp), build the code with: |
| |
| # mkdir bld # This is just a suggested name for the build directory |
| # cd bld |
| # cmake .. # ".." is the path to the distribution directory |
| |
| # make all |
| |
| To run the tests: |
| |
| # make test |
| |
| To install (you may need to be root/sudo to do this): |
| |
| # make install |
| |
| To uninstall (you may need to be root/sudo to do this): |
| |
| # make uninstall |
| |
| |
| The daemon and client API may be built separately if so desired: |
| |
| # make qpidbroker |
| |
| # make qpidclient |
| |
| The available make targets can be listed using: |
| |
| # make help |
| |
| |
| You can have multiple builds which use the same working copy with different |
| configuration. For example you can do the following to build twice, once for |
| debug, the other with optimization: |
| |
| # mkdir BLD-dbg BLD-opt |
| # (cd BLD-dbg; cmake -DCMAKE_BUILD_TYPE=Debug .. && make ) |
| # (cd BLD-opt; cmake -DCMAKE_BUILD_TYPE=Release .. && make) |
| |
| Note that there are 4 different predefined cmake build types: |
| Debug, Release, MinSizeRel, DebWithRelInfo: They each correspond to a different |
| set of build flags for respectively debug; release; minimum size release; release |
| with debug information. |
| |
| To see and edit all the available cmake options: |
| |
| # cmake-gui .. # ".." is the path to the source directory |
| |
| Or if you have only have a command line environment available |
| |
| # ccmake .. # ".." is the path to the source directory |
| |
| 2.1 Building as C++11 (Experimental) |
| ==================================== |
| Currently the Qpid project uses C++ that conforms to the C++03 standard, as currently |
| this is the C++ standard that is supported the most widely, so any new code must also |
| compile as C++03. As an experiment (and to support a few extra platforms) the Qpid code |
| will also now build as C++11. |
| |
| This will work under both gcc and clang. However when compiled under gcc you will hit some |
| depracation watrnings which will need to be suppressed. |
| |
| To compile as C++11 under gcc configure using cmake like this: |
| |
| # cmake -DCMAKE_CXX_FLAGS="-std=c++11 -Wno-error=deprecated-declarations" .. |
| |
| To compile as C++11 under clang configure using cmake like this: |
| |
| # CXX=clang++ CC=clang cmake -DBUILD_PROBES=no -DCMAKE_CXX_FLAGS=-std=c++11 .. |
| |
| 2.2 Building with the clang C++ compiler |
| ======================================== |
| Qpid will build with the clang compiler as well as gcc. When compiling using clang the probe |
| code will not compile so will need to be turned off. |
| |
| To compile using clang configure with cmake as follows: |
| |
| # CXX=clang++ CC=clang cmake -DBUILD_PROBES=no .. |
| |
| 2.3 Building on FreeBSD |
| ======================= |
| Qpid will build (and run) under FreeBSD using the clang compiler, compiling on FreeBSD using gcc |
| is not being worked on, and indeed from FreeBSD 10 and onwards the system compiler is clang. |
| |
| Under FreeBSD 10 the C++ standard library is provided by libc++ rather than libstdc++ (which is the |
| norm under Linux). There seems to be a bug in boost::lexical_cast which exhibits when compiling Qpid |
| under C++03 with libc++ but not C++11 with libc++. This means that you have to compile Qpid as C++11 |
| under FreeBSD 10. |
| |
| # cmake -DCMAKE_CXX_FLAGS=-std=c++11 -DBUILD_BINDING_PERL=no .. |
| |
| It is not necessary to specify CXX=clang++ because it is the system compiler under FreeBSD 10; |
| similarly we don't try to build the probe code on FreeBSD at this point because it doesn't work |
| there yet, so it doesn't need to be explicitly turned off. |
| |
| We turn building the PERL bindings off because the perl header file is incompatible with C++11 currently. |
| |
| If you want to use the ports version of cyrus-sasl then you should also add: |
| |
| -DCMAKE_REQUIRED_FLAGS=-L/usr/local/lib -DCMAKE_REQUIRED_INCLUDES=/usr/local/include |
| |
| Which will allow cmake to find libraries installed in /usr/local (which is where cyrus-sasl gets |
| installed by ports). |
| |
| 2.4 Building on AIX |
| =================== |
| Qpid has been tested on AIX 7.1 with XL C++ 13.1 and Boost 1.55.0. The |
| thread-using variant of the compiler must be used but it isn't the default |
| picked up by cmake. Thus, the compiler must be specified at cmake time. |
| For example (assuming PATH includes the compiler binaries): |
| |
| # CXX=xlC_r CC=cc_r cmake .. |
| |
| Warnings from Boost header files are expected and can be ignored. |
| |
| It is normal to see (lots of) multiply-defined symbol warnings when linking |
| the shared libraries built as part of Qpid. |
| |
| The mktemp package must be installed separately in order to execute the |
| Qpid test suite. |
| |
| 3. Building a Repository Working Copy |
| ===================================== |
| To get the source code from the subversion repository (trunk) do: |
| |
| # svn checkout http://svn.apache.org/repos/asf/qpid/trunk/qpid/. |
| |
| To build, cd to <qpid>/cpp subdirectory and then follow the instructions for building |
| from a Source Distribution in step (2). |
| |
| |
| 4. Tests |
| ======== |
| See <qpid>/cpp/src/tests/README.txt for details. |
| |
| |
| ====================================================================================== |
| |
| |
| 5. 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 succesful build are given in brackets, take |
| these as a recommended minimum version. |
| |
| |
| 5.1. What Prerequisite Libraries to Install |
| =========================================== |
| The following libraries and header files must be installed to build |
| a source distribution: |
| * boost <http://www.boost.org> (1.41) (*) |
| * libuuid <http://kernel.org/~kzak/util-linux/> (2.19) |
| * pkgconfig <http://pkgconfig.freedesktop.org/wiki/> (0.21) |
| |
| (*) Boost 1.33 will also work. |
| |
| Optional support for AMQP 1.0 requires (see docs/amqp-1.0.txt for details): |
| * Qpid proton-c <http://qpid.apache.org/proton> (0.5) |
| Note: If Proton is installed in a non-standard location, there are two ways to locate it: |
| 1. Recommended: use proton 0.7 or later and use the same install prefix |
| for both Proton and Qpid. |
| 2. Using pkg-config: set the PKG_CONFIG_PATH environment variable to |
| <proton-prefix>/lib[64]/pkgconfig before running cmake. |
| |
| Optional XML exchange requires: |
| * xqilla <http://xqilla.sourceforge.net/HomePage> (2.0.0) |
| * xerces-c <http://xerces.apache.org/xerces-c/> (2.7.0) |
| |
| Optional SSL support requires (see docs/ssl.txt for details): |
| * nss <http://www.mozilla.org/projects/security/pki/nss/> |
| * nspr <http://www.mozilla.org/projects/nspr/> |
| |
| Optional RDMA transport protocol requires: |
| * libibverbs <http://www.openfabrics.org/> (1.1) |
| * librdmacm <http://www.openfabrics.org/> (1.0) |
| |
| Optional binding support for ruby requires: |
| * ruby and ruby devel <http://www.ruby-lang.org/en/> |
| * swig <http://www.swig.org/> |
| |
| Qpid has been built using the GNU C++ compiler: |
| * gcc <http://gcc.gnu.org/> (4.1.2) |
| |
| If you want to build directly from the SVN repository you will need |
| all of the above plus: |
| |
| * Cmake <http://www.cmake.org/> (2.6.4) |
| * GNU make <http://www.gnu.org/software/make/> (3.8.0) |
| * help2man <http://www.gnu.org/software/help2man/> (1.36.4) |
| * doxygen <ftp://ftp.stack.nl/pub/users/dimitri/> (1.5.1) |
| * graphviz <http://www.graphviz.org/> (2.12) |
| * ruby 1.8 <http://www.ruby-lang.org> (1.8.4) |
| * python 2.x <http://www.python.org> (2.4.3) |
| |
| NOTE: make sure to install the related '-devel' packages also!!!! |
| |
| NOTE: Python 3.x is known to NOT work - please use 2.7 or earlier. |
| |
| To build the QMF (Qpid Management Framework) bindings for Ruby and Python, |
| the following must also be installed: |
| |
| * ruby-devel |
| * python-devel |
| * swig <http://www.swig.org> (1.3.35) |
| |
| UUID problems: |
| |
| In some earlier Linux releases (such as Fedora 11), the uuid/uuid.h |
| file is located in the e2fsprogs-devel package instead of |
| libuuid-devel. If you are using an older Linux release and run into a |
| problem during configure in which uuid.h cannot be found, install the |
| e2fsprogs-devel package. |
| |
| 5.2. How to Install Prerequisite Libraries |
| ========================================== |
| |
| 5.2.1. Using Package Management Tools |
| ===================================== |
| On linux most packages can be installed using your distribution's |
| package management tool. For example on Fedora: |
| |
| # yum install cmake boost-devel libuuid-devel pkgconfig gcc-c++ make ruby help2man doxygen graphviz |
| |
| For SASL and SSL, include |
| # yum install cyrus-sasl-devel nss-devel nspr-devel |
| |
| For the XML Exchange, include: |
| |
| # yum install xqilla-devel xerces-c-devel |
| |
| Optional ruby binding support include: |
| # yum install ruby ruby-devel swig |
| |
| Optional legacystore store module. |
| # yum install libdb-cxx-devel libaio-devel |
| |
| Follow the manual installation instruction below for any packages not |
| available through your distributions packaging tool. |
| |
| 5.2.2. Building Prerequisites From Source |
| ========================================= |
| 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 packages: |
| |
| 1. Unzip and untar them and cd to the untared directory. |
| 2. do: |
| # ./configure --prefix=~/qpid-tools |
| # make install |
| |
| The exception is boost. |
| |
| boost |
| ===== |
| 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 toolset=gcc variant=release threading=single link=shared \ |
| --layout=system --prefix=~/qpid-tools install |
| |
| |
| 5.3. Important Environment Variable Settings |
| ============================================ |
| Note that the following is generally not necessary if dependency packages have been |
| installed using Package Management Tools such as yum or apt. |
| |
| 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. This is especially important |
| if you have built the dependencies from source, as they may not be installed |
| in the default system location. For example: |
| |
| # export PKG_CONFIG_PATH=~/qpid-tools/lib/pkgconfig:/usr/local/lib/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 |
| |