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


Using Valgrind
==============

If valgrind is installed and cmake option 'USE_VALGRIND' is 'ON' the tests will
be run with valgrind's memcheck debugger. You can set other types of test runner
or modify the valgrind flags by setting the TEST_RUNNER cmake variable.