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)
- python-unittest2 (python2-unittest2 on Fedora) (we use unittest2 for running python tests)

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.