NO-JIRA: README improvements * remove out-of-date product information from the README and include the more current information from the website * add a new INSTALL file to contain the build and install instructions from the existing README * move all development and testing related info from that to the DEVELOPERS file * better explain how to run the various test suites and how they work across proton-c and proton-j in the developers file * other misc improvements across the contents of the files * rename DEVELOPERS and INSTALL to have .md suffixes for better rendering on GitHub * add a symlink from README --> README.md for better landing page rendering on GitHub (cherry picked from commit b532cf25756424c840047ad039b5c43eeb864046) Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/e55079e9 Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/e55079e9 Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/e55079e9 Branch: refs/heads/0.9.x Commit: e55079e98390251fd176b13176de668d022b2ec3 Parents: cf12285 Author: Dominic Evans Authored: Fri Apr 24 12:14:17 2015 +0100 Committer: Robert Gemmell Committed: Mon Apr 27 15:12:49 2015 +0100 ---------------------------------------------------------------------- DEVELOPERS | 36 ------- DEVELOPERS.md | 85 ++++++++++++++++ INSTALL.md | 168 ++++++++++++++++++++++++++++++ README | 293 +++++++---------------------------------------------- README.md | 1 + 5 files changed, 291 insertions(+), 292 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e55079e9/DEVELOPERS ---------------------------------------------------------------------- diff --git a/DEVELOPERS b/DEVELOPERS deleted file mode 100644 index b0e0015..0000000 --- a/DEVELOPERS +++ /dev/null @@ -1,36 +0,0 @@ -Qpid Proton Developer Information -================================= - -DEVELOPMENT ENVIRONMENT -======================= - -To setup the variables for your development environment, simply source -the file $BLDDIR/config.sh [$BLDDIR points to the proton build directory]: - - $ source config.sh - -This file sets the needed environment variables for all supported dynamic -languages (Python, Perl, Ruby, PHP) as well as for Java and for testing. - -You will need to have set up the build directory first with cmake before the file -will exist (see the instructions in README). - - -MAILING LIST -============ - -Subscribe to the Qpid Proton mailing list here: - - http://qpid.apache.org/proton/mailing_lists.html - - - -PATCHES -======= - -The best way to submit patches it to create a bug report or feature request -on the project's JIRA instance: - - http://issues.apache.org/jira/browse/PROTON - -You can attach any patch(es) to the report/request there http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e55079e9/DEVELOPERS.md ---------------------------------------------------------------------- diff --git a/DEVELOPERS.md b/DEVELOPERS.md new file mode 100644 index 0000000..e8b1f3c --- /dev/null +++ b/DEVELOPERS.md @@ -0,0 +1,85 @@ +Qpid Proton Developer Information +================================= + +Please see http://qpid.apache.org/proton/development.html for the current +roadmap. + +Development Environment +----------------------- + +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 run Java +tests. + +First you will need to set up your basic build environment with cmake and all +prequisites (see the instructions in INSTALL) so that you can build the full +codebase + +To setup shell variables for your development environment, you must source +the file config.sh from the cmake build directory. + + $ cd build + $ source config.sh + +This file sets the needed environment variables for all supported dynamic +languages (Python, Perl, Ruby, PHP) as well as for Java and for testing. + +Testing +------- + +As a developer on proton, it is a good idea to build and test with the +appropriate dependencies and settings in place so that the complete set of +language bindings and implementations are present. There is a common test suite +that runs against both the proton-c and proton-j implementations to help keep +them in sync with each other - this is the python test suite that lives +underneath the top level `tests/python` directory. These tests have been +integrated into the maven build via Jython (and are hence included in the +proton-java ctest). When you run the python test suite in Jython, the swig +generated cproton doesn't actually exist since it is a C module. Instead, you +get the cproton.py that resides in the java source tree underneath +`proton-j/src/main/resources`. This cproton.py and its dependent files serve as +a shim that adapts between the Java API and the C API. + +### Running tests + +To test Proton you should use the CMake build. By default this will invoke the +maven tests as well, so the maven prerequisites are required in addition to the +cmake prerequisites. +To run the tests, cd into your build directory and use the following commands: + + # to run all the tests, summary mode + $ ctest + + # to list the available testsuites + $ ctest -N + + # to run a single testsuite, verbose output + $ ctest -V -R c-engine-tests + +Additional packages required for testing the language bindings: + + # ruby dependencies + $ yum install rubygem-minitest rubygem-rspec rubygem-simplecov + + # alternatively ruby depedencies on non-RPM based systems + $ gem install minitest rspec simplecov + + +Mailing list +------------ + +Subscribe to the Qpid Proton mailing list here: + + http://qpid.apache.org/proton/mailing_lists.html + + +Patches +------- + +The best way to submit patches is to create a bug report or feature request +on the project's JIRA instance: + + http://issues.apache.org/jira/browse/PROTON + +You can attach any patch(es) to the report/request there http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e55079e9/INSTALL.md ---------------------------------------------------------------------- diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..973a7bd --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,168 @@ +Qpid Proton Install Information +=============================== + +Proton comes with two separate build systems. The CMake build system can buildS +the entire codebase, including proton-c, all proton-c language bindings, and +the pure Java proton-j implementation. The maven build system can only build +the Java portions of the code. + +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. + +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. + +The following packages must be installed: + + - Visual Studio 2005 or newer (regular or C++ Express) + - Python (www.python.org) + - CMake (www.cmake.org) + +Additional packages are required for the language bindings + + - swig (www.swig.org) + - development headers and libraries for the language of choice + +Notes: + + - be sure to install relevant Microsoft Service Packs and updates + - python.exe, cmake.exe and swig.exe _must_ all be added to your PATH + +To generate the Visual Studio project files, from the directory where you found +this README file: + + > mkdir build + > cd build + > 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. + +Build and install from a command prompt (using msbuild) + > cmake --build . --target install --config RelWithDebInfo + +Loading the ALL_BUILD project into Visual Studio + + 1. Run the Microsoft Visual Studio IDE + 2. From within the IDE, open the ALL_BUILD project file or proton + solution file - it should be in the 'build' directory you created + above. + 3. Select the appropriate configuration. RelWithDebInfo works best + with the included CMake/CTest scripts + +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. + +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 envvar 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 + +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 + http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e55079e9/README ---------------------------------------------------------------------- diff --git a/README b/README index f7ce39f..c1d2bbf 100644 --- a/README +++ b/README @@ -1,259 +1,40 @@ -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) +Qpid Proton - AMQP messaging toolkit +==================================== + +Qpid Proton is a high-performance, lightweight messaging library. It can be +used in the widest range of messaging applications, including brokers, client +libraries, routers, bridges, proxies, and more. Proton makes it trivial to +integrate with the AMQP 1.0 ecosystem from any platform, environment, or +language + +Features +-------- + + + A flexible and capable reactive messaging API + + Full control of AMQP 1.0 protocol semantics + + Portable C implementation with bindings to popular languages + + Pure-Java and pure-JavaScript implementations + + Peer-to-peer and brokered messaging + + Secure communication via SSL and SASL + +Universal - Proton is designed to scale both up and down. Equally suitable for +simple clients or high-powered servers, it can be deployed in simple +peer-to-peer configurations or as part of a global federated messaging network. + +Embeddable - Proton is carefully written to be portable and cross platform. It +has minimal dependencies, and it is architected to be usable with any threading +model, as well as with non-threaded applications. These features make it +uniquely suited for embedding messaging capabilities into existing software. + +Standard - Built around the AMQP 1.0 messaging standard, Proton is not only +ideal for building out your own messaging applications but also for connecting +them to the broader ecosystem of AMQP 1.0-based messaging applications. + +Getting Started --------------- -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: +See the included INSTALL file for build and install instructions and the +DEVELOPERS file for information on how to modify and test the library code +itself. - - 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 +Please see http://qpid.apache.org/proton for a more info. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e55079e9/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md new file mode 120000 index 0000000..100b938 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +README \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org For additional commands, e-mail: commits-help@qpid.apache.org