qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rob...@apache.org
Subject [11/11] qpid-proton git commit: NO-JIRA: README improvements
Date Mon, 27 Apr 2015 15:06:15 GMT
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


Mime
View raw message