README - qpid-dispatch - Git at Google

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