forked from apache/qpid-dispatch
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
181 lines (123 loc) · 5.1 KB
/
README
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
Qpid Dispatch
=============
A lightweight AMQP router for building scalable, available, and performant messaging
interconnect.
Dependencies
============
To build dispatch on a yum-based Linux system, you will need the following
packages installed:
- qpid-proton-c-devel
- python-qpid-proton
- cmake
- make
- gcc
- python-devel
- cyrus-sasl-plain
- cyrus-sasl-devel
- asciidoc (for building docs)
- asciidoctor (for building docs)
The unit tests are implemented using Python's unittest library.
Python versions prior to 2.7 do not have this library. In
order to run the unit tests using older versions of python the
"unittest2" module must be installed.
This may be available from your Linux distribution or via pip:
pip install unittest2
The command line arguments parsing is done using Python's argparse library.
Python versions prior to 2.7 do not have this library. Similar to what happend
with unittest2, this may be fixed via pip:
pip install argparse
Dispatch will not build on Windows.
To build formatted documentation (man pages, HTML, PDF) see the requirements in doc/README
Building and testing
====================
From the dispatch directory:
$ mkdir my_build # or directory of your choice.
$ cd my_build
$ cmake ..
$ make
Running The Tests
=================
From the <build> directory you can run all the system and tests with:
$ ctest -VV
ctest uses the script <build>/test/run.py to set up the correct environment for
tests. You can use it to run tests individually from the <build>/tests
directory, for example:
$ ./run.py unit_tests_size 3
$ ./run.py -m unittest system_tests_qdstat
Run it without arguments to get a summary of how it can be used:
$ ./run.py
Test Suite Code Coverage (GNU tools only)
=========================================
Use coverage analysis to ensure that all code paths are exercised by
the test suite. To run the tests and perform code coverage analysis:
# install the lcov package
$ yum install lcov
# configure and build for the Coverage build type (from the <build> directory):
$ cmake -DCMAKE_BUILD_TYPE=Coverage .. && make
# run the test suite and generate the coverage html output
$ ctest && make coverage
# Then point your browser at:
<build>/coverage_results/html/index.html
Clean build, install and test
=============================
$ source config.sh; test.sh
This does the following:
- NOTE: delete any existing directories 'build' and 'install'
- Do a fresh cmake and make in directory 'build'
- Run unit tests (not system tests) in 'build'
- Do 'make install' into the directory 'install'
- Run system tests on the installation in 'install'.
Run Time Validation
===================
The CTest test suite can be configured to enable extra run time
validation checks against the dispatch router.
Since run time validation slows down qdrouter considerably it is
disabled by default. It can be enabled by setting the RUNTIME_CHECK
build flag via the cmake command.
Note well: Depending on your environment the ctest suite may time out
if validation is enabled due to the additional run time overhead it
adds. You can extend the default test time via the ctest "--timeout"
option. Example:
ctest --timeout 1500 -VV
The Qpid Dispatch Router test suite supports the following run time
validation tools:
Valgrind Memcheck
-----------------
Runs qdrouterd under Valgrind's memcheck leak checker during the CTest
suite. This will cause tests to fail if a memory error is
encountered. Use the grinder tool (in the bin directory) to create a
summary of the errors found during the test run.
The valgrind toolset must be installed in order to use memcheck.
To enable memcheck set the RUNTIME_CHECK build flag to "memcheck":
cmake .. -DRUNTIME_CHECK=memcheck
If valgrind detects errors the qdrouterd process will exit with an
exit code of 42. This will be displayed in the CTest output. For
example:
RuntimeError: Errors during teardown:
Process XXXX error: exit code 42, expected 0
GCC/Clang Thread Sanitizer (TSAN)
---------------------------------
This option turns on extra run time threading verification.
Applicable only to GCC versions >= 7.4 and Clang versions >= 6.0.
To enable the thread sanitizer set the RUNTIME_CHECK build flag to "tsan":
cmake .. -DRUNTIME_CHECK=tsan
The TSAN library (libtsan) must be installed in order to use this
option.
If threading violations are detected during the CTest suite the
qdrouterd process will exit with an exit code of 66. This will be
displayed in the CTest output. For example:
RuntimeError: Errors during teardown:
Process XXXX error: exit code 66, expected 0
False positives can be suppressed via the tsan.supp file in the tests
directory.
GCC/Clang Address Sanitizer (ASAN)
----------------------------------
This option turns on extra run time memory verification, including
leak checks.
Applicable only to GCC versions >= 5.4 and Clang versions >= 6.0.
To enable the address sanitizer set the RUNTIME_CHECK build flag to "asan":
cmake .. -DRUNTIME_CHECK=asan
The ASAN (libasan) and UBSAN (libubsan) libraries must be installed in
order to use this option.
False positive leak errors can be suppressed via the lsan.supp file in
the tests directory.