| |
| 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: |
| |
| 3rd Party Recommended Version |
| ------------------------------- |
| APR >= 1.6.5 |
| ICU == 50.2 |
| Xerces-C >= 3.1.4 |
| Java SDK >= 1.8 |
| ActiveMQ CPP >= 3.9.3 (optional) to build the UIMA-AS service wrapper |
| APR-util >= 1.6.1 (optional) an ActiveMQ prerequisite |
| |
| |
| On Linux the following GNU build tools are required: |
| |
| Tool Recommended Version |
| ------------------------------- |
| autoconf >= 2.69 |
| automake >= 1.13.4 |
| libtool >= 2.4.2 |
| g++ >= 4.8.5 |
| |
| 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 64-bit mode on Linux systems with gcc version 4.8.5; |
| Mac OSX 64-bit and Windows versions are currently delayed. |
| |
| 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 an installed Java development package. |
| |
| |
| Build Steps |
| ----------- |
| |
| Configure and build |
| Generate a configure script compatible with the build machine tool level: |
| ./autogen.sh |
| |
| Generate the required makefiles and build UIMACPP components: |
| ./configure --with-jdk=location_of_jni.h [other options, see below] |
| make |
| |
| 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-3.0.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' -I'loc_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 |
| |
| Run the test suite |
| make check |
| |
| Install and Build the SDK tree |
| make install |
| make docs |
| make sdk TARGETDIR=loc_of_sdk_tree [CLEAN=clean] |
| |
| The SDK tree will be created in loc_of_sdk_tree/uimacpp. Package by: |
| cd loc_of_sdk_tree |
| tar czf uimacpp-X.Y.Z-bin.tgz uimacpp |
| |
| 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-X.Y.Z\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-X.Y.Z\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-X.Y.Z\src |
| winmake /build release |
| winmake /build debug |
| |
| 2 Build and run the test suite: |
| cd \uimacpp-X.Y.Z\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-X.Y.Z\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-X.Y.Z |
| buildsdk "target_dir [clean]" |
| |
| 5 Package the SDK zipfile by creating a compressed folder of |
| target_dir\uimacpp into uimacpp-X.Y.Z-bin.zip |
| |
| 6 Package a source zipfile by creating a compressed folder of the |
| the directory containing the uimacpp source from git |
| |
| |
| ---------------------------------------------- |
| 4. Building, testing and packaging on Mac OSX: |
| ---------------------------------------------- |
| Except for note below, building is the same here as outlined |
| in Building on Unix (section 2). |
| |
| Make sure you have built and installed in your system all prerequisites, |
| as stated in General (section 1). |
| |
| |
| 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 Re-generated configure |
| -------------------------- |
| |
| In Mac OSX it is necessary to re-generate the configure file: |
| |
| ./autogen.sh |
| |
| |
| 4.3 Executing configure |
| ----------------------- |
| |
| Mac OSX Sierra default GCC is not capable of building UIMACPP. As alternative, you can |
| install GCC-5 and pass it as an agument in configure command: |
| |
| CC=gcc-5 CXX=g++-5 ./configure <other parameters> |
| |
| Make sure to pass the JDK Hearder path (--with-jdk) and the path of each dependency |
| (--with-<dep name> syntax). |
| |
| |
| 4.4 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#<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 |
| |
| 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. |