README

Qpid Proton
===========

Proton is a library for speaking AMQP, including:

  + The AMQP Messenger API, a simple but powerful interface to send and receive
    messages over AMQP.
  + The AMQP Protocol Engine, a succinct encapsulation of the full
    AMQP protocol machinery.

Proton is designed for maximum embeddability:

  + minimal dependencies
  + minimal assumptions about application threading model

Proton is designed to scale up and down:

  + transparently supports both simple peer to peer messaging and complex
    globally federated topologies

Proton is multi-lingual:

  + Proton-C - a C implementation with language bindings in Python,
               Php, Perl, and Ruby
  + Proton-J - a pure Java implementation

Please see http://qpid.apache.org/proton for a more info.

Build Instructions
==================

Proton comes with two separate build systems. The CMake build system
builds the entire codebase including the C implementation, all the
bindings of the C implementation, and the pure Java implementation.

The maven build system builds only the Java portions of the code.
Developers wishing to work across multiple languages should become
familiar with the cmake build system as this will build and run all
available tests and code whereas the maven build system only runs Java
tests.

CMake (Linux)
-------------

The following prerequisites are required to do a full build. If you do
not wish to build a given language binding you can omit the devel
package for that language:

    # required dependencies
    yum install gcc cmake libuuid-devel

    # dependencies needed for ssl support
    yum install openssl-devel

    # dependencies needed for bindings
    yum install swig python-devel ruby-devel php-devel perl-devel

    # dependencies needed for java (note that any non-ancient jvm will
    # work, 1.8.0 is just what is current for fedora 20)
    yum install java-1.8.0-openjdk-devel

    # dependencies needed for python docs
    yum install epydoc

From the directory where you found this README file:

    mkdir build
    cd build

    # Set the install prefix. You may need to adjust depending on your
    # system.
    cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DSYSINSTALL_BINDINGS=ON

    # Omit the docs target if you do not wish to build or install
    # documentation.
    make all docs

    # Note that this step will require root privileges.
    make install

When make install completes, all installed files are listed in the
install_manifest.txt file. The contents of this file may be used to
uninstall.

Note: When SYSINSTALL_BINDINGS is enabled (ON), the
CMAKE_INSTALL_PREFIX does not affect the location for where the
language bindings (Python, Perl, PHP, Ruby) are installed. For those
elements, the location is determined by the language interpreter
itself; i.e., each interpreter is queried for the proper location for
extensions. If you want to constrain where the Proton code is
installed, set SYSINSTALL_BINDINGS to OFF. This will install all
bindings to a common location under ${CMAKE_INSTALL_PREFIX}. When
installed like this, each user will need to manually configure their
interpreters with the respective binding location.

Installing Language Bindings
----------------------------

Most dynamic languages provide a way for asking where to install
libraries in order to place them in a default search path.

When SYSINSTALL_BINDINGS is disabled (OFF), Proton installs all
dynamic language bindings into a central, default location:

    BINDINGS=${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR}/proton/bindings

In order to use these bindings, you'll need to configure your
interpreter to load the bindings from the appropriate directory:

 * Perl   - Add ${BINDINGS}/perl to PERL5LIB
 * PHP    - Set the PHPRC environment variable to point to
            ${BINDINGS}/php/proton.ini
 * Python - Add ${BINDINGS}/python to PYTHONPATH
 * Ruby   - Add ${BINDINGS}/ruby to RUBYLIB

You can configure the build to install a specific binding to the
location specified by the system interpreter with the
SYSINSTALL_[LANGUAGE] options, where [LANGUAGE] is one of JAVA, PERL,
PHP, PYTHON, or RUBY.:

    cmake .. -DSYSINSTALL_PHP=ON

Disabling Language Bindings
---------------------------

To disable any given language bindings, you can use the
BUILD_[LANGUAGE] option where [LANGUAGE] is one of JAVA, PERL, PHP,
PYTHON or RUBY, e.g.:

    cmake .. -DBUILD_PHP=OFF

CMake (Windows)
---------------

This describes how to build the Proton library on Windows using
Microsoft Visual C++.

The Proton build uses the cmake tool to generate the Visual Studio
project files. These project files can then be loaded into Visual
Studio and used to build the Proton library.

These instructions assume use of a command shell. If you use the
Visual Studio supplied Command Prompt, cmake is even more likely to
guess the intended compiler.

The following packages must be installed:

  - Visual Studio 2005 or newer (regular or C++ Express)
  - Python (www.python.org)
  - Cmake (www.cmake.org)

The following packages are optionally required in order to run the
python or java driven test suites:

  - swig (www.swig.org)

Notes:

  - be sure to install relevant Microsoft Service Packs and updates
  - python.exe _must_ be in your path
  - cmake.exe _must_ be in your path
  - swig.exe optional (but should be in your path for building test
    modules)

### Step 1:

Create a 'build' directory - this must be at the same level as the
'proton-c' directory. For example, from the directory where you found
this README file:

    > mkdir build

### Step 2:

  cd into the build directory

    > cd build

### Step 3:

Generate the Visual Studio project files using cmake. The command
contains:

  1. the name of the compiler you are using (if cmake guesses wrongly)
  2. the path (required) to the _directory_ that contains the top
     level "CMakeLists.txt" file (the parent directory, in this case).

  Example:

    > cmake ..

  If cmake doesn't guess things correctly, useful additional arguments
  are:

    -G "Visual Studio 10"
    -DSWIG_EXECUTABLE=C:\swigwin-2.0.7\swig.exe

  Refer to the cmake documentation for more information.

### Step 4:

Load the ALL_BUILD project into Visual Studio

  a. Run the Microsoft Visual Studio IDE
  b. From within the IDE, open the ALL_BUILD project file or proton
     solution file - it should be in the 'build' directory you created
     above.
  c. select the appropriate configuration. RelWithDebInfo works best
     with the included CMake/CTest scripts

### Step 5:

Build the ALL_BUILD project.

Note that if you wish to build debug version of proton for use with
swig bindings on Windows, you must have the appropriate debug target
libraries to link against.

Maven (All platforms)
---------------------

The following prerequesuites are required to do a full build.

  + Apache Maven 3.0 (or higher) (http://maven.apache.org/)

From the directory where you found this README file:

    # To compile and package all Java modules (omitting the tests)
    mvn -DskipTests package

    # To install the packages in the local Maven repository (usually ~/.m2/repo)
    mvn -DskipTests install

Testing
=======

Additional packages required for testing:

    yum install rubygem-minitest rubygem-rspec rubygem-simplecov

On non-RPM based systems, you can install them using:

    gem install minitest rspec simplecov

To test Proton, use the cmake build and run 'make test'. Note that
this will invoke the maven tests as well, so the maven prerequisites
are required in addition to the cmake prerequisites.

Running Tests
-------------

To run the system tests using the CMake build system, cd into your
build directory and use the following commands:

    # to run all the tests, summary mode
    ctest

    # to run a single test, full output
    ctest -V -R proton-c