Online Documentation Server
Net technology
Web technology
Data bases
Other docs



Вся предоставленная на этом сервере информация собрана нами из разных источников. Если Вам кажется, что публикация каких-то документов нарушает чьи-либо авторские права, сообщите нам об этом.

Building Xerces-C

This page answers the following questions:

Building on Windows NT/98

Xerces-C comes with Microsoft Visual C++ projects and workspaces to help you build Xerces-C. The following describes the steps you need to build Xerces-C.

Building Xerces-C library

To build Xerces-C from it source (using MSVC), you will need to open the workspace containing the project. If you are building your application, you may want to add the Xerces-C project inside your applications's workspace.

The workspace containing the Xerces-C project file and all other samples is:


Once you are inside MSVC, you need to build the project marked XercesLib.

If you want to include the Xerces-C project separately, you need to pick up:


You must make sure that you are linking your application with the xerces-c_1.lib library and also make sure that the associated DLL is somewhere in your path.


If you are working on the AlphaWorks version which uses ICU, you must have the ICU data DLL named icudata.dll available from your path setting. For finding out where you can get ICU from and build it, look at the How to Build ICU.

Building samples

Inside the same workspace (xerces-all.dsw), you'll find several other projects. These are for the samples. Select all the samples and right click on the selection. Then choose "Build (selection only)" to build all the samples in one shot.

Building on UNIX platforms

Xerces-C uses GNU tools like Autoconf and GNU Make to build the system. You must first make sure you have these tools installed on your system before proceeding. If you don not have required tools, ask your system administrator to get them for you. These tools are free under the GNU Public Licence and may be obtained from the Free Software Foundation.

Do not jump into the build directly before reading this.

Spending some time reading the following instructions will save you a lot of wasted time and support-related e-mail communication. The Xerces-C build instructions are a little different from normal product builds. Specifically, there are some wrapper-scripts that have been written to make life easier for you. You are free not to use these scripts and use Autoconf and GNU Make directly, but we want to make sure you know what you are by-passing and what risks you are taking. So read the following instructions carefully before attempting to build it yourself.

Besides having all necessary build tools, you also need to know what compilers we have tested Xerces-C on. The following table lists the relevant platforms and compilers.

Operating System  C++, C Compilers 
Redhat Linux 6.1  g++, gcc (egcs) 
AIX 4.2.1 and higher  xlC_r, xlc_r 
Solaris 2.6  CC, cc 
HP-UX 11  aCC, cc 

If you are not using any of these compilers, you are taking a calculated risk by exploring new grounds. Your effort in making Xerces-C work on this new compiler is greatly appreciated and any problems you face can be addressed on the Xerces-C mailing list.

Differences between the UNIX platforms: The description below is generic, but as every programmer is aware, there are minor differences within the various UNIX flavors the world has been bestowed with. The one difference that you need to watch out in the discussion below, pertains to the system environment variable for finding libraries. On Linux and Solaris, the environment variable name is called LD_LIBRARY_PATH, on AIX it is LIBPATH, while on HP-UX it is SHLIB_PATH. The following discussion assumes you are working on Linux, but it is with subtle understanding that you know how to interpret it for the other UNIX flavors.


If you wish to build Xerces-C with ICU, look at the Building ICU. It tells you where you can get ICU and how to build Xerces-C with it.

Setting build environment variables

Before doing the build, you must first set your environment variables to pick-up the compiler and also specify where you extracted Xerces-C on your machine. While the first one is probably set for you by the system administrator, just make sure you can invoke the compiler. You may do so by typing the compiler invocation command without any parameters (e.g. xlc_r, or g++, or cc) and check if you get a proper response back.

Next set your Xerces-C root path as follows:

export XERCESCROOT=<full path to xerces-c-src1_4_0>

This should be the full path of the directory where you extracted Xerces-C.

Building Xerces-C library

As mentioned earlier, you must be ready with the GNU tools like autoconf and gmake before you attempt the build.

The autoconf tool is required on only one platform and produces a set of portable scripts (configure) that you can run on all other platforms without actually having the autoconf tool installed everywhere. In all probability the autoconf-generated script (called configure) is already in your src directory. If not, type:


This generates a shell-script called configure. It is tempting to run this script directly as is normally the case, but wait a minute. If you are using the default compilers like gcc and g++ you do not have a problem. But if you are not on the standard GNU compilers, you need to export a few more environment variables before you can invoke configure.

Rather than make you to figure out what strange environment variables you need to use, we have provided you with a wrapper script that does the job for you. All you need to tell the script is what your compiler is, and what options you are going to use inside your build, and the script does everything for you. Here is what the script takes as input:

runConfigure: Helper script to run "configure" for one of the
              supported platforms.
Usage: runConfigure "options"
       where options may be any of the following:
       -p <platform> (accepts 'aix', 'linux', 'solaris',
                            'hp-10', 'hp-11', 'irix', 'unixware')
       -c <C compiler name> (e.g. xlc_r, gcc, cc)
       -x <C++ compiler name> (e.g. xlC_r, g++, CC, aCC)
       -d (specifies that you want to build debug version)
       -m <message loader> can be 'inmem', 'icu', 'iconv'
       -n <net accessor> can be 'fileonly', 'libwww'
       -t <transcoder> can be 'icu' or 'native'
       -r <thread option> can be 'pthread' or 'dce'
	    (only used on HP-11)
       -l <extra linker options>
       -z <extra compiler options>
       -h (to get help on the above commands)

Xerces-C can be built as either a standalone library or as a library dependent on International Components for Unicode (ICU). For simplicity, the following discussion only explains standalone builds.

One of the common ways to build Xerces-C is as follows:

runConfigure -plinux -cgcc -xg++ -minmem -nfileonly -tnative

The response will be something like this:

Generating makefiles with the following options ...
Platform: linux
C Compiler: gcc
C++ Compiler: g++
Extra compile options:
Extra link options:
Message Loader: inmem
Net Accessor: fileonly
Transcoder: native
Thread option:
Debug is OFF

creating cache ./config.cache
checking for gcc... gcc
checking whether the C compiler (gcc -O -DXML_USE_NATIVE_TRANSCODER
checking whether the C compiler (gcc -O -DXML_USE_NATIVE_TRANSCODER
 -DXML_USE_INMEM_MESSAGELOADER   ) is a cross-compiler... no
checking whether we are using GNU C... yes
checking whether gcc accepts -g... yes
checking for c++... g++
checking whether the C++ compiler (g++ -O -DXML_USE_NATIVE_TRANSCODER
checking whether the C++ compiler (g++ -O -DXML_USE_NATIVE_TRANSCODER
 -DXML_USE_INMEM_MESSAGELOADER   ) is a cross-compiler... no
checking whether we are using GNU C++... yes
checking whether g++ accepts -g... yes
checking for a BSD compatible install... /usr/bin/install -c
checking for autoconf... autoconf
checking for floor in -lm... yes
checking how to run the C preprocessor... gcc -E
checking for ANSI C header files... yes
checking for XMLByte... no
checking host system type... i686-pc-linux-gnu
updating cache ./config.cache
creating ./config.status
creating Makefile
creating util/Makefile
creating util/Transcoders/ICU/Makefile
creating util/Transcoders/Iconv/Makefile
creating util/Transcoders/Iconv390/Makefile
creating util/Transcoders/Iconv400/Makefile
creating util/Platforms/Makefile
creating util/Compilers/Makefile
creating util/MsgLoaders/InMemory/Makefile
creating util/MsgLoaders/ICU/Makefile
creating util/MsgLoaders/MsgCatalog/Makefile
creating util/MsgLoaders/MsgFile/Makefile
creating validators/DTD/Makefile
creating framework/Makefile
creating dom/Makefile
creating parsers/Makefile
creating internal/Makefile
creating sax/Makefile
creating ../obj/Makefile
creating conf.h
cat: ./ No such file or directory
conf.h is unchanged

Having build problems? Read
instructions at
Still cannot resolve it? Find out if someone else had
the same problem before.
Check the mailing list archives at

In future, you may also directly type the following commands
to create the Makefiles.

export USELIBWWW=0
export CC=gcc
export CXX=g++
export LIBS= -lpthread

If the result of the above commands look OK to you,
go to the directory
XERCESCROOT and type "gmake" to make
the XERCES-C system.
NoteThe error message concerning conf.h is NOT an indication of a problem. This code has been inserted to make it work on AS/400, but it gives this message which appears to be an error. The problem will be fixed in future.

So now you see what the wrapper script has actually been doing! It has invoked configure to create the Makefiles in the individual sub-directories, but in addition to that, it has set a few environment variables to correctly configure your compiler and compiler flags too.

Now that the Makefiles are all created, you are ready to do the actual build.


Is that it? Yes, that's all you need to build Xerces-C.

Building samples

Similarly, you can build the samples by giving the same commands in the samples directory.

cd $XERCESCROOT/samples
runConfigure -plinux -cgcc -xg++

The samples get built in the bin directory. Before you run the samples, you must make sure that your library path is set to pick up libraries from $XERCESCROOT/lib. If not, type the following to set your library path properly.


You are now set to run the sample applications.

Building Xerces-C on Windows using Visual Age C++

A few unsupported projects are also packaged with Xerces-C. Due to origins of Xerces-C inside IBM labs, we do have projects for IBM's Visual Age C++ compiler on Windows. The following describes the steps you need to build Xerces-C using Visual Age C++.

Building Xerces-C library


  • VisualAge C++ Version 4.0 with Fixpak 1:
    Download the Fixpak from the IBM VisualAge C++ Corrective Services web page.

To include the ICU library:

  • ICU Build:
    You should have the ICU Library in the same directory as the Xerces-C library. For example if Xerces-C is at the top level of the d drive, put the ICU library at the top level of d e.g. d:/xml4c, d:/icu.


  1. Change the directory to d:\xml4c\Projects\Win32
  2. If a d:\xml4c\Project\Win32\VACPP40 directory does not exist, create it.
  3. Copy the IBM VisualAge project file, XML4C2X.icc, to the VACPP40 directory.
  4. From the VisualAge main menu enter the project file name and path.
  5. When the build finishes the status bar displays this message: Last Compile completed Successfully with warnings on date.

These instructions assume that you install in drive d:\. Replace d with the appropriate drive letter.

Building on OS/2 using Visual Age C++

OS/2 is a favourite IBM PC platforms. The only option in this platform is to use Visual Age C++ compiler. Here are the steps you need to build Xerces-C using Visual Age C++ on OS/2.

Building Xerces-C library


  • VisualAge C++ Version 4.0 with Fixpak 1:
    Download the Fixpak from the IBM VisualAge C++ Corrective Services web page.

There are two ways to build Xerces-C. The "From Existing" method only requires VAC++. The "From Scratch" method requires both Object Rexx and VAC++ installed.

The "From Existing" Method

  1. In the xerces-c-src1_4_0\Projects\OS2\VACPP40 directory, find and edit the VAC++ configuration file project_options.icc.
  2. Change the directory on the first line 'BASE_DIR = "..."' to match the base directory of the Xerces-C sources on your system. Note that the directory path must use double backslashes "\\"!
  3. Save project_options.icc
  4. Start the Command Line in the VAC++ folder.
  5. Navigate to the xerces-c-src1_4_0\Projects\OS2\VACPP40 directory.
  6. Run build.cmd. This does a migration build.
  7. When build.cmd finishes, review the file compiler.errors. This file should contain only informational messages, almost all complaining about constant values in comparisons.
  8. You should now have a xerces-c.dll and xerces-c.lib. The library file is an import library for the DLL.

The "From Scratch" Method

  1. If you are not currently running Object Rexx, run the SWITCHRX command from a command line, answer "yes" to switching to Object Rexx, and follow the instructions to reboot. You can switch back to "Classic Rexx" by running SWITCHRX again. But you probably won't need to switch back since Object Rexx runs almost 100% of Classic Rexx programs.
  2. In the xerces-c-src1_4_0\Projects\OS2\VACPP40 directory, run genICC.cmd. This builds the VAC++ configuration files for the sources you have on your system.
  3. Check the generated ICC files to ensure that they didn't pick up some non-OS/2 platform stuff. This happens when new platform-specific directories are added to Xerces. If they did pick up new non-OS/2 stuff, either edit it out of the ICC file or add them to the "ignore" array in genICC.cmd and re-run genICC.
  4. Start the Command Line in the VAC++ folder.
  5. Navigate to the xerces-c-src1_4_0\Projects\OS2\VACPP40 directory.
  6. Run build.cmd This does a migration build.
  7. When build.cmd finishes, review the file compiler.errors. This file should contain only informational messages, almost all complaining about constant values in comparisons.
  8. You should now have a xerces-c.dll and xerces-c.lib. The library file is an import library for the DLL.)

Packaging the Binaries

There is an Object Rexx program that will package the binaries and headers. (See step 1 of the "From scratch" method on how to switch to Object Rexx.) The packageBinaries.cmd file is in the xerces-c-src1_4_0\Projects\OS2\VACPP40 directory. Run packageBinaries, giving the source and target directories like this:

packageBinaries -s x:\xerces-c-src1_4_0 -o x:\temp\xerces-c1_4_0-os2

(Match the source directory to your system; the target directory can be anything you want.)


If you don't want to use the Object Rexx program, you'll need to manually copy the "*.hpp" and "*.c" files to an include directory. (Be sure to maintain the same directory structure that you find under xerces-c-src1_4_0.)

Building on AS/400

The following addresses the requirements and build of Xerces-C natively on the AS/400.

Building Xerces-C library


  • QSHELL interpreter installed (install base option 30, operating system)
  • QShell Utilities, PRPQ 5799-XEH
  • ILE C++ for AS/400, PRPQ 5799-GDW
  • GNU facilities (the gnu facilities are currently available by request only. Send e-mail to


  • There are a couple of options when building the XML4C parser on AS/400. For messaging support, you can use the in memory message option or the message file support. For code page translation, you can use the AS/400 native Iconv400 support or ICU. If you choose ICU, follow the instructions to build the ICU service program with the ICU download. Those instructions are not included here.
  • Currently we recommend that you take the options of MsgFile and Iconv400 (see below)

Setup Instructions:

  • Make sure that you have the requirements installed on your AS/400. We highly recommend that you read the writeup that accompanies the gnu facilities download. There are install instructions as well as information about how modules, programs and service programs can be created in Unix-like fashion using gnu utilities. Note that symbolic links are use in the file system to point to actual AS/400 *module, *pgm and *srvpgm objects in libraries.
  • Download the tar file (unix version) to the AS/400 (using a mapped drive), and decompress and untar the source. We have had difficulty with the tar command on AS/400. This is under investigation. If you have trouble, we recommend the following work around:
gunzip -d <tar file.gz>
pax -r -f <uncompressed tar file>
  • Create AS400 target library. This library will be the target for the resulting modules and Xerces-C service program. You will specify this library on the OUTPUTDIR environment variable in step 4
  • Set up the following environment variables in your build process (use ADDENVVAR or WRKENVVAR CL commands):
XERCESCROOT - <the full path to your Xerces-C sources>
MAKE   - '/usr/bin/gmake'
OUTPUTDIR  - <identifies target as400 library for *module,
 *pgm and *srvpgm objects>
ICUROOT - (optional if using ICU)  <the path of your ICU includes>
  • Add QCXXN, to your build process library list. This results in the resolution of CRTCPPMOD used by the icc compiler.
  • The runConfigure instruction below uses 'egrep'. This is not on the AS/400 but you can create it by doing the following: edtf '/usr/bin/egrep' with the following source:
/usr/bin/grep -e "$@"

You may want to put the environment variables and library list setup instructions in a CL program so you will not forget these steps during your build.


To configure the make files for an AS/400 build do the following:

cd <full path to Xerces-C>/src
runConfigure -p os400 -x icc -c icc -m MsgFile -t Iconv400


error: configure: error: installation or configuration problem:
C compiler cannot create executables.

If during runConfigure you see the above error message, it can mean one of two things. Either QCXXN is not on your library list OR the runConfigure cannot create the temporary modules (CONFTest1, etc) it uses to test out the compiler options. The second reason happens because the test modules already exist from a previous run of runConfigure. To correct the problem, do the following:

DLTMOD <your OUTPUTDIR library>/CONFT* and


gmake -e

The above gmake will result in a service program being created in your specified library and a symbolic link to that service program placed in <path to Xerces-C/lib>. You can either bind your XML application programs directly to the parser's service program via the BNDSRVPGM option on the CRTPGM or CRTSRVPGM command or you can specify a binding directory on your icc command. To specify an archive file to bind to, use the -L, -l binding options on icc. An archive file on AS/400 is a binding directory. To create an archive file, use qar command. (see the gnu facilities write up).

After building the Xerces-C service program, create a binding directory by doing the following (note, this binding directory is used when building the samples):

cd <full path to Xerces-C>/lib>
qar -cuv libxercesc1_1.a *.o
command = CRTBNDDIR BNDDIR(yourlib/libxercesc)
command = ADDBNDDIRE BNDDIR(yourlib/libxercesc)


If you are on a V4R3 system, you will get a bind problem 'descriptor QlgCvtTextDescToDesc not found' using Iconv400. On V4R3 the system doesn't automatically pick up the QSYS/QLGUSR service program for you when resolving this function. This is not the case on V4R4. To fix this, you can either manually create the service program after creating all the resulting modules in your <OUTPUTDIR> library or you can create a symbolic link to a binding directory that points to the QLGUSR service program and then specify an additional -L, -l on the EXTRA_LINK_OPTIONS in Makefile.incl. See the ln and qar function in the gnu utilities.

To build for transcoder ICU:

  1. Make sure you have an ICUROOT path set up so that you can find the ICU header files (usually /usr/local)
  2. Make sure you have created a binding directory (symbolic link) in the file system so that you can bind the Xerces-C service program to the ICU service program and specify that on the EXTRA_LINK_OPTIONS in src/Makefile.incl (usually the default is a link in /usr/local/lib).

Creating AS400 XML parser message file:

As specified earlier, the -m MsgFile support on the runConfigure enable the parser messages to be pulled from an AS/400 message file. To view the source for creating the message file and the XML parser messages, see the following stream file:

EDTF <full path to Xerces-C>/src/util/MsgLoaders/MsgFile/CrtXMLMsgs

In the prolog of CrtXMLMsgs there are instructions to create the message file:

  1. Use the CPYFRMSTMF to copy the CL source to an AS/400 source physical file. Note that the target source file needs to have record length of about 200 bytes to avoid any truncation.
  2. Create the CL program to create the message file and add the various message descriptions
  3. Call the CL program, providing the name of the message file (use QXMLMSG as default) and a library (this can be any library, including any product library in which you wish to embed the xml parser)

Note that the Xerces-C source code for resolving parser messages is using by default message file QXMLMSG, *LIBL. If you want to change either the message file name or explicitly qualify the library to match your product needs, you must edit the following .cpp files prior to your build.

<full path to Xerces-C>/src/util/MsgLoaders/MsgFile/MsgLoader.cpp
<full path to Xerces-C>/src/util/Platforms/OS400/OS400PlatformUtils.cpp


If you are using the parser and are failing to get any message text for error codes, it may be because of the *LIBL resolution of the message file.

Building Samples on AS/400

cd <full path to Xerces-C>/samples
runConfigure -p os400 -x icc -c icc
gmake -e


If you take a 'sed' error, while trying to make the samples. This is an AS400 anomaly having to do with certain new line character and the sed function. A temporary work around is to use EDTF on the configure stream file (../samples/configure) and delete the following line near the bottom: s%@DEFS@%$DEFS%g.

Building on Macintosh using CodeWarrior

Building Xerces-C library

The directions in this file cover installing and building Xerces-C and ICU under the MacOS using CodeWarrior.

  1. Create a folder:
    for the Xerces-C and ICU distributions, the "src drop" folder
  2. Download and uncompress:
    the ICU and Xerces-C source distribution
    the ICU and Xerces-C binary distributions, for the documentation included
  3. Move the new folders:
    move the newly created Xerces-C and icu124 folders to the "src drop" folder.
  4. Drag and drop:
    the Xerces-C folder into the "rename file" application located in the same folder as this readme.
    This is a MacPerl script that renames files that have names too long to fit in a HFS/HFS+ filesystem. It also searches through all of the source code and changes the #include statements to refer to the new file names.
  5. Move the MacOS folder:
    from the in the Projects folder to "src drop:Xerces-C:Projects".
  6. Open and build Xerces-C:
    open the CodeWarrior project file "src drop:Xerces-C:Projects:MacOS:Xerces-C:Xerces-C" and build the Xerces-C library.
  7. Open and build ICU:
    open the CodeWarrior project file "src drop:Xerces-C:Projects:MacOS:icu:icu" and build the ICU library.
  8. Binary distribution:
    If you wish, you can create projects for and build the rest of the tools and test suites. They are not needed if you just want to use Xerces-C. I suggest that you use the binary data files distributed with the binary distribution of ICU instead of creating your own from the text data files in the ICE source distribution.

There are some things to be aware of when creating your own projects using Xerces-C.

  1. You will need to link against both the ICU and Xerces-C libraries.
  2. The options "Always search user paths" and "Interpret DOS and Unix Paths" are very useful. Some of the code won't compile without them set.
  3. Most of the tools and test code will require slight modification to compile and run correctly (typecasts, command line parameters, etc), but it is possible to get them working correctly.
  4. You will most likely have to set up the Access Paths. The access paths in the Xerces-C projects should serve as a good example.

These instructions were originally contributed by J. Bellardo. Xerces-C has undergone many changes since these instructions were written. So, these instructions are not upto date. But it will give you a jump start if you are struggling to get it to work for the first time. We will be glad to get your changes. Please respond to with your comments and corrections.

How to Build ICU

As mentioned earlier, Xerces-C may be built in stand-alone mode using native encoding support and also using ICU where you get support over 180 different encodings. ICU stands for International Components for Unicode and is an open source distribution from IBM. You can get ICU libraries from IBM's developerWorks site or go to the ICU download page directly.

Buiding ICU for Xerces-C

You can find generic instructions to build ICU in the ICU documentation. What we describe below are the minimal steps needed to build ICU for Xerces-C. Not all ICU components need to be built to make it work with Xerces-C.


Important: Please remember that ICU and Xerces-C must be built with the same compiler, preferably with the same version. You cannot for example, build ICU with a threaded version of the xlC compiler and build Xerces-C with a non-threaded one.

Building ICU on Windows

To build ICU from its source, invoke the project \icu\source\allinone\allinone.dsw and build the sub-project labeled all.

You must make sure that you are linking your application with the xerces-c_1.lib library and also make sure that the associated Xerces-C DLL is somewhere in your path. Note that at runtime, your application will need the ICU data DLL called icudata.dll which must also be available from your path setting.

Building ICU on UNIX platforms

To build ICU on all UNIX platforms you at least need the autoconf tool and GNU's gmake utility.

First make sure that you have defined the following environment variables:

export ICUROOT = <icu_installdir>

Next, go to the directory, the following commands will create a shell script called configure:

cd source

Commands for specific UNIX platforms are different and are described separately below.

You will get a more detailed description of the use of configure in the ICU documentation. The differences lie in the arguments passed to the configure script, which is a platform-independent generated shell-script (through autoconf) and is used to generate platform-specific Makefiles from generic files.

For AIX:

Type the following:

env CC="xlc_r -L/usr/lpp/xlC/lib" CXX="xlC_r -L/usr/lpp/xlC/lib"
    C_FLAGS="-w -O" CXX_FLAGS="-w -O"
configure --prefix=$ICUROOT
gmake install

The first line is different for different platforms as outlined below:

For Solaris and Linux:

env CC="cc" CXX="CC" C_FLAGS="-w -O" CXX_FLAGS="-w -O"
    ./configure --prefix=$ICUROOT

For HP-UX with the aCC compiler:

env CC="cc" CXX="aCC" C_FLAGS="+DAportable -w -O"
    CXX_FLAGS="+DAportable -w -O" ./configure --prefix=$ICUROOT

For HP-UX with the CC compiler:

env CC="cc" CXX="CC" C_FLAGS="+DAportable -w -O"
    CXX_FLAGS="+eh +DAportable -w -O" ./configure --prefix=$ICUROOT

Building Xerces-C with ICU using bundled Perl scripts

To simplify the builds, we use the bundled perl script ''. It requires some setup, but once it is done, repeating it becomes easy. Here's how we do it.


  • Perl 5.004 or higher
  • Cygwin tools or MKS Toolkit
  • zip.exe

Steps are:

  1. Download the appropriate ICU source archive.
  2. Download Xerces-C source archive.
  3. Build ICU.
  4. Build Xerces-C with ICU.

Download Xerces-C from directory.

Download the appropriate archive for ICU from:

For Windows

Extract Xerces-C source files from the .zip archive using WinZip, say in the root directory (an arbitrary drive x:). It should create a directory like 'x:\xerces-c-src1_4_0'.

Extract the ICU files, using WinZip, in root directory of the disk where you have installed Xerces-C, sources. After extraction, there should be a new directory 'x:\icu' which contains all the ICU source files.

There are two options to build Xerces-C with ICU. One is to use the MSDEV GUI environment, and the other is to invoke the compiler from the command line.

Using, the GUI environment, requires one to edit the project files. Here, we will describe only the second option. It involves using the perl script ''.

Start a command prompt to get a new shell window. Make sure you have perl, cygwin tools (uname, rm, cp, ...), and zip.exe somewhere in the path. Next setup the environment for MSVC using 'VCVARS32.BAT' or a similar file. Next at the prompt enter:

set XERCESCROOT=x:\xerces-c-src1_4_0
set ICUROOT=x:\icu
cd x:\xerces-c-src1_4_0\scripts
perl -s x:\xerces-c-src1_4_0 -o
 x:\temp\xerces-c1_4_0-win32 -t icu

(Match the source directory to your system; the target directory can be anything you want.)

If everything is setup right and works right, then you should see a binary drop created in the target directory specified above. This script will build both ICU and Xerces-C, copy the files (relevant to the binary drop) to the target directory.

For a description of options available, you can enter:


How to build XML for COM on Windows

To build the COM module for use with XML on Windows platforms, you must first set up your machine appropriately with necessary tools and software modules and then try to compile it. The end result is an additional library that you can use along with the standard Xerces-C for writing VB templates or for use with IE 5.0 using JavaScript.

Setting up your machine for COM

To build the COM project you will need to install the MS PlatformSDK. Some of the header files we use don't come with Visual C++ 6.0. You may download it from Microsoft's Website at or directly FTP it from

The installation is huge, but you don't need most of it. So you may do a custom install by just selecting "Build Environment" and choosing the required components. First select the top level Platform SDK. Then click the down arrow and make all of the components unavailable. Next open the "Build Environment" branch and select only the following items:

  • Win32 API
  • Component Services
  • Web Services - Internet Explorer

Important: When the installation is complete you need to update VC6's include path to include ..\platformsdk\include\atl30. You do this by choosing "Tools -> Options -> Directories". This path should be placed second after the normal PlatformSDK include. You change the order of the paths by clicking the up and down arrows.


The order in which the directories appear on your path is important. Your first include path should be ..\platformsdk\include. The second one should be ..\platformsdk\include\atl30.

Building COM module for Xerces-C

Once you have set up your machine, build Xerces-C COM module by choosing the project named 'xml4com' inside the workspace. Then select your build mode to be xml4com - Win32 Release MinDependency. Finally build the project. This will produce a DLL named xerces-com.dll which needs to be present in your path (on local machine) before you can use it.

Testing the COM module

There are some sample test programs in the test/COMTest directory which show examples of navigating and searching an XML tree using DOM. You need to browse the HTML files in this directory using IE 5.0. Make sure that your build has worked properly, specially the registration of the ActiveX controls that happens in the final step.

You may also want to check out the NIST DOM test suite at You will have to modify the documents in the NIST suite to load the Xerces COM object instead of the MSIE COM object.

How to build the User Documentation?

The user documentation (this very page that you are reading on the browser right now), was generated using an XML application called StyleBook. This application makes use of Xerces-J and Xalan to create the HTML file from the XML source files. The XML source files for the documentation are part of the Xerces-C module. These files reside in the doc directory.

Pre-requisites for building the user documentation are:

  • JDK 1.2.2 (or later).
  • Xerces-J 1.0.1.bundled
  • Xalan-J 0.19.2.bundled
  • Stylebook 1.0-b2.bundled
  • The Apache Style files (dtd's and .xsl files).bundled

Invoke a command window and setup PATH to include the JDK 1.2.2 bin directory

Next, cd to the Xerces-C source drop root directory, and enter

  • Under Windows:
  • Under Unix's:
    sh createDocs.bat

This should generate the .html files in the 'doc/html' directory.

I wish to port Xerces to my favourite platform. Do you have any suggestions?

All platform dependent code in Xerces has been isolated to a couple of files, which should ease the porting effort. Here are the basic steps that should be followed to port Xerces.

  1. The directory src/util/Platforms contains the platform sensitive files while src/util/Compilers contains all development environment sensitive files. Each operating system has a file of its own and each development environment has another one of its own too.
    As an example, the Win32 platform as a Win32Defs.hpp file and the Visual C++ environment has a VCPPDefs.hpp file. These files set up certain define tokens, typedefs, constants, etc... that will drive the rest of the code to do the right thing for that platform and development environment. AIX/CSet have their own AIXDefs.hpp and CSetDefs.hpp files, and so on. You should create new versions of these files for your platform and environment and follow the comments in them to set up your own. Probably the comments in the Win32 and Visual C++ will be the best to follow, since that is where the main development is done.
  2. Next, edit the file XML4CDefs.hpp, which is where all of the fundamental stuff comes into the system. You will see conditional sections in there where the above per-platform and per-environment headers are brought in. Add the new ones for your platform under the appropriate conditionals.
  3. Now edit AutoSense.hpp. Here we set canonical Xerces internal #define tokens which indicate the platform and compiler. These definitions are based on known platform and compiler defines.
    AutoSense.hpp is included in XML4CDefs.hpp and the canonical platform and compiler settings thus defined will make the particular platform and compiler headers to be the included at compilation.
    It might be a little tricky to decipher this file so be careful. If you are using say another compiler on Win32, probably it will use similar tokens so that the platform will get picked up already using what is already there.
  4. Once this is done, you will then need to implement a version of the platform utilities for your platform. Each operating system has a file which implements some methods of the XMLPlatformUtils class, specific to that operating system. These are not terribly complex, so it should not be a lot of work. The Win32 verions is called Win32PlatformUtils.cpp, the AIX version is AIXPlatformUtils.cpp and so on. Create one for your platform, with the correct name, and empty out all of the implementation so that just the empty shells of the methods are there (with dummy returns where needed to make the compiler happy.) Once you've done that, you can start to get it to build without any real implementation.
  5. Once you have the system building, then start implementing your own platform utilties methods. Follow the comments in the Win32 version as to what they do, the comments will be improved in subsequent versions, but they should be fairly obvious now. Once you have these implementations done, you should be able to start debugging the system using the demo programs.

That is the work required in a nutshell!

What should I define XMLCh to be? And what is the relationship between XMLCh and wchar_t?

XMLCh should be defined to be a type suitable for holding a utf-16 encoded (16 bit) value, usually an unsigned short.

All XML data is handled within xerces-c as strings of XMLCh characters. Regardless of the size of the type chosen, the data stored in variables of type XMLCh will always be utf-16 encoded values.

Unlike XMLCh, the encoding of wchar_t is platform dependent. Sometimes it is utf-16 (AIX, Windows), sometimes ucs-4 (Solaris, Linux), sometimes it is not based on Unicode at all (HP/UX, AS/400, system 390).

Some earlier releases of xerce-c defined XMLCh to be the same type as wchar_t on most platforms, with the goal of making it possible to pass XMLCh strings to library or system functions that were expecting wchar_t paramters. This approach has been abandonded because of

  • Portability problems with any code that assumes that the types of XMLCh and wchar_t are compatible
  • Excessive memory usage, especially in the DOM, on platforms with 32 bit wchar_t.
  • utf-16 encoded XMLCh is not always compatible with ucs-4 encoded wchar_t on Solaris and Linux. The problem occurs with Unicode characters with values greater than 64k; in ucs-4 the value is stored as a single 32 bit quatity. With utf-16, the value will be stored as a "surrogate pair" of two 16 bit values. Even with XMLCh equated to wchar_t, xerces will still create the utf-16 encoded surrogate pairs, which are illegal in ucs-4 encoded wchar_t strings.

How do I build a single-threaded library on Unix platforms?

To build a single-threaded library on Unix platforms you have to update one or more of the following files Makefile.incl,, runConfigure. The following steps guide you to create a single-threaded library for each platform:

For Aix -

  • Replace xlc_r and xlC_r libraries with xlc and xlC respectively
  • Replace makeC++SharedLib_r with makeC++SharedLib
  • Remove the flag -D_THREAD_SAFE
  • Remove inclusion of any threaded library directories from the LIBPATH
  • Remove inclusion of -lpthreads and -lpthread_compat
  • Add -DAPP_NO_THREADS to define the variable under AIX specific options in Makefile.incl

For Solaris -

  • Add -DAPP_NO_THREADS to define the variable under SOLARIS specific options in Makefile.incl
  • Remove compiler switch -mt
  • Remove -D_REENTRANT flag from the 'compile' options
  • Remove inclusion of -lpthread

For Linux -

  • Add -DAPP_NO_THREADS to define the variable under LINUX specific options in Makefile.incl
  • Remove -D_REENTRANT flag from the 'compile' options
  • Remove inclusion of -lpthread

For HPUX -

  • Add -DAPP_NO_THREADS to define the variable under HP specific options in Makefile.incl
  • Remove inclusion of -lpthread and -lcma
  • Remove threading defines like -D_PTHREADS_DRAFT4 , -DXML_USE_DCE

Where can I look for more help?

If you have read this page, followed the instructions, and still cannot resolve your problem(s), there is more help. You can find out if others have solved this same problem before you, by checking the Apache XML mailing list archives at

Copyright © 2000 The Apache Software Foundation. All Rights Reserved.

With any suggestions or questions please feel free to contact us