| |
| 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. |
| |
| |