blob: a4679d4c4db39608804c40997fb365edc91107ee [file] [log] [blame]
See the LICENSE file for licensing information.
The Apache UIMA C++ SDK
1. General
2. Building on Unix
3. Building on Windows
4. Building, testing and packaging on Mac OSX
5. Building the dependencies
6. UIMA C++ Release Compatibility
1. General
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, it is recommended that the prerequisites be built from source.
The SDK build process must be configured with the location of the install directory for each
of the dependencies. It locates the headers and libraries of the dependencies relative
to the specified location.
Alternatively, on Linux, UIMACPP can be built and installed on a machine along
with all its prerequisites in the standard system directories. In this case the
prerequisites can be installed from binary distributions.
UIMACPP runtime prerequisites are:
Tool Recommended Version
APR >= 1.3.8
ICU >= 3.6
Xerces-C >= 2.8
JDK for building the JNI interface
ActiveMQ CPP >= 3.4.1 (optional) to build the UIMA-AS service wrapper
APR-Util >= 1.3.8 (optional) an ActiveMQ prerequisite
On Linux the following GNU build tools are required:
Tool Recommended Version
autoconf >= 2.61
automake >= 1.10
libtool >= 1.5.24
On Windows, UIMACPP is built with Microsoft Visual Studio. The UIMA C++ MSVC projects
are Microsoft Visual Studio 8 (2005) projects.
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.
For up-to-date build instructions. please see these pages on the Apache UIMA site:
2. Building on Unix
To build an SDK it is recommended that all prerequisite components, APR, ICU, Xerces-C,
ActiveMQ-cpp and APR-Util be built from source and "make
install" run. They need not be installed in system directories.
Prerequisite installs from compatible binary distributions can be used to build
the UIMACPP components. At runtime, only one version of ICU can be loaded. Some
binary distributions of Xerces-C are built with ICU and have been reported to have
problems. In this case, rebuild Xerces-C from source and specify --without-icu argument
to the configure script.
There is also a dependency on JNI headers from a Java JDK.
2.1 Optional pre-build step
If changes are made to or, then configure
needs to be re-generated using:
./ requires GNU tools at or above the following versions:
automake v1.9.6, autoconf v2.59 and libtool v1.5.24.
2.2 Configure, build and test
To build the UIMACPP libraries using prerequisites installed in the
system directories, Simply,
./configure --with-jdk=location_of_jni.h [other options]
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"
If the prerequisites are not installed in the system directories and
for a full SDK build, additional parameters must be provided to the
configure script:
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 \
For a build of UIMACPP without UIMA-AS support, specify the option
--without-activemq and leave out --with-activemq and --with-apr-util.
For more help on how to customize the build configuration, run:
./configure --help
2.3 Run the test suite
make check
2.3 Install and Build the 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 build an SDK, install them elsewhere by adding the following
option to configure:
--prefix=install_target_loc e.g. --prefix=~/uimacpp-2.4.0/install
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
2.4 Generate source tar ball
make dist
For additional information on building on Mac OSX, please see Section 4.
3. 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
For details on building the dependencies, please see section 5.2 of
this document.
In order to be able to build annotators, the SDK must be built as the
annotator MSVC projects setup requires the environment variable
UIMACPP_HOME to be set to the location of the SDK and finds all
dependencies under UIMACPP_HOME.
If using MSVC Express Edition, first run these prebuild steps.
- cd uimacpp-2.X.Y\src
- run vcexpress uimacpp.sln and do any conversions as prompted.
- replace devenv command with vcexpress in the winmake and test/ scripts and in all build instructions.
- continue with the instructions below.
If using a newer version of MSVC, the uimacpp.sln in uimacpp-2.X.Y\src
must be converted.
The following commands assume you are running from a Microsoft Visual
Studio 2005 Command Prompt.
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
3 Build the documentation:
Note: The documentation build requires Doxygen 1.3.6 or later.
cd \uimacpp-2.X.Y\docs
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
6 Package a source zipfile by creating a compressed folder of the
the directory containing the source download or SVN extract.
4. Building, testing and packaging on Mac OSX:
Except for one problem with APR (see below), building is the same here as outlined
in Building on Unix (section 2).
These instructions should work on the Max OSX but have not been tested.
4.1 Patch APR
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:
>#if defined(DSO_USE_DYLD)
>#define DSO_USE_DLFCN
>#undef DSO_USE_DYLD
4.2 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
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
5. Building the dependencies: APR, APR-Util, ICU, Xerses-c and Activemq-cpp
Download and build information for these libraries are at:
APR-Util -
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.
5.1 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.
5.2 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
Put the following sed script in a file called downgrade_vc9_to_vc8.sed :
s# ToolsVersion=\"3.5\"##g
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
Binary distributions are available for Xerces and ICU.
6. 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++
- 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.