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 <dominic.evans@uk.ibm.com>
Authored: Fri Apr 24 12:14:17 2015 +0100
Committer: Robert Gemmell <robbie@apache.org>
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
|