[PATCH] Edits and corrections to README file
Michael Schonberg <mschonberg@...>
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 |
|