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 contains UIMACPP as well as all prerequisite components. The SDK is intended to enable user's annotator code be packaged for integration into a UIMA pipeline and to make it easier to redistribute UIMACPP-based applications. This 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 contains 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 build process also builds the documentation and 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: https://uima.apache.org/dev-quick.html https://uima.apache.org/doc-uimacpp-build.html ------------------------- 2. Building on Unix/Linux ------------------------- 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 installed by running "make install". 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. 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. Build Steps ----------- 1 Configure and build To build the UIMACPP libraries using prerequisites installed in the system directories, Simply run: ./configure --with-jdk=location_of_jni.h [other options] make The ./configure script will generate Makefiles customized to your system, including detecting available prerequisites that have been installed in standard locations. 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 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 as well as 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 \ --with-apr-util=loc_of_apr-util_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 Run the test suite make check 3 Install and Build the SDK tree make install make sdk TARGETDIR=loc_of_sdk_tree [clean] 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 4 Optionally, 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, APR-util and APR-iconv must first be built, and a JDK installed. The location of the dependencies must be set in environment variables APR_HOME, ICU_HOME, XERCES_HOME, ACTIVEMQ_HOME and JAVA_HOME. 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 described below in step 4, since the annotator projects use the environment variable UIMACPP_HOME to locate the UIMA libraries and dependencies. 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/fvt.sh 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 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 required msvc*.dll files. set ACTIVEMQ_HOME if building the ActiveMQ service wrapper, deployCppService. cd \uimacpp-2.X.Y 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 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: 26a27,31 >#if defined(DSO_USE_DYLD) >#define DSO_USE_DLFCN >#undef DSO_USE_DYLD >#endif > 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 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 ---------------------------------------------------------------------------- 5. Building the dependencies: APR et al, ICU, Xerses-c and Activemq-cpp ---------------------------------------------------------------------------- Download and build information for these libraries are at: APR - 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. (On Windows APR-util requires APR-iconv) 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. The APR components must be checked out and built in parallel directories (see apr.apache.org) and the libraries are expected to be located relative to %APR_HOME%. ActiveMQ libraries are in %ACTIVEMQ_HOME%\vs2008-build\ReleaseDLL and the 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#9.0.21022#8.0.50727#g s#v2.0##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 The only activemq-cpp target needed by uimacpp is ReleaseDLL, e.g. devenv vs2008-build/activemq-cpp2005.vcproj /build ReleaseDLL The three APR libraries can be built by launching aprutil.dsw and building libaprutil or by following the instructions in Makefile.win. XERCES and ICU Binary distributions are available for Xerces and ICU. Use only those built with a compatible version of Visual Studio! Currently the SDK uses xerces-c_2 so if a higher version is installed the MSVC project files must be edited. ---------------------------------- 6. UIMA C++ Release Compatibility ---------------------------------- There are 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.