| Proton Project |
| ============== |
| |
| 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 |