You are viewing a plain text version of this content. The canonical link for it is here.

Posted to commits@xerces.apache.org by ab...@locus.apache.org on 2000/02/02 01:01:00 UTC

cvs commit: xml-xerces/c/src BUILDINSTRUCTIONS.TXT

abagchi 00/02/01 16:01:00

Added: c/src BUILDINSTRUCTIONS.TXT
Log:
Initial checkin of build instructions

Revision Changes Path
1.1 xml-xerces/c/src/BUILDINSTRUCTIONS.TXT

Index: BUILDINSTRUCTIONS.TXT
===================================================================
BUILDINSTRUCTIONS.TXT
=====================

****************************************************************************

WARNING: This is not the best place to look for build instructions. You
should go to http://xml.apache.org/xerces-c/build.html to see the
latest stuff. The web-page is maintained more regularly than this text
file.

However, if you insist, here is a text dump of the same web-page from
ancient times.

End of warning!

****************************************************************************

This page has sections on the following topics:

* Building Xerces-C on Windows
* Building Xerces-C on UNIX
* Building Xerces-C on Windows using Visual Age
* Building Xerces-C on OS/2 using Visual Age
* Building Xerces-C on Macintosh
* Building ICU
* Building the User Documentation

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:

xerces-c-src-1_1_0\Projects\Win32\VC6\xerces-all\xerces-all.dsw

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:

xerces-c-src-1_1_0\Projects\Win32\VC6\xerces-all\XercesLib\XercesLib.dsp

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.

[Note] If you are working on the AlphaWorks version which uses ICU, you must either
have the environment variable ICU_DATA set, or keep the international converter
files relative to the Xerces DLL (as it came with the original binary drop) for
the program to find it. For finding out where you can get ICU from and build it,
look at the last section of this page.

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 Compiler
Redhat Linux 6.0 egcs-2.91.66 & glibc-2.1.1-6
AIX 4.1.4 and higher xlC 3.1
Solaris 2.6 CC version 4.2
HP-UX B10.2 aCC and CC
HP-UX B11 aCC and 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.

[Note] If you wish to build Xerces-C with ICU, look at the last section of this page. It
tells you where you can find ICU and how you can build Xerces-C to include the ICU
internationalization library.

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-src-1_1_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:

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. gcc, cc, xlc)
-x <C++ compiler name> (e.g. g++, CC, xlC)
-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)

[Note] Xerces-C builds as a standalone library and also as a library dependent on IBM's
International Classes for Unicode (ICU). For simplicity, the following discussion
only targets 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:

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/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
conf.h is unchanged

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/src and type "gmake" to make the XERCES-C system.

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.

gmake

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

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.

export LD_LIBRARY_PATH=$XERCESCROOT/lib:$LD_LIBRARY_PATH

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

Requirements:

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

Instructions:

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.

[Note] 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

Requirements:

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

Instructions

1. Change directory to d:\xml4c\Projects\OS2
2. If a d:\xml4c\Project\OS2\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.

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

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.

[Note] 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 xerces-dev@xml.apache.org
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 for 100's of encodings.
ICU stands for International Classes 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.

[Note] 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 common. You may also want to build tools/makeconv
to make the converter tool. All others are not required for
the Xerces-C build to proceed.

To build Xerces-C from it source, you will need to include
a project file in your workspace to program your
application. Otherwise, you can use the provided workspace
and add your application to it as a separate project.

In the first case the project file is:
xml4c2\Projects\Win32\VC6\IXXML4C2\IXXML4C2\IXXML4C2.dsp

In the second case the workspace is:
xml4c2\Projects\Win32\VC6\IXXML4C2\IXXML4C2.dsw

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. Note that you
must either have the environment variable ICU_DATA set, or
keep the international converter files relative to the
Xerces DLL (as it came with the original binary drop) for
the program to find it.

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>
export ICU_DATA = <icu_installdir>/data/

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

cd $ICUROOT
cd source
autoconf

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 Makefile.in 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
cd common
gmake
gmake install
cd ../tools/makeconv
gmake

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

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. The
application makes use of Xerces-J and Xalan to create the HTML from the XML
source files. The XML source files are part of the Xerces-C module. These files
reside in the doc directory.

Pre-requisites for building the user

documentation

Since the user docs make use of Java, you must first have
JDK1.2.2 (or higher) installed on your machine.

Next you must have Xerces-J (EA2 or better) installed on
your machine.

Finally you must install the StyleBook application. This is
part of the Xerces Project and the module name is
xml-stylebook. Details about installing Stylebook are quite
involved and usually takes some effort to install
perfectly. Hopefully it will be simplified in future, but
it a working application now. To make our scripts work
directly with StyleBook, you must install it at the same
level as xml-xerces. That is, 'xml-xerces' and
'xml-stylebook' must both be at the same level in your
directory.

Creating the user documentation

If you have installed StyleBook properly, the remaining part is very simple.
In the xerces-c directory there is a batch script called createdocs.bat. This
is a one line script containing the following command:

java org.apache.stylebook.StyleBook "targetDirectory=doc/html"
doc/xerces-c_book.xml ../../xml-stylebook/styles/apachexml

All you need to do is run this command. The generated HTML files would reside
in the doc/html directory.

Where to 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 Xerces mailing list archives.

If all else fails, you ask for help by joining the Xerces-C
mailing list.