1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
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
a. openais
b. boost
c. 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.35)(*)
* e2fsprogs <http://e2fsprogs.sourceforge.net/> (1.39)
* pkgconfig <http://pkgconfig.freedesktop.org/wiki/> (0.21)
(*) earlier versions of boost e.g. 1.33 also work
Optional cluster functionality requires:
* openais <http://openais.org/> (0.80.3)
Optional XML exchange requires:
* xqilla <http://xqilla.sourceforge.net/HomePage> (2.0.0)
* xerces-c <http://xerces.apache.org/xerces-c/> (2.7.0)
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)
NOTE: make sure to install the related '-devel' packages also!
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 boost-devel e2fsprogs-devel pkgconfig openais openais-devel
# yum install gcc-c++ make autoconf automake help2man libtool doxygen graphviz ruby
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.
a. openais
==========
If ais is shipped with you platform and you have 0.80.3-x or later, skip
builing ais
To build ais: 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.)
Configuring ais:
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/
b. 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
c. autotools
============
If you don't have sufficiently up-to-date autotools you can get the
latest by running 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
|