blob: 7d394bf51161a7e3ccdc89ee417c97f3f12a19d4 (
plain)
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
|
= Developer guide to C++ codebase =
== Prerequisites ==
Required to build:
* Apache Portable Runtime 1.2.7: http://apr.apache.org
* CppUnit 1.11.4: http://cppunit.sourceforge.net
* boost 1.33.1: http://www.boost.org
Optional: to generate documentation from source code comments you need:
* doxygen 1.4.6: http://sourceforge.net/projects/doxygen/
* graphviz 2.8: http://www.graphviz.org/
If you use yum to install packages:
# yum install apr apr-devel cppunit cppunit-devel boost boost-devel doxygen graphviz
== Building ==
You can have mutltiple builds in the same working copy.
For example for a release build using APR platform:
make USE_APR=1 RELEASE=1
This will create build/apr-release containing the bin/ lib/ and test/ subdirs.
You can set your preferred defaults in options-local.mk.
Generated code goes in build/gen and is shared between all builds.
All other build output is under build/<build name>/
* bin/ lib/ - executables and libraries.
* test/ - test executables, directories with unit test .so plugins.
* obj/ - compiled .o files.
* include - exported header files
Main targets:
* test: (default) build & run all tests
* all: build all
* usage: this message
* unittest: run unit tests
* pythontest: run python tests.
* doxygen: generate documentation in build/html
* clean: cleans the current build only. Does not clean generated code.
* spotless: cleans up all build output and removes the build directory.
=== Source Tree ===
The source tree is structured as follows:
* src/ - .h and .cpp source files, directories mirror namespaces.
* qpid/
* sys/ - system portability abstractions: threading, io etc.
* posix/ - posix implementations for sys
* apr/ - portable APR implementation for sys
* framing - encoding/decoding AMQP messages
* client - client classes.
* broker - broker classes.
* etc/ - Non-c++ resources, e.g. stylesheets.
* test/
* unit/ - unit tests (cppunit plugins), directories mirror namespaces.
* include/ - .h files used by tests
* client/ - sources for client test executables.
Build system principles:
* Single Makefile (see http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html)
* Calculate sources from directories, no explicit source lists.
* Corresponding .cpp and .h files in same directory for easy editing.
* Source directory structure mirrors C++ namespaces.
=== Portability ===
All system calls are abstracted by classes in qpid/sys. This provides
an object-oriented C++ API and contains platform-specific code.
These wrappers should be mainlly inline by-value classes so they
impose no run-time penalty compared do direct system calls.
Initially we will have a full POSIX implementation and a portable
implementation suffcient 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 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
|
