Building Xalan-C/C++
- The Distribution Source Tools
- Windows Build Environment
- Windows Basic Build Instruction
- Sample Windows Build Command File
- Installing the Xalan Library on Windows
- UNIX Build Environment
- Reference on Unix Platforms and C++ Compilers
- Xerces-C/C++ Transcoders and Plug-in Modules
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.
You can either install a compatible binary distribution of Xerces-C/C++ or build your own from a source distribution of Xerces-C/C++. You can gain additional capability if you build the Xerces-C/C++ XML Parser library from sources. The Xerces-C/C++ binary distribution is not built for the IBM-ICU libraries. The IBM-ICU libraries provide additional transcoding services.
Building from the source code packages for Xerces and Xalan libraries ensures that the resulting packages are proper for your system. There are various binary distributions available, but incompatibilities between C++ compilers (even between compiler versions) are known to cause issues with sharing of libraries.
You can get more information on the Xerces-C/C++ distributions at the http://xerces.apache.org/xerces-c web site.
The Distribution Source Tools
We are including in the distribution some script files that can help with build environment setup and distribution package creation. These script packages are working examples that developers can use for their own work.
-
(src)/scripts/xalan-ms-scripts.zip
For Windows Packages -
(src)/scripts/xalan-unix-scripts.tar
For Unix/Linux Packages
The following discussions in this chapter describe the rules by which these scripts were written.
Prepare Windows Build Scripts
I use the
C:\Apache\xalan-builds\
directory as the home path
for building Windows packages. You may need to edit the scripts for your own
package build location.
You will need a copy of Microsoft Visual Studio .NET installed on your development computer.
- Create your package building directory.
- Unzip the
xalan-ms-scripts.zip
into your package building directory. - Copy the Xerces-C sources into a builds subdirectory
xerces-src-31
. - Copy the Xalan-C sources into a builds subdirectory
xalan-src-11
. - You need the Xerces-C binaries available before building the Xalan-C sources.
- Build the Xerces-C sources using an appropriate
xerces-build-31-*.bat
script. This script launches Microsoft Visual Studio with an appropriate environment set. - Construct the Xerces-C binary package using the appropriate
xerces-inst-31-*.bat
script. This binary package is later used for the XERCESCPKG environment variable. - You can now create the Xalan-C binary package.
- Build the Xalan-C sources using an appropriate
xalan-build-11-31-*.bat
script. This script launches Microsoft Visual Studio with an appropriate environment set. - Construct the Xalan-C binary package using the apppropriate
xalan-inst-11-31-*.bat
script. This binary package can later be used for the XALANCPKG environment variable. - You can now copy the (XERCESCPKG-31)/bin to your Windows installation directory.
- You can now copy the (XALANCPKG-11-31)/bin to your Windows installation directory.
- You can also merge the (XERCESCPKG-31)/include and (XALANCPKG-11-31)/include to your Windows installation directory.
- You can also merge the (XERCESCPKG-31)/lib and (XALANCPKG-11-31)/lib to your Windows installation directory.
Prepare Unix Build Scripts
I use my
$HOME
directory as the path into which
xalan-unix-scripts.tar
is extracted.
I create subdirectory
xerces-src
for the Xerces-C sources and
another subdirectory
xalan-src
for the Xalan-C sources.
I then create separate directories into which the actual build process
takes place.
Directory
Xerces-Build
is where I make the Xerces-C binaries.
Directory
Xalan-Build
is where I make the Xalan-C binaries.
The following scripts are used to make and install the release build
of binary products to the
/opt/apache/
target directory path.
Connect to the appropriate build directory and execute the appropriate script.
- xerces-build.sh
- xalan-build.sh
The following scripts are used to make and install the debug build
of binary products to the
/opt/apache/debug/
target directory path.
Connect to the appropriate build directory and execute the appropriate script.
- xerces-build-debug.sh
- xalan-build-debug.sh
Windows Build Environment
Build support for Microsoft Visual Studio (VC6) is deprecated.
Building Xalan-C/C++ with Microsoft Visual Studio (VC6) requires the Xerces-C/C++ version 2.8 or older releases. Microsoft VC6 is removed from the Xerces-C/C++ Version 3.x releases.
Building Xalan-C/C++ with Microsoft Visual Studio .NET 2008 (VC9) requires Xerces-C/C++ version 3.1 or newer. Building with Microsoft Visual Studio .NET 2010 (VC10) requires Xerces-C/C++ version 3.1.1 or newer.
Environment variables XERCESCROOT and XALANCROOT are required. Environment ICUROOT is used only if building Xalan-C/C++ with IBM-ICU library support.
XERCESCROOT | The Xerces-C/C++ installation directory |
XALANCROOT | The Xalan-C/C++ source directory |
ICUROOT | The IBM-ICU installation directory (only if building with ICU support) |
I like to create command or batch files to setup the build environment variables and start the Visual Studio .NET development system using the custom build environment. I find this much easier than navigating the graphical interface to add custom build environments. The Microsoft *.vsprops custom property files are not available in the early versions of Visual Studio .NET platforms.
Windows Basic Build Instruction
If you want to create binary packages from the sources, you may wish to look at the Windows Build Command File in the next section.
A quick experiment in building for Windows is documented in the remainder of this section.
I have Visual Studio 2005, 2008, 2010 on one computer and VC6 and Visual Studio 2003 installed on another computer.
Microsoft Visual Studio .NET products will usually install a Visual Studio Command Prompt icon in the Visual Studio Tools subfolder for each version of Visual Studio installed on your computer. The Visual Studio Command Prompt automatically sets a basic development environment using a "vsvars32.bat" or "vcvarsall.bat" script for 32-bit or 64-bit platform builds, and leaves you at the command line for customizing your environment.
You then define the XERCESCROOT, XALANCROOT, and ICUROOT environment variables.
If the Xerces-C DLL files are not in directory %XERCESCROOT%\bin, you must add a directory to the PATH environment variable so the Xerces-C DLL files can be found.
You then launch the Visual Studio .NET by calling devenv
with a
path to the Xalan.sln
file as a parameter.
The following section describes how you can build your own scripts to create binary packages from Xalan-C compiled sources for the various versions of Microsoft Visual Studio products.
Sample Windows Build Command File
I like to use this template for both Xerces-C and Xalan-C builds from sources. The sample shown here is for Xalan-C/C++ because the installation of Xerces-C/C++ should already have been done.
SET XERCESCROOT="path to xerces-c installation" SET XALANCROOT="sources\xalan\c\"
Set the xalan project path for your version of Microsoft Visual Studio .NET.
:: VS 2003 (VC7.1) SET XALANCPROJDIR=%XALANCROOT%\Projects\Win32\VC7.1 :: VS 2005 (VC8) SET XALANCPROJDIR=%XALANCROOT%\Projects\Win32\VC8 :: VS 2008 (VC9) SET XALANCPROJDIR=%XALANCROOT%\Projects\Win32\VC9 :: VS 2010 (VC10) SET XALANCPROJDIR=%XALANCROOT%\Projects\Win32\VC10
Set some environment variables so we can easily copy or install the products after they have been built.
:: VS 2003 (VC7.1) SET XALANCBUILDDIR=%XALANCROOT%\Build\Win32\VC7.1 :: VS 2005 (VC8) SET XALANCBUILDDIR=%XALANCROOT%\Build\Win32\VC8 :: VS 2008 (VC9) SET XALANCBUILDDIR=%XALANCROOT%\Build\Win32\VC9 :: VS 2010 (VC10) SET XALANCBUILDDIR=%XALANCROOT%\Build\Win32\VC10
We use this Visual Studio .NET solution file.
SET XALANCBUILDSLN=%XALANCPROJDIR%\xalan.sln
The $(variable)
is expanded inside Visual Studio.
The %variable%
is expanded by the cmd utility before launching the Visual Studio.
SET PATH=%WINDIR%\system32;%WINDIR%;%WINDIR%\system32\Wbem SET INCLUDE= SET LIB= SET LIBPATH= SET SOURCE=
Set the default environment variables for your version of Microsoft Visual Studio .NET.
:: VS 2000 (VC7) - obsolete call "%VS70COMNTOOLS%vsvars32.bat" :: VS 2003 (VC7.1) 32-bit platform call "%VS71COMNTOOLS%vsvars32.bat" :: VS 2005 (VC8) 32-bit platform call "%VS80COMNTOOLS%vsvars32.bat" :: VS 2005 (VC8) 64-bit platform call "%VS80COMNTOOLS%\..\..\VC\vcvarsall.bat" x86_amd64 :: VS 2008 (VC9) 32-bit platform call "%VS90COMNTOOLS%vsvars32.bat" :: VS 2008 (VC9) 64-bit platform call "%VS90COMNTOOLS%\..\..\VC\vcvarsall.bat" x86_amd64 :: VS 2010 (VC10) 32-bit platform call "%VS100COMNTOOLS%vsvars32.bat" :: VS 2010 (VC10) 64-bit platform call "%VS100COMNTOOLS%\..\..\VC\vcvarsall.bat" x86_amd64
The LIBPATH and SOURCE environment variables may not be properly set by the vsvars32.bat command file. You may wish to start your Visual Studio .NET application without any custom environment and examine the Tools -> C/C++ project defaults for the various libraries. Then specifically set the paths in the build command file for your project.
The Xalan-C and Xerces-C libraries do not use the Microsoft Framework, the "mfc" and the "atl" directives. Microsoft is deprecating their "mfc" Microsoft Foundation Classes.
Define the necessary environment variables for building the Xalan-C/C++ libraries and sample programs.
SET PATH=%PATH%;%XERCESCROOT%\bin SET INCLUDE=%INCLUDE%;%XERCESCROOT%\include;%XERCESCROOT%\src SET INCLUDE=%INCLUDE%;%XALANCROOT%\src SET LIB=%LIB%;%XERCESCROOT%\lib
If you are going to build for IBM-ICU support, then add the following environments.
SET ICUROOT="path to ibm-icu installation" SET PATH=%PATH%;%ICUROOT%\bin SET INCLUDE=%INCLUDE%;%ICUROOT%\include SET LIB=%LIB%;%ICUROOT%\lib;%ICUROOT%\data
Now we should be ready to start the Microsoft Visual Studio .NET using our custom environment using the %XALANCBUILDSLN%
solution.
devenv.exe "%XALANCBUILDSLN%" /useenv
Installing the Xalan Library on Windows
The following command script will install the binary and header files to a target directory that is compatible with the XALANCROOT environment variable for creating applications. Environment variables other than XALANCTARGET are defined in the previous section, the Visual Studio .NET build example.
SET XALANCTARGET="path-to-target-directory" MKDIR "%XALANCTARGET%\bin" MKDIR "%XALANCTARGET%\include" MKDIR "%XALANCTARGET%\lib" CD "%XALANCBUILDDIR%\Release\Nls" COPY *.hpp "%XALANCTARGET%"\include CD "%XALANCBUILDDIR%\Release" COPY *.DLL "%XALANCTARGET%\bin" COPY *.LIB "%XALANCTARGET%\lib" COPY *.EXP "%XALANCTARGET%\lib" CD "%XALANCBUILDDIR%\Debug" COPY *.DLL "%XALANCTARGET%\bin" COPY *.PDB "%XALANCTARGET%\bin" COPY *.LIB "%XALANCTARGET%\lib" COPY *.EXP "%XALANCTARGET%\lib" CD "%XALANCROOT%\src XCOPY xalanc\*.hpp "%XALANCTARGET%\include\xalanc" /E /C /I /R /Y XCOPY xalanc\*.h "%XALANCTARGET%\include\xalanc" /E /C /I /R /Y
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 the
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 the
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/
You can use any empty file system or directory path with write access. Starting with an empty directory is a quick way to do a clean build. Make this empty directory to be your current working 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.
Finding Runtime 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 Xalan-C/C++ and Xerces-C/C++ shared library objects must be installed in a reachable library path for your platform. The make
step creates the libraries in the lib
subdirectory of your working directory. The make install
step installs these shared objects to the designated {prefix}/lib
directory or another directory defined by the --libdir
configuration parameter.
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 explicit library path environment variable 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 Libraries 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.
The Xalan-C/C++ configuration process uses the runConfigure
script as a front-end to the automake configure
script. Your shell command script should therefore use the runConfigure
script.
runConfigure Options | |
---|---|
Option | Description |
-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 |
Here are the names of some C/C++ compilers associated with commercial UNIX operating systems used to build Xalan-C/C++ and Xerces-C/C++ packages.
System | Platform | C Compiler | C++ Compiler | Comment |
---|---|---|---|---|
AIX | aix | xlc_r | xlC_r | thread support |
AIX | aix | xlc | xlC | no thread support |
Cygwin | cygwin | gcc | g++ | |
HP-UX | hp-11 | cc | aCC | |
HP-UX | hp-11-ia64 | cc | aCC | |
Solaris | solaris | cc | CC |
The following example shows you how to construct a usable script with your favorite text editor.
#!/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 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. If you run make from your build directory, then the # library and all sample programs will 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.
Configuration Options For Unix Platforms | |
---|---|
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 now being implemented as runtime modules. Use of the transcoding modules is still experimental for Xalan-C/C++ transformation applications. The basic transcoder capability still exists. Xerces-C/C++ version 2 series had transcoder libraries explicitly built and installed.
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.