diff options
Diffstat (limited to 'qpid/cpp/INSTALL')
| -rw-r--r-- | qpid/cpp/INSTALL | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/qpid/cpp/INSTALL b/qpid/cpp/INSTALL new file mode 100644 index 0000000000..717c9b0908 --- /dev/null +++ b/qpid/cpp/INSTALL @@ -0,0 +1,327 @@ + 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 AMQP_1.0 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: +* 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 + |