diff options
author | Carl C. Trieloff <cctrieloff@apache.org> | 2008-04-24 21:07:47 +0000 |
---|---|---|
committer | Carl C. Trieloff <cctrieloff@apache.org> | 2008-04-24 21:07:47 +0000 |
commit | 09744902d2df556f2c67cfb6295276beeb6143b6 (patch) | |
tree | 27bc504af0cf234092dc5cb543439d713b0b56fa /qpid/cpp | |
parent | 18993656fb8578b58c5ae6ee96fac998914bf209 (diff) | |
download | qpid-python-09744902d2df556f2c67cfb6295276beeb6143b6.tar.gz |
QPID-958 by Danushka Menikkumbura
git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk@651425 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'qpid/cpp')
-rw-r--r-- | qpid/cpp/INSTALL | 307 | ||||
-rw-r--r-- | qpid/cpp/README | 306 |
2 files changed, 329 insertions, 284 deletions
diff --git a/qpid/cpp/INSTALL b/qpid/cpp/INSTALL new file mode 100644 index 0000000000..e7e9af14ca --- /dev/null +++ b/qpid/cpp/INSTALL @@ -0,0 +1,307 @@ + Installing Qpid/C++ + =================== + +Table of Contents +================= +1. Introduction + +2. Prerequisites + 2.1. What to Install + 2.2. How to Install + 2.2.1. Using Package Management Tools + 2.2.2. From Source + - openais + - boost + 2.2.3. autotools + 2.3. Important Environment Variable Settings + +3. Building from a Source Distribution +4. Building a Repository Working Copy +5. Portability +6. Tests +7. Doxygen +8. Troubleshooting + + +1. Introduction +=============== +Note that the daemon and client API can be installed separately. + +This document describes how to build the Qpid/C++ broker and client, either +from a checkout of the source or from a source distribution. + +This also explains how to install the required prerequisites for Qpid/C++. + + +2. 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. + + +2.1. What to Install +==================== +The following libraries and header files must be installed to build +a source distribution: + * boost <http://www.boost.org> (1.33.1) + * e2fsprogs <http://e2fsprogs.sourceforge.net/> (1.39) + * pkgconfig <http://pkgconfig.freedesktop.org/wiki/> (0.21) + +Optional cluster functionality requires: + * openais <http://openais.org/> (0.80.3) + +Running qpid test suite requires: + * cppunit <http://cppunit.sourceforge.net> (1.11.4) + +Qpid has been built using the GNU C++ compiler: + * gcc <http://gcc.gnu.org/> (3.2.3) + +If you want to build directly from the SVN repository you will need +all of the above plus: + + * 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) + * 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) + + +2.2. How to Install +=================== + +2.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 pkgconfig e2fsprogs boost-devel cppunit-devel openais-devel ruby + # yum install make gcc-c++ autoconf automake libtool doxygen help2man graphviz # yum install e2fsprogs-devel + +Follow the manual installation instruction below for any packages not +available through yum. + +2.2.2. 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 pakcages: + + 1. Unzip and untar them and cd to the untared directory. + 2. do: + # ./configure --prefix=~/qpid-tools + # make install + +The exceptions are openais and boost. + +- openais +========= +Unpack the source distribution and do: + # make + # sudo make install DESTDIR= + # sudo ldconfig + +This will install in the standard places (/usr/lib, /usr/include etc.) + +Edit /etc/ais/openais.conf and modify the "bindnetaddr" setting +to your hosts IP address. Do not use 127.0.0.1. + +Make sure the UDP port set for mcastport in openais.conf (5405 by +default) is not blocked by your firewall. Disable the firewall or +configure it to allow this port for UDP. + +Finally start the ais daemon (must be done as root): + # sudo /sbin/aisexec + +Note that to run the AIS tests your primary group must be "ais". You +can change your primary group with the usermod command or set it +temporarily with the newgrp command. + +Troubleshooting tips: + +If aisexec goes into a loop printing "entering GATHER state", verify your firewall is allowing UDP traffic on the mcastport set in openais.conf. + +If aisexec reports "got nodejoin message 127.0.0.1" verify the +bindnetaddr in openais.conf is an active local IP address. ifconfig +will list local addresses. + +When aisexec is working correctly, the start-up log messages will end +with "entering OPERATIONAL state." and "got nodejoin message <ip +address>" where <ip address> is the local IP address specified for +bindnetaddr in openais.conf. + +For further info on openais http://openais.org/ + +- 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 -sTOOLS=gcc --prefix=~/qpid-tools + +2.2.3. 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. + + +2.3. Important Environment Variable Settings +============================================ +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 + + +3. Building from a Source Distribution +====================================== +In the distribution directory + +Build and install with: + + # ./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) + + +4. Building a Repository Working Copy +===================================== +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 in step (3). + + +5. 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. + + +6. Tests +======== +See src/tests/README for details. + + +7. 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. + + +8. Troubleshooting +================== +When building, get the following on configure + configure: error: Package requirements (apr-1 >= 1.2.2) were not met: + + No package 'apr-1' found + +The following has not been set + export PKG_CONFIG_PATH=$HOME/qpid-tools/lib/pkgconfig:/usr/lib/pkgconfig diff --git a/qpid/cpp/README b/qpid/cpp/README index 7de7fd3f98..e008f5b45b 100644 --- a/qpid/cpp/README +++ b/qpid/cpp/README @@ -1,291 +1,29 @@ -= Qpid C++ = + Qpid/C++ + ======== -Qpid C++ is a C++ implementation of the AMQP protcol described at - http://amqp.org/ +Table of Contents +================= +1. Introduction +2. Available Documentation -The Qpid project also provides Java, Ruby and Python implementations. -NOTE: This release of Qpid C++ implements the AMQP 0-9 WIP. -It will not inter-operate with AMQP 0-8 implementations. -We will be moving to 0-10 as soon as it is available. +1. Introduction +=============== +Qpid/C++ is a C++ implementation of the AMQP protcol described at +http://amqp.org/ -For additional software or information on the Qpid project go to: - http://cwiki.apache.org/qpid/ - -Available documentation: - qpidd(1) man page - how to run the broker daemon. - html/index.html - C++ client API. - NEWS - release notes. -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 == - -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. - -The following libraries and header files must be installed to build -a source distribution: - * boost <http://www.boost.org> (1.33.1) - * e2fsprogs <http://e2fsprogs.sourceforge.net/> (1.39) - * pkgconfig <http://pkgconfig.freedesktop.org/wiki/> (0.21) - -Optional cluster functionality requires: - * openais <http://openais.org/> (0.80.3) - -Running qpid test suite requires: - * cppunit <http://cppunit.sourceforge.net> (1.11.4) - -Qpid has been built using the GNU C++ compiler: - * gcc <http://gcc.gnu.org/> (3.2.3) - -If you want to build directly from the SVN repository you will need -all of the above plus: - - * 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) - * 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) - -=== Installing as root === - -On linux most packages can be installed using your distribution's package -management tool. For example on Fedora: - # yum install pkgconfig e2fsprogs boost-devel cppunit-devel openais-devel ruby - # yum install make gcc-c++ autoconf automake libtool doxygen help2man graphviz - # yum install e2fsprogs-devel - -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 are openais, boost, JDK 5.0. - -==== To build and install openais from source ==== - -Unpack the source distribution and do: - # make - # sudo make install DESTDIR= - # sudo ldconfig - -This will install in the standard places (/usr/lib, /usr/include etc.) - -Edit /etc/ais/openais.conf and modify the "bindnetaddr" setting -to your hosts IP address. Do not use 127.0.0.1. - -Make sure the UDP port set for mcastport in openais.conf (5405 by -default) is not blocked by your firewall. Disable the firewall or -configure it to allow this port for UDP. - -Finally start the ais daemon (must be done as root): - # sudo /sbin/aisexec - -Note that to run the AIS tests your primary group must be "ais". You -can change your primary group with the usermod command or set it -temporarily with the newgrp command. - -Troubleshooting tips: - -If aisexec goes into a loop printing "entering GATHER state", verify your firewall is allowing UDP traffic on the mcastport set in openais.conf. - -If aisexec reports "got nodejoin message 127.0.0.1" verify the -bindnetaddr in openais.conf is an active local IP address. ifconfig -will list local addresses. - -When aisexec is working correctly, the start-up log messages will end -with "entering OPERATIONAL state." and "got nodejoin message <ip -address>" where <ip address> is the local IP address specified for -bindnetaddr in openais.conf. - -For further info on openais http://openais.org/ - -==== 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 +This release of Qpid/C++ implements the AMQP 0-10. +It will not inter-operate with AMQP 0-8/0-9 implementations. -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 - -== Building from a source distribution. == - -In the distribution directory - -Build and install with: - - # ./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. - -=== Tests === - -See src/tests/README for details. - -== 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. +For additional software or information on the Qpid project go to: +http://cwiki.apache.org/qpid/ -=== Troubleshooting === -When building, get the following on configure - configure: error: Package requirements (apr-1 >= 1.2.2) were not met: - No package 'apr-1' foun - -The following has not been set - export PKG_CONFIG_PATH=$HOME/qpid-tools/lib/pkgconfig:/usr/lib/pkgconfig - +2. Available Documentation +========================== + - INSTALL - How to install Qpid/C++. + - RELEASE_NOTES - Release notes. + - DESIGN - Qpid/C++ implementation. + - LICENSE - Apache license. + - NOTICE - Corresponds to the section 4 d of + the Apache License, Version 2.0. |