Building Xalan-C with Unix

[sh...@e-z.net]

## Building Xalan-C/C++

The Xalan-C/C++ XSLT library is built upon the Xerces-C/C++ XML Parser
library. Before compiling the Xalan-C/C++ XSLT library, you must have a
usable Xerces-C/C++ library.

Building the source code packages ensures that the resulting packages are
proper for your system. Incompatibilities between C++ compilers (even
between compiler versions) are known to cause issues with sharing of
libraries.

We don't have persons yet committed to build Xalan binary distribution
releases.

You can get information on the Xerces-C/C++ distributions at web site
[http://xml.apache.org/xerces-c/].


## UNIX Build Environment

I don't like building sources using root or superuser login.  I like to do
builds in a directory separated from the source tree.  A debug build and
release build will create shared objects of the same name.  I like to
target these builds to separate directory trees.

Release builds are targeted at the /usr/local file system.

Debug builds are targeted at the /opt/apache/debug file system.

Source trees are referenced wherever convenient.  Using the (--srcdir)
configuration parameter allows the source tree to be separate from the
build tree.  The source tree can even reside on read-only media.

Product builds are done in a build directory path separate from the source
tree.  This is the working directory from where you perform your builds
and installs.


Source Trees: (--srcdir) configuration parameter

    /opt/xerces/c/<trunk>/<the Xerces-C/C++ XML parser library source
distribution>

    /opt/xalan/c/<trunk>/<the Xalan-C/C++ XSLT library source distribution>

If the source distribution is well-constructed, the source directory trees
can be read-only.

Binary Installation Trees: (--prefix) configuration parameter

    /usr/local/ <the target for release binary installation>
            ./bin               The sample programs
            ./lib               The shared and static library files
            ./include           The library header files

    /opt/apache/debug/ <the target for debug binary installation>
            ./bin               The sample programs
            ./lib               The shared and static library files
            ./include           The library header files

The default (--prefix) value is /usr/local which I use for release builds.

I choose (--prefix) value of /opt/apache/debug for debug builds.


Build Tree: The build working directory tree

    /<user-directory>/Build/

Initialize this directory to be empty on a writable file system and make
it your current directory.

I also like to make some shell scripts so that the build process can be
automated. I locate these scripts outside of the Build directory so they
don't get lost when I purge directory content.

    ../build-xerces-lib.sh

    ../build-xalan-lib.sh

    ../build-xalan-app.sh

I generate these shell scripts with a text editor and use them to minimize
keyboard typing errors.


## Testing Your Libraries

The various types of UNIX operating systems have differing requirements
for finding libraries at runtime.

    Operating System                Library Path Environment

    Solaris and Linux               LD_LIBRARY_PATH

    HP-UX                           SHLIB_PATH

    AIX and BSD	                    LIBPATH

    Mac OS X                        DYLD_LIBRARY_PATH

    Cygwin and  MinGW               PATH

The directory containing the shared libraries must be placed in the proper
library path list for your platform.

In many cases, the /usr/local/lib is already cached in /etc/ld.so.cache or
included by /etc/ld.so.conf.  The library path environment variable is
then used for exceptions.  The library path list usually takes precedence
over the other methods of finding shared library runtimes.  This is useful
if you wish to use a debug environment on the same platform that also
includes release libraries of the same name.


## Building the Xalan-C/C++ XSLT Transformer for UNIX


I don't like building sources from a root or superuser login.  I also like
to do builds in a directory separated from the source tree.

If your sources tree is read-only and some required files are not
executable, then you need to copy the source to writable media and change
the execute attributes of specific files.  This command sequence will copy
an entire directory tree from {source-dir} to {dest-dir}.

        cd {source-dir}
        find . | cpio -pdmuv {dest-dir}

Connect to the (xalan-src) directory and make specific files executable.

        cd {xalan-src}
        chmod 755 runConfigure configure install-sh

Connect to your empty build directory and construct a script for building
the Xalan-C/C++ XSLT products.

#!/bin/sh
# Script to build and install Xalan-C/C++ products from sources

# The Source and Target Directories for Debug Build

# SourceDir="--srcdir=/opt/xalan/c/trunk"
# DestDir="--prefix=/opt/apache/debug"

# The Source and Target Directories for Release Build

SourceDir="--srcdir=/opt/xalan/c/trunk"
DestDir="--prefix=/usr/local"

# The Xerces and Xalan package directories

export XALANCROOT=${SourceDir}
export XERCESCROOT=${DestDir}

# If compiling with IBM-ICU support, the ICUROOT environment variable
needs to be
# defined to specify where the ICU libraries are installed.  Specifically
the following
# directories are accessed:
#       ${ICUROOT}/lib, ${ICUROOT}/include, ${ICUROOT}/data
#       export ICUROOT=/usr/local

# The runConfigure Options
#
# -p    Build platform: aix, linux, freebsd, netbsd, solaris, hp-10,
hp-11, hp11-ia64
#       irix, tru64, macosx, cygwin,
#
# -c    C compiler name: gcc, cc, c89, xlc, xlc_r, acc (default = gcc)
#
# -x    C++ compiler name: g++, CC, C89, xlC, xlC_r, aCC (default = g++)
#
# -d    Indicates a debug build, takes no values, default is No Debug
#
# -t    Transcoder to use: 'icu', (Default is null, the Xerces-C/C++
transcoder)
#
# -m    Type of localization support: inmem, icu, nls (default is inmem)
#
# -M    Locale for message localization: "en_US"
#
# -r    Threads option: pthread, dce (Default is pthread)
#
# -b    Specify 32 or 64 bit build (Default is 32-bit)
#       On Linux, the 32/64 build is determined by the compiler, kernel,
and glibc.
#
# -P    Install root directory: value is assigned to the (--prefix)
configure parameter
#
# -l    Extra link options (assigned to LDFLAGS)
#
# -z    Extra compiler options (assigned to CFLAGS and CXXFLAGS)
#
# -C    Extra configuration options (i.e. --srcdir=${SourceDir})
#
# -h    Print the runConfigure help and exit
#
#
# Compilers for specific Operating Systems
#
#       aix         xlc_r   xlC_r       (thread support)
#       aix         xlc     xlC         (no thread support)
#       cygwin      gcc     g++
#       hp-ux       aCC     aCC
#       solaris     cc      CC

export PATH=$PATH:${SourceDir}

# Debug Configure

# runConfigure -p linux -d -c gcc -x g++ -P "${DestDir}" \
#   -C "--srcdir=${SourceDir}"

# Release Configure

runConfigure -p linux -c gcc -x g++ -P "${DestDir}" \
#   -C "--srcdir=${SourceDir}"

# Connect to configured src subdirectory to build the library without
sample programs
# and build the libraries.  If you make from your build directory, then
all sample programs
# will also be built.

cd src
make clean
make

# As a user with permissions to write to ${DestDir} install the
Xalan-C/C++ products
#   ${DestDir}/bin   the Xalan command-line utility and sample programs
#   ${DestDir)/lib    the Xalan-C/C++ static and dynamic libraries
#   ${DestDir}/include/xalanc/*    The header files.

# make install

## End of sample build script.



## Reference on Unix Platforms and C++ Compilers

Some compilers and platforms may need configuration options and variables
that differ from the default Linux build.  Beware that the runConfigure
script for Xalan-C/C++ is a front-end that calls the configure script. 
The following table is reference information for the build of Xerces-C/C++
version 3.x.  The C++ compiler for Xerces should be the same as used for
Xalan builds.

    Platform                Compiler
        Options

    Solaris x86             Sun CC
        ./configure CXX=CC CC=cc
    Solaris x86-64          Sun CC
        ./configure CXX=cc CC=cc CFLAGS=-xarch=amd64 CXXFLAGS=-xarch=amd64
        (newer Sun CC versions use -m64 instead of -arch=amd64)
    Solaris Sparc           Sun CC
        ./configure CXX=CC CC=cc
    Solaris Sparc v9        Sun CC
        ./configure CXX=cc CC=cc CFLAGS=-xarch=v9 CXXFLAGS=-xarch=v9
        (newer Sun CC versions use -m64 instead of -arch=v9)
    AIX PowerPC             IBM XLC++
        ./configure CXX=xlc_r CC=xlc_r
        gmake libxerces_c_1a LDFLAGS=-qmkshrobj
    AIX PowerPC-64          IBM XLC++
        ./configure CXX=xlc_r CC=xlc_r CXXFLAGS=-q64 CFLAGS=-q64
        gmake libxerces_c_1a LDFLAGS=-qmkshrobj
    HP-UX 1a-64-32          HP aCC
        ./configure CXX=aCC CC=aCC CFLAGS=-mt CXXFLAGS=-mt LDFLAGS=-mt
    HP-UX 1a-64             HP aCC
        ./configure CXX=aCC CC=aCC CFLAGS=-mt CXXFLAGS=-"mt +DD64"
        LDFLAGS="-mt +DD64"
    Mac OS X x86-64         GCC
        ./configure CFLAGS="-arch x86_64" CXXFLAGS="-arch x86_64"
    Mac OS X
    PowerPC-64              GCC
        ./configure CFLAGS="-arch ppc64" CXXFLAGS="-arch ppc64"
    Mac OS X
    x86/PowerPC             GCC
        ./configure --disable-dependency-tracking
        CFLAGS="arch i386 -arch ppc" CXXFLAGS="-arch i386 -arch ppc"
    MinGW x86               GCC
        ./configure LDFLAGS=-no-undefined
    Cygwin x86              GCC
        ./configure LDFLAGS=-no-undefined


## Xerces-C/C++ Transcoders and Plug-in Modules

Xerces-C/C++ XML Parsers have undergone some additional modularity
features.  In the version 3 series, the transcoders are no longer
integrated into the parsers.  There is a basic transcoding library.  Other
custom transcoding libraries can be registered at application runtime for
use.  Use of the transcoding modules is still experimental for Xalan-C/C++
transformation applications.

A plug-in memory management architecture was introduced in Xerces-C/C++
version 2.7.  The plug-in memory management of Xerces-C/C++ is also
supported by Xalan-C/C++ applications.