OpenMAMA Client Library ============================ Release: 2.3.3 Change Log: http://git.openmama.org/?p=OpenMAMA.git;a=shortlog;h=refs/heads/OpenMAMA-2.3.3-release Project Page ------------ http://www.openmama.org Overview -------- OpenMAMA is a lightweight wrapper that provides a common API interface to different middleware and messaging solutions across a variety of platforms and languages. OpenMAMDA is a framework that adds Market Data functionality, such as order book handling on top of MAMA. Please see the project page above for more information, as well as the mailing list for questions, discussions, and development. Supported Platforms ------------------- Currently C, C++ and JNI/Java on Linux and Windows are the supported platforms. Supported distributions are * Redhat 4 * Redhat 5 * Redhat 6 * SLERT * SuSe 10 * Windows XP + * Java SE 6 (from Oracle) Requirements for End Users -------------------------- 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): * GNU-compatible Make or gmake * POSIX-standard shell * C99 compiler * Apache Ant (for JNI/Java builds) * gnu flex (fast lexical analyzer) available from http://flex.sourceforge.net or as part of many Linux distributions To use OpenMAMA you will need a middleware/payload. Example middleware bridges and payloads are included for Avis and QPID. These middlewares can be obtained from the following websites: http://avis.sourceforge.net http://qpid.apache.org/proton OpenMAMA API reference documentation depends on: * doxygen (C/C++) Unit tests are dependent on the Google Testing Framework (C/C++) or JUnit (JNI/Java), which are available from: http://code.google.com/p/googletest/ http://www.junit.org/ OpenMAMA's own regression tests also rely on: * Python version 2.3 or newer The Qpid Proton middleware has an additional dependency on the libevent event management library, which is used for it's IO implementation. Windows ----- Visual Studio 8 or later Getting the Source ------------------ Use one of the following methods to obtain the OpenMAMA source code: * Download a stable source release in archive format * Check out the source from our GIT repository. 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 that can be downloaded from: http://www.openmama.org/downloads Once the package is downloaded, extract it. The following directory, containing all the source code, will be created: openmama-X.Y.Z ### GIT Checkout ### To check out the main branch of OpenMAMA, complete the instructions on the following site: http://www.openmama.org/downloads/git-repository The primary OpenMAMA git repository is located at: http://git.openmama.org/OpenMAMA.git Navigating to the site will also allow interactive web access to the repository. OpenMAMA Directory Structure ---------------------------- configure configure script. Makefile GNU Makefile README this file COPYING Licence SConstruct Main entry point for SCons build system site_scons Additional code used for SCons build system common/c_cpp/ configure.ac autoconf script Makefile.am autoconf makefile Makefile.common.vcc windows makefile SConscript Configuration and setup for common SCons build SConscript.win Equivalent for Windows builds src/c/ c files for common library src/c/linux/ linux specific c files for common library src/c/windows/ windows specific c files for common library src/c/windows/wombat/ windows specific header for common library src/c/wombat/ header files for common library src/cpp/ cpp files for common library src/cpp/wombat/ cpp header files for common library common/jni/ src/com/wombat/common/ java files for common library mama/c_cpp/ configure.ac autoconf script Makefile.am autoconf makefile Makefile.base.vcc windows makefile Makefile.bridge.vcc windows makefile Makefile.mama.vcc windows makefile Makefile.mamac.vcc windows makefile Makefile.mamacpp.vcc windows makefile Makefile.mak windows makefile doxyconfig-c.in doxygen config for C reference guide doxyconfig-cpp.in doxygen config for C++ reference guide SConscript Configuration and setup for MAMA SCons build SConscript.win Equivalent SCons file for Windows build doc/ doc/images/ reference guide images mama/c_cpp/src/c/ c files for mama C library bridge/avis/ c files for avis middleware bridge bridge/qpid/ c files for qpid proton middleware bridge conflation/ c files for mama conflation component mama/ header files for mama payload/avismsg/ c files for avis payload bridge implementation payload/qpidmsg/ c files for qpid proton payload bridge implementation playback/ c files for mama playback component mama/c_cpp/src/cpp/ cpp files for mama C++ library conflation cpp files for mama conflation component fieldcache cpp files for mama fieldcache component fieldcache/mama header files for mama fieldcache component mama header files for mama mama/c_cpp/src/examples/ mama.properties example mama.properties file c/ c files for mama example applications c/Makefile.sample Makefile to build C examples only cpp/ cpp files for mama example applications cpp/Makefile.sample Makefile to build C++ examples only cpp/perf/ mama/c_cpp/src/gunittest/ c/ c files for mama gunittest applications cpp/ cpp files for mama gunittest applications mama/c_cpp/src/regression/ c_cpp/scripts/ regression scripts for C and C++ c_cpp/tools/ regression tests for C and C++ mama/c_cpp/src/testtools/ test tools for c++ API capturereplay/c/ capture and replay apps using C API load/c/ load testing apps for C API load/cpp/ load testing apps for C++ API performance/c/ performance testing apps for C API performance/cpp/ performance testing apps for C++ API mama/jni/ build.xml java build file configure.ac autoconf script Makefile.am autoconf makefile Makefile.vcc windows makefile SConscript Configuration and setup for MAMA JNI SCons build SConscript.win Equivalent SCons file for Windows builds doc/ reference guide files mama/jni/src/c/ c files for mama JNI library Makefile.am autoconf makefile mamajni/ header files for mamajni mama/jni/src/com/wombat/mama/ java files for mama JNI library examples/ java files for mama example applications testtools/load/ load testing apps for JNI api testtools/performance/ performance testing apps for JNI api mama/jni/src/junittests/ java unittests mama/jni/src/regression/ scripts/ regression scripts for java tools/ regression tests for java mamda/c_cpp/ configure.ac autoconf script Makefile.am autoconf makefile Makefile.base.vcc windows makefile Makefile.mamda.vcc windows makefile Makefile.news.vcc windows makefile Makefile.options.vcc windows makefile Makefile.orderbooks.vcc windows makefile Makefile.mak windows makefile SConscript Configuration and setup for MAMDA SCons build SConscript.win Equivalent SCons file for Windows builds doxyconfig-cpp.in doxygen config for C++ reference guide doc/ reference guide style doc/images/ reference guide images mamda/c_cpp/src/cpp/ mamda C++ files mamda/ mamda header files news/ mamda news C++ files news/mamda/ mamda news header files options/ mamda options C++ files options/mamda/ mamda options header files orderbooks/ mamda orderbooks C++ files orderbooks/mamda/ mamda orderbooks header files mamda/c_cpp/src/examples/ mamda C++ standard example apps news/ mamda C++ news example apps orderbooks/ mamda C++ orderbook example apps orderbooks/test/ mamda C++ orderbook test apps mamda/c_cpp/src/gunittest/ common/ general C++ mamda unittests orderbooks/ mamda C++ orderbook unittests orderImbalances/ mamda C++ order imbalance unittests quotes/ mamda C++ quote unittests secstatus/ mamda C++ security status unittests trades/ mamda C++ trade unittests mamda/c_cpp/sec/testtools/ mamda test apps mamda/java/ build.xml java build file SConscript Configuration and setup for MAMDA Java SCons build SConscript.win Equivalent SCons file for Windows builds mamda/java/com/wombat/mamda/ mamda java files examples/ mamda java example apps locks/ mamda java lock files options/ mamda java option files orderbooks/ mamda java orderbook files mamda/java/junittests/ orderBooks/ mamda java orderbook unittests orderImbalances/ mamda java order imbalance unittests quotes/ mamda java quote unittests secstatus/ mamda java security status unittests trades/ mamda java trade unittests Building OpenMAMA -------------------- ### Avis Install ### Currently OpenMAMA assumes Avis is the middleware to be built with unless told otherwise. To build the avis client libraries: The Avis router (avisd) is avalaible from: http://sourceforge.net/projects/avis/viles/Avis%20router/ To build the avis client: download the source from: http://downloads.sourceforge.net/avis/avis-client-1.2.4.tar.gz tar -xzf avis-client-1.2.4.tar.gz cd avis-client-1.2.4 ./configure --prefix=${AVIS_HOME} make install 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. Use --with-avis=/path/to/avis to specify where to find avis if it is not installed to a default location. mv ${AVIS_SOURCE}/platforms/gnu_automake/avis_client_config.h ${AVIS_HOME}/include/avis ### Qpid Proton Install ### To build with the Qpid Proton bridge, the Qpid Proton bridge must already be compiled and installed. Note that the recommended version for use with OpenMAMA is 0.5. The qpid proton release can be downloaded and compiled from their website: http://qpid.apache.org/proton/ Alternatively, Qpid Proton can be often be installed using common package managers. For example, to install using "Yum" on a RedHat, Centos or Fedora system, use: sudo yum install qpid-proton-c-devel Once compiled and installed, OpenMAMA can be compiled with Proton support using the following additions to the SCons command: scons middleware=qpid qpid_home=/path/to/proton If building on Windows, you'll also need to include the "libevent_home" command line argument, pointing to your local libevent install. For more information, checkout the documentation on the OpenMAMA Wiki, at: http://wiki.openmama.org #### Legacy Build System #### If building with the legacy Autotools system, OpenMAMA can be compiled with proton support by using the following command *if you are using mama/c_cpp/configure*: ./configure --with-proton=/path/to/proton If you are using the *top level* configure script, you can do the equivalent by running: ./configure --proton-path=/path/to/proton For more information on the Qpid Proton bridge, see: http://wiki.openmama.org/index.php/Qpid_Bridge ### Google Test Install ### OpenMAMA uses the static google test library and expects the files to be in the following location. ${GTEST_HOME}/include - include files ${GTEST_HOME}/lib - library files ### SCons Instructions ### The following uses the default settings to build the OpenMAMA and OpenMAMDA libraries and example applications, along with the Qpid Proton Bridge. This assumes Qpid is installed in /usr, and will install OpenMAMA to an openmama_install_* directory within the current directory. In the top level directory for the OpenMAMA source files: scons middleware=qpid ### SCons Arguments ### vis_home: Path to Avis ( /path/to/avis_home ) Default: /usr/local/ [ /usr/local/ ] blddir: Object directory ( /path/to/blddir ) Default: #objdir [ #objdir ] cache_dir: Path to object cache ( /path/to/cache_dir ) Default: None [ None ] compiler: Compiler to use for building OpenMAMA (default|gcc|clang|clang-analyzer) Default: default [ clang ] entitled: Whether the build is entitled or unentitled (yes|no) Default: False [ False ] gtest_home: Path to Google Test home ( /path/to/gtest_home ) Default: None [ /usr/local ] java_home: JAVA Home folder ( /path/to/java_home ) Default: None [ /usr/java/latest/ ] logfile: Output Log File ( /path/to/logfile ) Default: scons.log [ scons.log ] middleware: Middleware(s) to be compiled in (all|none|comma-separated list of names) allowed names: avis qpid Default: avis [ qpid ] package: Whether to tar up the installation directory (yes|no) Default: False [ False ] prefix: Installation prefix ( /path/to/prefix ) Default: #openmama_install_6.0.1rc2 [ /home/damian/workspace/openmama/OpenMAMA-dev/install ] product: Product to be built (mamda|mamajni|common|mamdajni|mama) Default: mamda [ mama ] qpid_home: Path to QPID Proton Libraries ( /path/to/qpid_home ) Default: /usr/local/ [ /home/damian/lib/proton-0.5/ ] verbose: Whether to print verbose output (yes|no) Default: True [ True ] with_docs: Build with documentation (yes|no) Default: False [ False ] with_examples: Build with test tools (yes|no) Default: True [ True ] with_testtools: Build with test tools (yes|no) Default: False [ True ] with_unittest: Build with gunit tests (yes|no) Default: False [ True ] Use scons -H for help about command-line options. ### Windows Build Using SCons ### The following uses the default settings to build the OpenMAMA library and example applications. It assumes you have a local install of Qpid Proton and libevent, as well as JDK and Flex binaries available. Begin by setting the appropriate environment variables: set PATH=%PATH%;C:\PROGRA~2\GnuWin32\bin set PATH=%PATH%;C:\PROGRA~1\Java\jdk1.7.0_45\bin set JAVA_HOME=C:\PROGRA~1\Java\jdk1.7.0_45\bin set PATH=%PATH%;C:\Python27\Scripts\ Then in the top level of the OpenMAMA source, execute the following: scons middleware=qpid qpid_home=C:\Path\To\Qpid libevent_home=C:\Path\To\libevent product=mama More detailed Windows build instructions (including details for resolving the build dependencies can be found at: http://wiki.openmama.org/index.php/Build_instructions_(Windows) ### Legacy GNU Automake Instructions ### 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 If you are building source code cloned from the OpenMAMA git repository run the following command before following the remaining instructions: ./generateBuildFiles.sh For source downloaded as an archive from http://www.openmama.org, it is not necessary to run generateBuildFiles.sh. ./configure --with-avis=/usr/local make sudo make install ### Configure arguments ### 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: --prefix=${INSTALL_DIR} specify non default Avis install: --avis-path=${AVIS_HOME} specify non default Qpid Proton install: --proton-path=${AVIS_HOME} build unittests, specify google test location: --gtest-path=${GTEST_HOME} build testtools: --with-testtools ### Legacy Building the API Reference ### To build the latest API reference guide, use the following command after Configure: make docs This will build the reference in the mama/c_cpp/src/doc folder. ### Running Unit tests ### After the build is complete (built with the with_unittests flag set to true, and gtest_home directed to a local gtest installation), a series of extra binaries can be found in the bin folder of the install. UnitTestCommonC UnitTestMamaC UnitTestMamaCPP UnitTestMama* Each runs a subset of the available MAMA unit tests, using the Google test framework. The following command line argument is available, as well as the normal Google test options: -m ${MIDDLEWARE} Tests which interact with the underlying payload directly also accept the following: -p ${PAYLOAD} ### Legacy Windows C/C++ build ### Set the AVIS_HOME environment variable appropriately. This should contain debug, release, and include folders. Set the JAVA_HOME environment variable appropriately (for mamajni). This should contain an include folder. Set the ANT_HOME environment variable appropriately (for mamajni). Set the GTEST_HOME environment variable appropriately (optional for unittests). This should contain debug, release, and include folders. Insure Flex is included in your path. Open OpenMama.sln Build common, then mama, then mamda. Avis folder should also be built, if not previously done. Concurrent building of multiple products may cause build fail. Flex perbuild command is run when building common. ### Legacy Windows Java build ### Follow the above steps to build MAMA in C, which the JNI files depend on. For MAMA JNI, in the mama folder, run ant on the build.xml file. ant {optional arguments} -f build.xml The following build arguments are optional: -DwithTestBed=true -DwithDocs=true For MAMDA JNI, in the mamda folder, run ant on the build.xml file with target dist ant -f build.xml dist Run generatewindist in the root OpenMAMA folder. This will create a directory called 'install' containing all the files for distribution. ### Running regression tests ### OpenMAMA regression test suite ============================== The OpenMAMA regression suite is implemented as python unittests. Directories: scripts: Contains python scripts. tools: Contains modified mama sample apps. Complete the following steps to run the test suite: 1. Set LD_LIBRARY_PATH to the lib directory of OpenMAMA. export LD_LIBRARY_PATH=/path/to/OpenMAMA/lib 2. To run with middleware, add middleware libraries to LD_LIBRARY_PATH export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/middleware/lib 3. Set WOMBAT_PATH to mama.properties file export WOMBAT_PATH=/path/to/mamaproperties/ 4. Set CLASSPATH to both the tools directory and the OpenMAMA jars (to test jni) export CLASSPATH=/path/to/tools:/path/to/OpenMAMA/lib/xxx.jar:$CLASSPATH 5. In tools directory,set API_HOME in sample make file to OpenMAMA root directory, that contains lib directory (to test OpenMAMA c and c++) API_HOME=/path/to/OpenMAMA/root/directory #parent directory of lib in step 1 6. In tools directory, execute the following command to compile c and cpp apps using make make -f Makefile.sample 7. In tools directory, compile the java apps (to test OpenMAMA jni) javac BasicPubJava.java BasicSubJava.java BasicInboxJava.java BasicFtMemberJava.java 9. For details about optional arguments run python regression.py --help 10. In scripts directory, run regression.py (python versions 2.4 till 2.7 supported) python regression.py # Runs all tests with avis, avis router should be # running on default port python regression.py --m lbm --tport pub sub --test all --timeout 10 --q #run all tests without verbose output N.B. In the first run, pubsub tests will fail as it requires expected log files. Make a copy of pubsub subscption log as expected log. cp pubsub_basicsubc.out pubsub_expectedsubc.out # for c cp pubsub_basicsubcpp.out pubsub_expectedsubcpp.out # for c++ cp pubsub_basicsubjava.out pubsub_expectedsubjava.out # for java Contributing ------------- Can be done through the OpenMAMA website http://www.openmama.org/get-involved License -------- The OpenMAMA library is distributed under the terms of the GNU Lesser General Public license version 2. Please see COPYING for full licence text.