README.4src

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, the build will attempt to locate and use the system installation of the dependencies 
- APR, ICU, XERCES, ACTIVEMQ. Provided these are consistent and only the UIMACPP library is required to be built, 
there is no need for ennviroment variables to be set.

To build with libraries at different location or to build the SDK, the environmental parameters 
APR_HOME, ICU_HOME, XERCES_HOME, ACTIVEMQ_HOME and APU_HOME must be set.  

The ActiveMQ CPP library is required for the Linux build.

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  
  To build with system installation of the dependencies, run:
  ./configure
  To build specifiying the path to the the location of the dependencies, 
  first set the environement variables APR_HOME, ICU_HOME, XERCES_HOME, ACTIVEMQ_HOME to the respective install directories..
        set JAVA_INCLUDE
  run
  ./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.