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