From: Mike Schonberg <mschonberg@...>

Adding edits and corrections suggested by a technical writer who reviewed the
README file.

Signed-off-by: Michael Schonberg <mschonberg@...>
---
README | 184 +++++++++++++++++++++++++++++++++++-----------------------------
1 files changed, 100 insertions(+), 84 deletions(-)

diff --git a/README b/README
index 68a443e..5ebfa70 100644
--- a/README
+++ b/README
@@ -1,41 +1,42 @@
OpenMAMA Client Library
============================

-http://
+Project Page
+------------
+
+http://www.openmama.org

Overview
--------

-OpenMAMA provides a lightweight wrapper to give a common API interface
-across different middleware and messaging solutions across a variety of
-platforms and languages.
+OpenMAMA is a lightweight wrapper that provides a common API interface to
+different middleware and messaging solutions across a variety of platforms and
+languages.

-Please see the project page above for more information as well as the
-mailing list for questions, discussions, and development.
+Please see the project page above for more information, as well as the mailing
+list for questions, discussions, and development.

Supported Platforms
-------------------

-Currently C on Linux is the only supported platform. Supported
-distributions are
+Currently C on Linux is the only supported platform. Supported distributions
+are

* Redhat 4
* Redhat 5
* SLERT
* SuSe 10

-
Requirements for End Users
--------------------------

-OpenMama is designed to have fairly minimal requirements to build,
-but there are some.
+OpenMAMA is designed to have minimal build requirements.

Linux
-----

-These are the base requirements to build and use OpenMama from a source
-package (as described below):
+These are the base requirements to build and use OpenMAMA from a source package
+(as described below):

* GNU-compatible Make or gmake
* POSIX-standard shell
@@ -46,22 +47,22 @@ package (as described below):
* libtool
* uuid-dev

-To use OpenMama you will need a middleware/payload. An example
-middleware bridge and payload is included for Avis which can be
-obtianed from the following website.
+To use OpenMAMA you will need a middleware/payload. An example middleware
+bridge and payload is included for Avis. Avis can be obtained from the following
+website:

http://avis.sourceforge.net.

-OpenMAMA reference documentation has dependancy on
+OpenMAMA API reference documentation depends on:

* doxygen

-Unittests are dependant on Google Testing Framework which is
-available from
+Unittests are dependent on the Google Testing Framework, which is available
+from:

http://code.google.com/p/googletest/

-OpenMAMA's own regression tests also relie on
+OpenMAMA's own regression tests also rely on:

*Python version 2.3 or newer

@@ -72,21 +73,20 @@ Getting the Source
There are two primary ways of getting OpenMAMA's source code:

* Download a stable source release in archive format
- * check out the source from our GIT repositary.
+ * Check out the source from our GIT repository.

-The GIT checkout requires a few extra steps and some extra software
-packages on your system, but lets you track the latest development and
-make patches much more easily.
+The GIT checkout requires a few extra steps, and extra software packages to be
+installed on your system. However, it provides easier tracking of the latest
+development and make patches.

### Source Package ###

-OpenMAMA is released in versioned source packages which can be
-downloaded from:
+OpenMAMA is released in versioned source packages which can be downloaded from:

- http://
+ http://www.openmama.org/downloads

-Once the package is downloaded, expand it. This will result in a
- new directory with the name
+Once the package is downloaded, expand it. This will result in a new directory
+with the name

openmama-X.Y.Z

@@ -94,9 +94,9 @@ which contains all of the source code.

### GIT Checkout ###

-To check out the main branch of OpenMAMA, run the following
-GIT command:
+To check out the main branch of OpenMAMA, run the following GIT command:

+ git clone http://git.openmama.org/OpenMAMA-1.1.git

Distribution Layout
-------------------
@@ -117,19 +117,19 @@ mama/c_cpp/
configure.ac autoconf script
Makefile.am autoconf makefile
doxyconfig-c.in doxygen config
- doc referance guide style
- doc/images referance guide images
+ doc reference guide style
+ doc/images reference guide images

mama/c_cpp/src/c c files for mama library
bridge/avis c files for avis middleware bridge implementation
conflation c files for mama conflation component
mama header files for mama
payload/avismsg c files for avis payload bridge implementation
- payload/playback c files for mama playback component
+ playback c files for mama playback component


mama/c_cpp/src/examples
- mama.properties exmaple mama.properties file
+ mama.properties example mama.properties file
c c files for mama example applications
c/Makefile.sample Makefile to build examples only

@@ -138,11 +138,10 @@ mama/c_cpp/src/examples
c/tools test apps for c API
c/* tests and expected results for c API

- mama/c_cpp/src/testtools
- c test tools for c API
- c/capturereplay capture adn replay apps using c API
- c/load load testing apps for c API
- c/performance performance testing apps for c API
+ mama/c_cpp/src/testtools test tools for c API
+ capturereplay capture and replay apps using c API
+ load load testing apps for c API
+ performance performance testing apps for c API


Building OpenMAMA
@@ -150,13 +149,13 @@ Building OpenMAMA

### Avis Install ###

-Curretnly OpenMAMA assumes Avis is the middleware to be built with as
-this is currently the only opensource middleware supported. Therefore
-the Avis client libraries must be available.
+Currently OpenMAMA assumes Avis is the middleware to be built with as this is
+currently the only opensource middleware supported. Therefore the Avis client
+libraries must be available.

-The default install of Avis missing a header file and this needs to be
-moved manually in the include directory. The OpenMAMA configure script
-checks for this header and will exit with an error if not found.
+The default install of Avis is missing a header file. This needs to be moved
+manually in the include directory. The OpenMAMA configure script checks for
+this header and will exit with an error if not found.

mv ${AVIS_SOURCE}/lib/avis_client_config.h ${AVIS_HOME}/include/avis

@@ -164,8 +163,8 @@ checks for this header and will exit with an error if not found.

### Google Test Install ###

-OpenMAMA uses the static google test library and expects the files to be
-in the following format.
+OpenMAMA uses the static google test library and expects the files to be in the
+following format.

${GTEST_HOME}/include - include files
${GTEST_HOME}/lib - library files
@@ -174,9 +173,9 @@ ${GTEST_HOME}/lib - library files

### GNU Automake Instructions ###

-The following uses teh defualt settings to build the OpenMAMA library
-and exmaple applications. This assumes that Avis middleware is avialble
-in /usr/local and will install OpenMAMA to /opt/OpenMAMA
+The following uses the default settings to build the OpenMAMA library and
+example applications. This assumes that Avis middleware is available in
+/usr/local, and will install OpenMAMA to /opt/OpenMAMA

./configure
make
@@ -185,43 +184,42 @@ in /usr/local and will install OpenMAMA to /opt/OpenMAMA

### Configure arguments ###

-The following arguments can be passed to configure if you wish to use
-non-default paths or build extra components of OpenMAMA
+The following arguments can be passed to the configure script if you wish to use
+non-default paths, or build extra components of OpenMAMA:

-specify an alternative install location
+specify an alternative install location:
--prefix=${INSTALL_DIR}

-specify non defualt Avis install
+specify non default Avis install:
--avis-path=${AVIS_HOME}

-build unittests, specify google test location
+build unittests, specify google test location:
--gtest-path=${GTEST_HOME}

-build testtools
+build testtools:
--with-testtools


### Building reference guide ###

- If you wish to build the latest refernce guide use the following command
- after configure
+To build the latest reference guide, use the following command after Configure:

make docs

- This will build the docs in the mama/c_cpp/src/doc folder.
+This will build the docs in the mama/c_cpp/src/doc folder.


### Running Unit tests ###

- After the build is complete an extra binary can be found in the bin
- folder of the install.
+After the build is complete an extra binary can be found in the bin folder of
+the install.

MainUnitTestC

- This runs the full set of unit tests using the google test framework.
+This runs the full set of unit tests using the google test framework.

- The following commar line arguments are available as well as the
- normal google test options
+The following command line arguments are available, as well as the normal Google
+test options:

-m ${MIDDLEWARE}

@@ -229,34 +227,55 @@ build testtools

### Running regression tests ###

- The regression tests do full end to end testing using a specific set of test
- applications and a predetermined input output scenario.
+The regression tests do full end to end testing using a specific set of test
+applications and a predetermined input output scenario.

- In-order to run the regression scripts an elvin router must be available. If
- it is not running on the defaulkt port on localhost then the mama.properties
- file provided in examples should be used with the ${WOMBAT_PATH} variable to
- give the location of the router.
+In-order to run the regression scripts Avis should be running on the same
+machine with the elvin router listening on the default port on localhost. If it
+is not running on the default port on localhost, then the mama.properties file
+provided in examples should be used with the ${WOMBAT_PATH} variable to give the
+location of the router.

- To build the regression tests move into teh regression/tols folder. Modify
- the makefile with your install path if is non-default. The execute the following commnad
+NOTE: The publish/subscribe regression test is based on comparing the output
+file against an expected results file. The intial expected results file should
+be created by running the test with unmodified OpenMAMA code - steps listed
+below.

- make
+Setting up regression tests:
+1) Build required binaries:
+ - cd src/regression/c/tools
+ - Edit Makefile: Set API_HOME to the path of the build/root directory of built API
+
+2) Run 'make'.
+
+3) Set AVIS_PATH:
+ - export AVIS_PATH=/path_to_avis_client
+ eg. export AVIS_PATH=/usr/local/avis-client-1.2.4

- After the tests apps are sucessfully built move into the directory of the
- test you wish to run and execute the python file
+4) Set OPENMAMA_PATH:
+ - export OPENMAMA_PATH=/path_to_openmama_build_directory
+ eg. export OPENMAMA_PATH=/usr/local/openmama/build

- eg
- cd ../basicpubsub
- ./regression.sh
+5) Set PYTHON_PATH:
+ - export PYTHON_PATH=/path_to_python_binary
+ eg. export PYTHON_PATH=/usr/bin/python2.4

+6) Run the test script:
+ - cd src/regression/c/basicpubsub
+ - run regression.sh

- NOTE: python 2.3 or higher required for regression tests
+7) FOR THE FIRST RUN OF TESTS create the expectedsub_out file
+ - after step 6) create the expectedsub_out from the sub_out file
+ ie. mv sub_out expectedsub_out
+ - run step 6) again to run tests
+
+ NOTE: python 2.3 or higher required for regression tests.


Contributing
-------------

-
+see: www.openmama.org

License
--------
@@ -264,6 +283,3 @@ build testtools
The OpenMAMA library is distributed under the terms of the GNU
Lesser General Public license version 2. Please see COPYING
for full licence text.
-
-
-
--
1.7.5.4