README.4src

See the NOTICE 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 versions from 3.2.4 to 4.1.0, on Windows 
using MSVC version 8, and on MacOSX with gcc version 4.0.1.

64-bit builds have only been tested on Linux with gcc 4.1.0.


Setting up the build environment:
---------------------------------
UIMACPP has dependencies on APR, ICU, Xerces-C and ActiveMQ-cpp
libraries.  Dependent libraries must be specified with the
environmental parameters APR_HOME, ICU_HOME, XERCES_HOME and
ACTIVEMQ_HOME.  For now, the ActiveMQ dependency is optional; if not
specified the UIMA-AS compatible service wrapper deployCppService will
fail to 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 libraries are expected in %APR_HOME%\Release. ActiveMQ libraries 
are in %ACTIVEMQ_HOME%\vs2005-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-incubating.

1 Create the GNU automake scripts:
  Note: This step is only done when building from an SVN extract;
        it should be skipped when building from a source tarball.
        The prebuild step requires relatively up-to-date GNU tools
        GNU automake v1.9.6, autoconf v2.59 and libtool v1.5.24.
  cd $HOME/uimacpp-2.X.Y-incubating/src
  make -f Makefile.prebuild

2 Build the UIMA shared library and test routines:
  cd $HOME/uimacpp-2.X.Y-incubating/src
  make -f Makefile.unix install

3 Run the test suite:
  cd $HOME/uimacpp-2.X.Y-incubating/src/test
  ./fvt.sh

4 Build the documentation:
  Note: The documentation build requires Doxygen 1.3.6 or later.
  cd $HOME/uimacpp-2.X.Y-incubating/docs
  ./builddocs.sh

5 Build the SDK tree:
  cd $HOME/uimacpp-2.X.Y-incubating
  ./buildsdk.sh target_dir

6 Package the SDK tarball:
  cd target_dir
  tar czf uimacpp-2.X.Y-incubating-bin.tgz uimacpp


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

1 Build the UIMA C++ framework in both release and debug:
  cd \uimacpp-2.X.Y-incubating\src
  winmake /build release
  winmake /build debug

2 Build and run the test suite:
  cd \uimacpp-2.X.Y-incubating\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-incubating\docs
  builddocs

4 Build the SDK tree:
  set MSVCRT_HOME to the directory with the msvc*.dll files required.
  cd \uimacpp-2.X.Y-incubating
  buildsdk target_dir

5 Package the SDK zipfile by creating a compressed folder of 
  target_dir\uimacpp into uimacpp-2.X.Y-incubating-bin.zip


Building, testing and packaging on Mac OSX:
-------------------------------------------
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
>


Building the dependencies: APR, ICU, Xersec-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

For UNIX users that cannot or do not want to install these at
system root, specify DESTDIR for the install step. For example,
after building APR, install using:

  DESTDIR=`pwd` make install

On Windows, the only activemq-cpp targets needed by uimacpp are ReleaseDLL and DebugDLL,
 e.g. devenv vs2005-build/vs2005-activemq.vcproj /build ReleaseDLL

Also, the APR library can be built by launching libapr.dsp or by following the
instructions in Makefile.win.


Disclaimer
-----------

Apache UIMA is an effort undergoing incubation at The Apache Software
Foundation (ASF). Incubation is required of all newly accepted projects
until a further review indicates that the infrastructure, communications,
and decision making process have stabilized in a manner consistent with
other successful ASF projects. While incubation status is not necessarily
a reflection of the completeness or stability of the code, it does
indicate that the project has yet to be fully endorsed by the ASF.