
See the LICENSE file for licensing information.

--------------------------------
The Apache UIMA C++ SDK
--------------------------------

UIMACPP enables analytics written in C++, Python, Perl and Tcl to be
easily integrated into the UIMA Java framework.

The Apache UIMA C++ SDK is intended to be portable, packaged with
user's annotator code, to make it easier to redistribute UIMACPP-based
applications. This portability also allows different UIMACPP annotators,
each using different versions of UIMACPP, to be integrated into a
common UIMA pipeline on the same machine. For this reason the SDK includes
UIMACPP as well as all prerequisite components. To build the SDK, all
prerequites need to be built from source.

Alternatively UIMACPP can be built and installed on a machine along
with all its prerequisites. In this case the prerequisites can be
installed from binary distributions.

UIMACPP runtime prerequisites are APR, ICU, Xerces-C, ActiveMQ-cpp,
APR-Util and a JDK for building the JNI interface. The SDK also
requires doxygen for building the documentation.

The Apache UIMA C++ SDK has been built and tested in 32-bit mode on
Linux systems with gcc version 3.4.6 and on Windows using MSVC version 8.
64-bit builds have only been tested on Linux with gcc 4.3.2 and 4.4.6.


----------------
Building on Unix
----------------

To build an SDK all prerequisite components, APR, ICU, Xerces-C,
ActiveMQ-cpp and APR-Util must first be built from source and "make
install" run. They need not be installed in system directories.

Prerequisite installs from binary distributions can be used to build
the UIMACPP components.  NOTE: UIMACPP problems have been reported
with binary distributions of "Xerces-C with ICU".

There is also a dependency on JNI headers from a Java JDK.


Optional pre-build step
-----------------------

If changes are made to configure.ac or Makefile.am, then configure
needs to be re-generated using:

 ./autogen.sh

autogen.sh requires GNU tools at or above the following versions:
automake v1.9.6, autoconf v2.59 and libtool v1.5.24.


Configure, build and test
---------------------------

Simply,
  ./configure --with-jdk=location_of_jni.h [other options]
  make
  make check

The ./configure script will generate Makefiles customized to your
system, including detecting available prerequisites that have been
installed in standard locations.

On Linux jni.h is usually in the JDK's "include" directory. On MacOSX
jni.h is in the JDK's "Headers" dirctory. In some cases jni.h will
#include files in other directories. For example, if jni.h includes
jni_md.h located in a subdirectory named linux, use
  --with-jdk="loc_of_jdk/include -Iloc_of_jdk/include/linux"

Other options must be set for an SDK build, or if prerequisites are
not installed in system directories.

For a full SDK build, all of the following are needed:
  --with-apr=loc_of_apr_install --with-icu=loc_of_icu_install \
  --with-xerces=loc_of_xerces_install --with-activemq=loc_of_amq_install \
  --with-apr-util=loc_of_apr-util_install

For a build of UIMACPP without UIMA-AS support, specify the option
--without-activemq. The options --with-activemq and --with-apr-util
can be left out.

For more help on how to customize the build configuration, run:

  ./configure --help


Install and Build SDK tree
--------------------------

  make install
  make sdk TARGETDIR=loc_of_sdk_tree [clean]

By default the install step will put UIMACPP components in
/usr/local/uimacpp. To install them elsewhere, add the following
option to configure:
  --prefix=install_target_loc

The SDK tree will be created in loc_of_sdk_tree/uimacpp. Package by:

  cd loc_of_sdk_tree
  tar czf uimacpp-2.X.Y-bin.tgz uimacpp

A source tarball can be generated by:
  make dist


-------------------
Building on Windows
-------------------

To build an SDK all prerequisite components, APR, ICU, Xerces-C,
ActiveMQ-cpp and APR-Util must first be built on the machine, and a
JDK installed. The location of the dependencies must be set in
environment variables APR_HOME, ICU_HOME, XERCES_HOME, ACTIVEMQ_HOME,
APU_HOME and JAVA_INCLUDE.

The following commands assume you are running from a Microsoft Visual
Studio 2005 Command Prompt. If using MSVC Express Edition, replace the
devenv command with vcexpress.

1 Build the UIMA C++ framework in both release and debug:
  cd \uimacpp-2.X.Y\src
  winmake /build release
  winmake /build debug

2 Build and run the test suite:
  cd \uimacpp-2.X.Y\src\test
  devenv test.sln /build release
  fvt

3 Build the documentation:
  Note: The documentation build requires Doxygen 1.3.6 or later.
  cd \uimacpp-2.X.Y\docs
  builddocs

4 Build the SDK tree:
  set MSVCRT_HOME to the directory with the msvc*.dll files required.
  set ACTIVEMQ_HOME and APU_HOME if building and distributing the ActiveMQ CPP service wrapper, deployCppService.

  buildsdk "target_dir [clean]"

5 Package the SDK zipfile by creating a compressed folder of 
  target_dir\uimacpp into uimacpp-2.X.Y-bin.zip


Building, testing and packaging on Mac OSX:
-------------------------------------------

These instructions should work on the Max OSX but have not been tested. 

Except for one problem with APR, building is the same here as on Linux.
For the Intel-based Mac OSX machines we have tested with, the APR function
to dynamically load shared libraries does not respect DYLD_LIBRARY_PATH.

A fix is to patch dso/unix/dso.c as follows:

26a27,31
>#if defined(DSO_USE_DYLD)
>#define DSO_USE_DLFCN
>#undef DSO_USE_DYLD
>#endif
>

Packaging UIMA C++ annotators:

On Mac OSX, the install names are embedded in the binaries.  Run the
following steps manually post build to neutralize the embedded name in
the UIMA C++ binary and to change the dependency path in the
annotator:
 
1) changing the install name in libuima, to neutralize it:

install_name_tool -id libuima.dylib $UIMACPP_HOME/install/lib/libuima.dylib

2) changing the dependency path in the annotator:

install_name_tool -change "/install/lib/libuima.dylib"
"/absolute_path_to_uimacpp_home/install/lib/libuima.dylib" MyAnnotator.dylib


Building the dependencies: APR, APR-Util, ICU, Xerses-c and Activemq-cpp
------------------------------------------------------------------------

Download and build information for these libraries are at:
  APR      - http://apr.apache.org/
  APR-Util - http://apr.apache.org/
  ICU      - http://www.icu-project.org/
  XERCES   - http://xml.apache.org/xerces-c/
  ACTIVEMQ - http://activemq.apache.org/cms/download.html

ACTIVEMQ CPP library version 3.2 or higher is required to support
the ActiveMQ failover protocol and to support multi-byte payload data.
ACTIVEMQ CPP 3.2 and higher has a dependency on APR at version 1.3.8
or higher and APR-Util 1.3.8.


Building Dependencies on Unix/MacOSX
------------------------------------

The directions for these components is straightforward. The UIMACPP
build expects to find headers in install_loc/include and libraries
in install_loc/lib.


Building Dependencies on Windows:
--------------------------------

The build of dependent libraries on Windows is less consistent.
APR and APR-Util libraries are expected in %APR_HOME%\Release and
%APU_HOME%\Release respectively.  ActiveMQ libraries are in
%ACTIVEMQ_HOME%\vs2008-build\ReleaseDLL (or DebugDLL) and ActiveMQ
headers are expected in %ACTIVEMQ_HOME%\src\main.

On Windows, buildsdk command tries to copy the msvc*.dll runtime libs from
C:\Program Files\Microsoft Visual Studio8\VC\redist\x86\Microsoft.VC80.CRT 
To override the location for MSCV redistributable libraries, use MSVCRT_HOME.

ActiveMQ-CPP - The UIMA C++ MSVC projects are Microsoft Visual Studio
8 (2005) projects.  The ActiveMQ CPP source distribution comes with
MSVC 8 (2008) project.  These can be down converted to MSVC 2005 by
following these step reproduced from
http://stackoverflow.com/questions/609419/how-do-i-downgrade-a-c-visual-studio-2008-project-to-2005

Put the following sed script in a file called downgrade_vc9_to_vc8.sed :
s#Version=\"9.00\"#Version=\"8.00\"#g
s#<ProductVersion>9.0.21022</ProductVersion>#<ProductVersion>8.0.50727</ProductVersion>#g
s#<TargetFrameworkVersion>v2.0</TargetFrameworkVersion>##g
s# ToolsVersion=\"3.5\"##g
s#MSBuildToolsPath#MSBuildBinPath#g

Run 
sed.exe -f downgrade_sln_vc9_to_vc8.sed vs2008-build/activemq-cpp.vcproj > vs2008-build/activemq-cpp2005.vcproj

On Windows, the only activemq-cpp targets needed by uimacpp are ReleaseDLL and DebugDLL,
 e.g. devenv vs2008-build/activemq-cpp2005.vcproj /build ReleaseDLL
      devenv vs2008-build/activemq-cpp2005.vcproj /build DebugDLL
 
APR and APR-Util
Also, the APR and APR-Util libraries can be built by launching
libapr.dsp or by following the instructions in Makefile.win.

XERCES and ICU
Binary distributions are available for Xerces and ICU.


UIMA C++ Release Compatibility
-------------------------------

There a two distinct features of UIMA C++ to consider when dealing
with release compatibility:

- The framework dynamically loads annotators which are user code. The
   annotators make calls to UIMA C++ APIs and are built with some
   version of the SDK. A possible scenario is for an application to
   run annotators that were built with different releases of UIMA C++
   SDK.
- The SDK depends on ICU, XERCES, APR and ACTIVEMQ-CPP and a release
   is built with a particular version of these.  Binary compatibility
   therefore also depends on the compatibility of these underlying
   libraries.  In particular, ICU and XERCES encode the major and
   minor release numbers in the APIs which restricts binary
   compatibility across releases of these libraries.  An application
   running UIMA C++ is restricted to running one version of the ICU
   library in a process and all annotators and underlying libraries
   must use the same ICU version.
   
In general, different UIMACPP releases are not binary compatible.