README.adoc - qpid-dispatch - Git at Google

 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
 // regarding copyright ownership.  The ASF licenses this file
 // to you under the Apache License, Version 2.0 (the
 // "License"); you may not use this file except in compliance
 // with the License.  You may obtain a copy of the License at
 //
 //   http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing,
 // software distributed under the License is distributed on an
 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.

 = Qpid Dispatch

 image:https://github.com/apache/qpid-dispatch/actions/workflows/build.yaml/badge.svg[
 "GitHub Actions"
 link="https://github.com/apache/qpid-dispatch/actions/workflows/build.yaml"]
 image:https://img.shields.io/travis/apache/qpid-dispatch.svg?logo=travisci[
 "Travis",
 link="https://travis-ci.com/apache/qpid-dispatch"]
 image:https://img.shields.io/github/license/apache/qpid-dispatch.svg[
 "License",
 link="https://github.com/apache/qpid-dispatch/blob/main/LICENSE"]

 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.

 == Building and testing

 NOTE: Dispatch will not build on Windows.

 === Dependencies

 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`

 === Build

 From the `qpid-dispatch` directory:

 [source,shell script]
 ----
 $ 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 unit-tests with:
 [source,shell script]
 ----
 $ 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.

 .Example
 [source,shell script]
 ----
 $ ./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:
 [source,shell script]
 ----
 $ ./run.py
 ----

 === Test-only dependencies

 Websocket system tests use the Python websockets asyncio module.

 .Install websockets
 [source,shell script]
 ----
 pip3 install --user websockets
 ----

 The 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:

 [source,shell script]
 ----
 cmake .. -DPYTHON_TEST_COMMAND='-m;pytest;-vs;--junit-xml=junitxmls/${py_test_module}.xml;--pyargs;${py_test_module}'
 ----

 === Runner for `skrouterd` in tests

 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.

 [source,shell script]
 ----
 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"
 ----

 === 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:

 1. install the lcov package
 [source,shell script]
 $ yum install lcov

 2. configure and build for the Coverage build type (from the <build> directory):
 [source,shell script]
 $ cmake -DCMAKE_BUILD_TYPE=Coverage .. && make

 3. run the test suite and generate the coverage html output
 [source,shell script]
 $ ctest && make coverage

 4. then point your browser at `<build>/coverage_results/html/index.html`

 === Clean build, install and test
 [source]
 ----
 $ 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'.

 === 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: 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
 [source,shell script]
 ----
 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":

 [source,shell script]
 ----
 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:

 [source]
 ----
 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.

 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":

 [source,shell script]
 ----
 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:

 [source]
 ----
 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.

 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":

 [source,shell script]
 ----
 cmake .. -DCMAKE_C_FLAGS=-DQD_MEMORY_DEBUG -DRUNTIME_CHECK=asan
 ----

 On Aarch64, a hardware-assisted address sanitizer is enabled with "hwasan":

 [source,shell script]
 ----
 cmake .. -DCMAKE_C_FLAGS=-DQD_MEMORY_DEBUG -DRUNTIME_CHECK=hwasan
 ----

 The 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.


 === CMake Build Options

 Use `cmake-gui` to explore the CMake build options available.
 Existing build directory can be opened with `cmake-gui -S .. -B .`

 |===
 |CMake option| Description

 |`-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`.

 |`-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.

 |`-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON`
 |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.
 |===
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.

	= Qpid Dispatch

	image:https://github.com/apache/qpid-dispatch/actions/workflows/build.yaml/badge.svg[
	"GitHub Actions"
	link="https://github.com/apache/qpid-dispatch/actions/workflows/build.yaml"]
	image:https://img.shields.io/travis/apache/qpid-dispatch.svg?logo=travisci[
	"Travis",
	link="https://travis-ci.com/apache/qpid-dispatch"]
	image:https://img.shields.io/github/license/apache/qpid-dispatch.svg[
	"License",
	link="https://github.com/apache/qpid-dispatch/blob/main/LICENSE"]

	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.

	== Building and testing

	NOTE: Dispatch will not build on Windows.

	=== Dependencies

	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`

	=== Build

	From the `qpid-dispatch` directory:

	[source,shell script]
	----
	$ 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 unit-tests with:
	[source,shell script]
	----
	$ 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.

	.Example
	[source,shell script]
	----
	$ ./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:
	[source,shell script]
	----
	$ ./run.py
	----

	=== Test-only dependencies

	Websocket system tests use the Python websockets asyncio module.

	.Install websockets
	[source,shell script]
	----
	pip3 install --user websockets
	----

	The 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:

	[source,shell script]
	----
	cmake .. -DPYTHON_TEST_COMMAND='-m;pytest;-vs;--junit-xml=junitxmls/${py_test_module}.xml;--pyargs;${py_test_module}'
	----

	=== Runner for `skrouterd` in tests

	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.

	[source,shell script]
	----
	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"
	----

	=== 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:

	1. install the lcov package
	[source,shell script]
	$ yum install lcov

	2. configure and build for the Coverage build type (from the <build> directory):
	[source,shell script]
	$ cmake -DCMAKE_BUILD_TYPE=Coverage .. && make

	3. run the test suite and generate the coverage html output
	[source,shell script]
	$ ctest && make coverage

	4. then point your browser at `<build>/coverage_results/html/index.html`

	=== Clean build, install and test
	[source]
	----
	$ 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'.

	=== 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: 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
	[source,shell script]
	----
	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":

	[source,shell script]
	----
	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:

	[source]
	----
	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.

	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":

	[source,shell script]
	----
	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:

	[source]
	----
	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.

	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":

	[source,shell script]
	----
	cmake .. -DCMAKE_C_FLAGS=-DQD_MEMORY_DEBUG -DRUNTIME_CHECK=asan
	----

	On Aarch64, a hardware-assisted address sanitizer is enabled with "hwasan":

	[source,shell script]
	----
	cmake .. -DCMAKE_C_FLAGS=-DQD_MEMORY_DEBUG -DRUNTIME_CHECK=hwasan
	----

	The 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.


	=== CMake Build Options

	Use `cmake-gui` to explore the CMake build options available.
	Existing build directory can be opened with `cmake-gui -S .. -B .`

	\|===
	\|CMake option\| Description

	\|`-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`.

	\|`-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.

	\|`-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON`
	\|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.
	\|===