This page answers the following questions:
 |  |  |  | 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. |
 |  |  |  | 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:
 |  |  |  | cd $XERCESCROOT/src
autoconf |  |  |  |  |
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
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 -DXML_USE_INMEM_MESSAGELOADER ) works... yes
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 -DXML_USE_INMEM_MESSAGELOADER ) works... yes
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: ./conf.h.in: No such file or directory
conf.h is unchanged
Having build problems? Read instructions at http://xml.apache.org/xerces-c/build.html
Still cannot resolve it? Find out if someone else had the same problem before.
Check the mailing list archives at http://archive.covalent.net.
In future, you may also directly type the following commands to create the Makefiles.
export TRANSCODER=NATIVE
export MESSAGELOADER=INMEM
export USELIBWWW=0
export CC=gcc
export CXX=g++
export CXXFLAGS=-O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER
export CFLAGS=-O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER
export LIBS= -lpthread
configure
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. |  |  |  |  |
 | The 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 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.
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 |  |  |  |  |
| |
- In the
xerces-c-src1_4_0\Projects\OS2\VACPP40 directory,
find and edit the VAC++ configuration file project_options.icc .
- 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 "\\" !
- Save
project_options.icc
- Start the Command Line in the VAC++ folder.
- Navigate to the
xerces-c-src1_4_0\Projects\OS2\VACPP40 directory.
- Run
build.cmd . This does a migration build.
- When
build.cmd finishes, review the file compiler.errors .
This file should contain only informational messages, almost all complaining
about constant values in comparisons.
- 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 |  |  |  |  |
| |
- 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.
- 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.
- 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 .
- Start the Command Line in the VAC++ folder.
- Navigate to the
xerces-c-src1_4_0\Projects\OS2\VACPP40 directory.
- Run
build.cmd This does a migration build.
- When
build.cmd finishes, review the file compiler.errors .
This file should contain only informational messages, almost all complaining about constant
values in comparisons.
- You should now have a
xerces-c.dll and xerces-c.lib .
The library file is an import library for the DLL.)
|
|
| |
The following addresses the requirements and build of
Xerces-C natively on the AS/400.
 |  |  |  | Building Xerces-C library |  |  |  |  |
| |
Requirements:
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 rchgo400@us.ibm.com)
Recommendations:
- 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:
 |  |  |  |
qsh:
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>
PLATFORM - 'OS400'
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/sh
/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.
Configure
To configure the make files for an AS/400 build do the following:
 |  |  |  |
qsh
cd <full path to Xerces-C>/src
runConfigure -p os400 -x icc -c icc -m MsgFile -t Iconv400 |  |  |  |  |
Troubleshooting:
 |  |  |  | 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
DLTPGM your <OUTPUTDIR library>/CONFT* |  |  |  |  |
Build
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):
 |  |  |  |
qsh
cd <full path to Xerces-C>/lib>
qar -cuv libxercesc1_1.a *.o
command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/Xerces-C/lib/libxercesc1_1.a')
command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) ) |  |  |  |  |
Troubleshooting:
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:
- Make sure you have an
ICUROOT path set up so that you can
find the ICU header files (usually /usr/local )
- 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:
- 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.
- Create the CL program to create the message file and add the various
message descriptions
- 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 |  |  |  |  |
Troubleshooting:
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 on Macintosh using CodeWarrior |  |  |  |  |
| |
|
| |
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.
| |
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. |
|
| |
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 Xerces-C with ICU using bundled Perl scripts |  |  |  |  |
| |
To simplify the builds, we use the bundled perl script
'packageBinaries.pl'. It requires some setup, but once it is done,
repeating it becomes easy. Here's how we do it.
Prerequisites:
- Perl 5.004 or higher
- Cygwin tools or MKS Toolkit
- zip.exe
Steps are:
- Download the appropriate ICU source archive.
- Download Xerces-C source archive.
- Build ICU.
- Build Xerces-C with ICU.
Download Xerces-C from
http://xml.apache.org/xerces-c/dist directory.
Download the appropriate archive for ICU from: http://oss.software.ibm.com/developerworks/opensource/icu/project/download/index.html
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 'packageBinaries.pl '.
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 packageBinaries.pl -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:
|
 |  |  |  | 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.
- 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.
- 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.
- 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.
- 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.
- 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.
|
|