Qpid Dispatch is a high-performance, lightweight AMQP 1.0 message router. It provides flexible and scalable interconnect between any AMQP endpoints, whether they be clients, brokers or other AMQP-enabled services.
|
Note
|
Dispatch will not build on Windows. |
To build dispatch on a yum-based Linux system, you will need the following packages installed:
-
qpid-proton-c-devel
-
python3-qpid-proton
-
cmake
-
make
-
gcc
-
python3-devel
-
cyrus-sasl-plain
-
cyrus-sasl-devel
-
asciidoc (for building docs)
-
asciidoctor (for building docs)
To build formatted documentation (man pages, HTML, PDF) see the requirements in doc/README.adoc
From the qpid-dispatch directory:
$ mkdir my_build # or directory of your choice.
$ cd my_build
$ cmake ..
$ makeFrom the <build> directory you can run all the system- and unit-tests with:
$ ctest -VVctest 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.
$ ./run.py unit_tests_size 3
$ ./run.py -m unittest system_tests_qdstatRun it without arguments to get a summary of how it can be used:
$ ./run.pyWebsocket system tests use the Python websockets asyncio module.
pip3 install --user websocketsThe system tests are implemented using Python’s unittest library. This library is
used to run the tests by default. The tests can be also run using xmlrunner or pytest.
Pytest can generate a JUnit-compatible XML report containing an entry for each Python test method.
After running the tests, all XML reports will be found under tests/junitxmls in your build directory:
cmake .. -DPYTHON_TEST_COMMAND='-m;pytest;-vs;--junit-xml=junitxmls/${py_test_module}.xml;--pyargs;${py_test_module}'System tests can be configured to run skrouterd processes with an arbitrary wrapper.
To do this, set the QDROUTERD_RUNNER CMake option to a string that will be prepended before all skrouterd invocations during testing.
The following example illustrates how to run the router under gdb, to obtain a backtrace if the router crashes.
cmake .. -DQDROUTERD_RUNNER="gdb -quiet -iex 'set pagination off' -iex 'set debuginfod enabled on' -ex run -ex 'thread apply all bt' -ex 'quit $_exitcode' --batch --args"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
$ source config.sh; test.sh|
Warning
|
Any preexisting directories 'build' and 'install' will be deleted. |
This script then does the following:
-
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'.
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
|
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.
|
ctest --timeout 1500 -VVThe Qpid Dispatch Router test suite supports the following run time validation tools:
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=memcheckIf 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 0This option turns on extra run time threading verification.
|
Note
|
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=tsanThe 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 0False positives can be suppressed via the tsan.supp file in the tests
directory.
This option turns on extra run time memory verification, including leak checks.
|
Note
|
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 .. -DCMAKE_C_FLAGS=-DQD_MEMORY_DEBUG -DRUNTIME_CHECK=asanOn Aarch64, a hardware-assisted address sanitizer is enabled with "hwasan":
cmake .. -DCMAKE_C_FLAGS=-DQD_MEMORY_DEBUG -DRUNTIME_CHECK=hwasanThe ASAN (libasan) and UBSAN (libubsan) libraries must be installed in order to use this option.
|
Note
|
Memory pool will produce false leak reports unless QD_MEMORY_DEBUG
is also defined.
|
False positive leak errors can be suppressed via the lsan.supp file in the tests directory.
Use cmake-gui to explore the CMake build options available.
Existing build directory can be opened with cmake-gui -S .. -B .
| CMake option | Description |
|---|---|
|
Dispatch defaults to building with the |
|
Seting this to |
|
Web console will not be built if this is set to |
|
Enables C/C++ runtime checkers.See "Run Time Validation" chapter above. |
|
With CMake 3.9+, compiles the project with LTO (Link Time Optimization) enabled. Older CMake will only honor this option with the Intel compiler on Linux. |