README.4src - uima-uimacpp - Git at Google


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

 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.

 On Windows dependent libraries must be specified with the
 environmental parameters APR_HOME, ICU_HOME, XERCES_HOME and
 ACTIVEMQ_HOME.  For now, the ActiveMQ CPP dependency is 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 and
 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 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.

 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 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_HOME/include --with-apr=$APR_HOME --with-icu=$ICU_HOME --with-xerces=$XERCES_HOME --with-activemq=$ACTIVEMQ_HOME
   make
   DESTDIR=`pwd` make install

 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, and ACTIVEMQ_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 later.

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

 6 Build source tarball:
   From root of the SVN extract
   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.

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

 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.

 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 vs2008-build/vs2008-activemq.vcproj /build ReleaseDLL

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


 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.

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

	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.

	On Windows dependent libraries must be specified with the
	environmental parameters APR_HOME, ICU_HOME, XERCES_HOME and
	ACTIVEMQ_HOME. For now, the ActiveMQ CPP dependency is 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 and
	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 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.

	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 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_HOME/include --with-apr=$APR_HOME --with-icu=$ICU_HOME --with-xerces=$XERCES_HOME --with-activemq=$ACTIVEMQ_HOME
	make
	DESTDIR=`pwd` make install

	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, and ACTIVEMQ_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 later.

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

	6 Build source tarball:
	From root of the SVN extract
	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.

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

	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.

	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 vs2008-build/vs2008-activemq.vcproj /build ReleaseDLL

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


	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.