README.4bin

                  Apache UIMA C++ (Unstructured Information Management Architecture) v3.0.0
                  -------------------------------------------------------------------------

Getting Started
----------------

Apache UIMA C++ can be used as a standalone framework, but it is primarily intended to be integrated with the Apache UIMA Java framework. Interoperability is enhanced if the uimacpp SDK package is installed directly under the top level directory of the Apache UIMA Java framework. 

For information about the Apache UIMA C++ package go to index.html in the uimacpp/docs directory. For more information about Apache UIMA, go to http://uima.apache.org, or to the documentation in the Apache UIMA Java package.


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

The Apache UIMA C++ SDK has been built and tested in 64-bit mode on Linux systems with gcc version 4.8.5. MacOS and Windows versions are delayed pending user requests. 

UIMACPP has dependencies on APR, ICU, Xerces-C and optionally ActiveMQ-cpp libraries.  ActiveMQ-cpp has a dependency on APR-UTIL. 

This UIMA C++ SDK has been built with the following versions of these dependencies:
- APR 1.6.5
- ICU 50.2
- XERCES 3.1.4
- ACTIVEMQ CPP 3.9.3
- APR-UTIL 1.6.1


Environment Variables
----------------------

The following environmental variables are needed for UIMA C++ to function properly.

    * UIMACPP_HOME should point to the uimacpp directory of your unpacked Apache UIMA C++
      distribution. UIMACPP_HOME is used when compiling & linking UIMA C++ components.
    * Append $UIMACPP_HOME/bin to your PATH to pick up the runAECpp test driver and 
      deployCppService utility.
    * Append $UIMACPP_HOME/lib to your LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (MacOSX)
      so that the necessary shared libraries can be found.

Also note that UIMA C++ annotators are built as shared libraries, so they must be in a directory in the LD_LIBRARY_PATH, DYLD_LIBRARY_PATH or PATH (as appropriate to your platform) as well. An example of this is given in the next section.

For better runtime integration between Java and C++, the Apache UIMA Java SDK command line utilities and Eclipse run configurations automatically add $UIMA_HOME/uimacpp/lib to LD_LIBRARY_PATH and DYLD_LIBRARY_PATH, and add $UIMA_HOME/uimacpp/bin to PATH.


Verifying Your Installation
----------------------------

The procedure here is to first test that Apache UIMA C++ is installed and operating correctly. Then if desired, check if the code is interoperating properly with Apache UIMA Java.

Set up the environment as described above. Go to $UIMACPP_HOME/examples/src to build the sample code and add the src directory to the appropriate path as follows.

On Linux:  (Please see below Notes on lib/base.mak)
    * make -f DaveDetector.mak
    * LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`pwd`

On Windows:
From a MSVC Command Prompt:
    * devenv DaveDetector.vcproj /build release
    * PATH=%PATH%;%CD%

To test the sample code in the C++ environment, change back to the $UIMACPP_HOME/examples directory and run:
    * runAECpp descriptors/DaveDetector.xml data

The console should show that a Dave was found in some of the files in the data directory.

To test interoperability with Java using the JNI, enable UIMA-AS by setting UIMA_HOME and adding $UIMA_HOME/bin to PATH. Then use the runAE.sh utility (use runAE on Windows) to run DaveDetector from the $UIMACPP_HOME/examples:
    * runAE.sh descriptors/DaveDetector.xml data

To test interoperability with UIMA-AS, continuing with above configuration:
    * Start and ActiveMQ broker using the startBroker.sh command
    * Build and deploy the uimacpp MeetingAnnotator component
       * cd $UIMACPP_HOME/examples/tutorial/src and run "make -f MeetingAnnotator.mak"
       * add this directory to C++ library path: "LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD"
       * deploy the service:
         deployCppService $UIMACPP_HOME/examples/tutorial/descriptors/MeetingAnnotatorCPP.xml MeetingAnnotator
       * deploy MeetingDetectorTAE service that uses this meeting annotator service:
         UIMA_DATAPATH=$UIMA_HOME/examples/descriptors deployAsyncService.sh \
         $UIMACPP_HOME/examples/tutorial/descriptors/Deploy_MeetingDetectorTAE_RemoteMeeting.xml
    * Send work to the two services:
         runRemoteAsyncAE.sh tcp://localhost:61616 MeetingDetectorTaeQueue \
         -c $UIMA_HOME/examples/descriptors/collection_reader/FileSystemCollectionReader.xml 


For more information about the C++ sample code see $UIMACPP_HOME/examples/readme.html.

For more information about UIMA C++ $UIMACPP_HOME/RELEASE_NOTES.html.

Notes on lib/base.mak
---------------------
The annotator and application Make files include lib/base.mak.

On Mac OS X, it is necessary to modify base.mak 
1) Change APR, ICU and XERCES-C includes
   In line 
   INCLUDES=-I$(UIMACPP_HOME)/include -I$(UIMACPP_HOME)/include/apr-1
   set the correct path to the APR, ICU and XERCES-C include directories. For example:
   INCLUDES=-I$(UIMACPP_HOME)/include -I/usr/local/opt/apr/libexec/include/apr-1 -I/usr/local/opt/icu4c/include -I/usr/local/opt/xerces-c/include
2) Add APR, ICU and XERCES-C libraries
   In line 
   LIBRARIES=-L$(UIMACPP_HOME)/lib
   include the path to the APR, ICU and XERCES-C lib directories. For example:
   LIBRARIES=-L$(UIMACPP_HOME)/lib -L/usr/local/opt/apr/libexec/lib -L/usr/local/opt/icu4c/lib -L/usr/local/opt/xerces-c/lib
3) Change the compiler
   If you have issues with the default Mac OS X GCC, install GCC-5 and change the line
   CC=g++
   to
   CC=g++-5