| Qpid Dispatch |
| ============= |
| |
| 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. |
| |
| 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 |
| - libnghttp2-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 |
| |
| The HTTP2 system tests (tests/system_tests_http2.py) use the Python Quart framework to start a HTTP2 server. |
| The HTTP2 system tests will run only if |
| 1. Python version >= 3.7 |
| 2. Python Web Microframework Quart version >= 0.13 |
| 3. curl is available |
| |
| The TCP system tests (tests/system_tests_tcp_adaptor.py) use the |
| Python selectors module when running echo clients and servers. |
| The TCP system tests run only if Python selectors is available. |
| |
| To install pip, Quart, and selectors |
| - curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py |
| - python3 get-pip.py |
| - pip3 install --user quart |
| - pip3 install --user selectors |
| |
| The gRPC system tests (tests/system_tests_grpc.py) use grpcio and protobuf modules. |
| To install them use: |
| - pip3 install --user grpcio protobuf |
| In order to regenerate the auto generated pb2 files used by system_tests_grpc.py, |
| you must also install the following dependency: |
| - pip3 install --user grpcio-tools |
| And run the following command to generate grpc code: |
| - python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. ./friendship.proto |
| |
| |
| 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. |
| |
| |
| CMake Build Options |
| =================== |
| |
| Use `cmake-gui` to explore the CMake build options available. |
| Existing build directory can be opened with `cmake-gui -S .. -B .` |
| |
| -DCMAKE_BUILD_TYPE= |
| ------------------- |
| |
| Dispatch defaults to building with the `RelWithDebInfo` CMake preset. |
| Other options include `Debug` (disables optimizations) and `Coverage`. |
| |
| -DQD_ENABLE_ASSERTIONS= |
| ----------------------- |
| |
| Seting this to `ON` enables asserts irrespective of `CMAKE_BUILD_TYPE`. |
| |
| -DQD_MEMORY_STATS= |
| ------------------ |
| |
| Dispatch will track memory pool usage statistics if this is enabled. |
| |
| -DCONSOLE_INSTALL= |
| ------------------ |
| |
| Web console will not be built if this is set to `OFF`. |
| |
| -DRUNTIME_CHECK= |
| ---------------- |
| |
| Enables C/C++ runtime checkers. See "Run Time Validation" chapter above. |