| |
| See the LICENSE file for licensing information. |
| |
| -------------------------------- |
| Building the Apache UIMA C++ SDK |
| -------------------------------- |
| |
| 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 |
| |
| |
| Setting up the build environment: |
| --------------------------------- |
| UIMACPP has dependencies on APR, ICU, Xerces-C and ActiveMQ-cpp |
| libraries. ActiveMQ-cpp has a runtime dependency on APR-Util and is required to build the |
| binary distribution. |
| |
| On Windows dependent libraries must be specified with the |
| environmental parameters APR_HOME, ICU_HOME, XERCES_HOME, APU_HOME and |
| ACTIVEMQ_HOME. For now, the ActiveMQ CPP and APR Util dependencies are optional; if not |
| specified the UIMA-AS compatible service wrapper deployCppService will |
| fail to build. |
| |
| On Linux, system install of dependencies - APR, ICU, XERCES, ACTIVEMQ |
| will be used if minimum version requirements are met. They may also |
| be specified with the environmental parameters APR_HOME, ICU_HOME, XERCES_HOME, |
| ACTIVEMQ_HOME. The ActiveMQ CPP library is required. |
| |
| There is also a dependency on JNI headers from a Java JDK. The build |
| looks for these headers in the directory specified by JAVA_INCLUDE. |
| A typical setting for JAVA_INCLUDE on Linux or Windows would be |
| $JAVA_HOME/include; on MacOSX jni.h and the other headers will be in a |
| "Headers" directory. |
| |
| On Unix, dependent headers are expected under $dependent_HOME/include and |
| dependent libraries under $dependent_HOME/lib. |
| |
| 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 Studio 8\VC\redist\x86\Microsoft.VC80.CRT |
| To override the location for MSCV redistributable libraries, use MSVCRT_HOME. |
| |
| |
| Building, testing and packaging on Linux: |
| ----------------------------------------- |
| Set up your environment as described above. The following instructions |
| assume you have unpacked the source into $HOME/uimacpp-2.X.Y. |
| |
| 1 (Optional) Create the GNU automake scripts: |
| Note: This step is only done to regenerate the configure script and Makefile.in if |
| the configure.ac or Makefile.am need to be modified. |
| The prebuild step requires relatively up-to-date GNU tools |
| GNU automake v1.9.6, autoconf v2.59 and libtool v1.5.24. |
| cd root of an SVN extract |
| ./autogen.sh |
| |
| 2 Build the UIMA shared library and test routines: |
| cd root of the SVN extract |
| ./configure --with-jdk=$JAVA_INCLUDE --with-apr=$APR_HOME --with-icu=$ICU_HOME --with-xerces=$XERCES_HOME --with-activemq=$ACTIVEMQ_HOME |
| make |
| DESTDIR=`pwd` make install (or make install-strip to strip symbols to shrink the binaries) |
| |
| 3 Build and run the test suite: |
| From root of the SVN extract |
| make check |
| |
| 4 Build the SDK tree: |
| Requires environmental parameters to be set for ICU_HOME, XERCES_HOME, APR_HOME, ACTIVEMQ_HOME, APU_HOME. |
| From root of the SVN extract |
| make sdk ARGS=target_dir |
| This will build the documentation. |
| Note: The documentation build requires Doxygen 1.3.6 or lahter. |
| |
| To rebuild the SDK at the same target_dir, run |
| make sdk ARGS="target_dir clean" |
| |
| 5 Package the SDK tarball: |
| cd target_dir/.. |
| tar czf uimacpp-2.X.Y-bin.tgz uimacpp |
| |
| 6 Build source tarball: |
| The source tar ball contains all the files needed to build on Windows and Linux |
| To build a source tar ball with only files needed for a Linux build, run: |
| make dist |
| |
| |
| Building, testing and packaging on Windows: |
| ------------------------------------------- |
| Set up your environment as described above. The following instructions |
| assume you have unpacked the source into \uimacpp-2.X.Y. |
| |
| 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. |
| cd \uimacpp-2.X.Y |
| buildsdk target_dir |
| |
| 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, ICU, Xersec-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. |
| |
| For UNIX users that cannot or do not want to install these as |
| system root, specify DESTDIR for the install step. For example, |
| after building APR, install using: |
| |
| DESTDIR=`pwd` make install |
| |
| |
| Building Dependencies on Windows: |
| -------------------------------- |
| |
| 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 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. |
| |
| We do not enforce binary compatility when doing a release. |
| |
| Installing UIMACPP SDK as a system-wide shared library is discouraged since we do not |
| have support for parallel versions. The include directory does not have version number and |
| there cannot be multiple versions of executable runAECpp and deployCppService. |