diff --git a/src/BUILDINSTRUCTIONS.TXT b/src/BUILDINSTRUCTIONS.TXT
index 33cdaa3cfc1e33936e06b0f3df5332f834102d9c..4529409391cd4988eaad8e32029d3ef24d730c64 100644
--- a/src/BUILDINSTRUCTIONS.TXT
+++ b/src/BUILDINSTRUCTIONS.TXT
@@ -17,1059 +17,1203 @@ 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 AS/400.
-* Building Xerces-C on Macintosh.
-* Building ICU.
-* How to build the User Documentation?.
-* I wish to port Xerces to my favourite platform. Do you have any suggestions?
+* Building Xerces-C++ on Windows NT/98
+* Building Xerces-C++ on Windows using Visual Age C++
+* Building Xerces-C++ on Windows using Borland C++Builder
+* Building Xerces-C++ on UNIX platforms
+* Building Xerces-C++ as a single-threaded library on Unix platforms
+* Building on iSeries (AS/400)
+* Building Xerces-C++ on OS/2 using Visual Age C++
+* Building Xerces-C++ on Macintosh
+* Building Xerces-C++ with ICU using bundled Perl scripts on Windows
+* Building Xerces-C++ COM Wrapper on Windows
+* Building User Documentation
+* I wish to port Xerces to my favourite platform. Do you have any
+* suggestions?
* What should I define XMLCh to be?
-* How can I generate Xerces-C binaries which includes the sample NetAccessor implementation using Libwww?
* Where can I look for more help?
+Building Xerces-C++ on Windows NT/98
+====================================
-Building on Windows 2000/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++.
- Borland C++Builder Compiler
- ---------------------------
- Xerces-C comes with Borland C++Builder projects to help you build Xerces-C.
- The following describes the steps you need to build Xerces-C. The library
- and demo projects are all contained in the Xerces-all project group:
-
- xerces-c-src1_5_1\Projects\Win32\BCB5\Xerces-all\Xerces-all.bpg
-
- Each project in the group refers a directory belog \Xerces-all. For example
- the XercesLib project files are contained in the directory
-
- xerces-c-src1_5_1\Projects\Win32\BCB5\Xerces-all\XercesLib
-
- To build any project, open the project manager. Double click on the project
- name. Then select "Project|Build" from the menu. For example, double click
- on XercesLib.dll in the manager. Then select "Project|Build XercesLib" from
- the menu.
-
- Once the library has been built, include XercesLib.lib with in application's
- project and place XercesLib.dll somewhere in your path.
+ 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.
- Microsoft Visual C++
- --------------------
- 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.
+ The workspace containing the Xerces-C++ project file and all other samples is:
- Building Xerces-C library
+ xerces-c-src1_6_0\Projects\Win32\VC6\xerces-all\xerces-all.dsw
- 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.
+ Once you are inside MSVC, you need to build the project marked XercesLib.
- The workspace containing the Xerces-C project file and all other samples is:
+ 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\xerces-all.dsw
+ xerces-c-src1_6_0\Projects\Win32\VC6\xerces-all\XercesLib\XercesLib.dsp
- 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.
- 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.
+ 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 Compiler
-Redhat Linux 6.1 egcs
-AIX 4.3.3 and higher xlC
-Solaris 2.6 CC
-HP-UX 10.2 CC
-HP-UX 11 aCC
-
-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
- International Components 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.
+ If you are using the source package, 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.
- To include the ICU library:
+ If you are using the binary package, load the
+ xerces-c1_6_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual
+ C++ workspace inside your MSVC IDE. Then select all the samples and right click
+ on the selection. Then choose "Build (selection only)" to build all the samples in
+ one shot.
- * 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 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 AS/400
-
-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
- rchasgo400@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
-
-
- qsh
- 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):
-
-
- 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:
-
- 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
-
-
-
- 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 Samples on AS/400
-
-
- qsh
- cd <full path to Xerces-C>/samples
- runConfigure -p os400 -x icc -c icc
- gmake -e
+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
+ ---------------------------
- Troubleshooting:
+ Requirements:
- 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.
+ * 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:
-Building on Macintosh using CodeWarrior
+ * 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:/xerces-c1_6_0 d:/icu.
+ Instructions:
-Building Xerces-C library
+ 1.Change the directory to d:\xerces-c1_6_0\Projects\Win32
+ 2.If a d:\xerces-c1_6_0\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.
- 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.
+ These instructions assume that you install in drive d:\. Replace d with the
+ appropriate drive letter.
- There are some things to be aware of when creating your own
- projects using Xerces-C.
+Building Xerces-C++ on Windows using Borland C++Builder
+=======================================================
- 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.
+ Xerces-C++ comes with Borland C++Builder projects to help you build
+ Xerces-C++. The following describes the steps you need to build
+ Xerces-C++.
- [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.
+ Building Xerces-C++ library
+ ---------------------------
+ The library and demo projects are all contained in the Xerces-all project group:
-How to Build ICU
+ * xerces-c-src1_6_0\Projects\Win32\BCB5\Xerces-all\Xerces-all.bpg
-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 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.
+ Each project in the group refers a directory belog \Xerces-all. For example, the
+ XercesLib project files are contained in the directory
+ * xerces-c-src1_6_0\Projects\Win32\BCB5\Xerces-all\XercesLib
-Buiding ICU for Xerces-C
+ To build any project, open the project manager. Double click on the project name.
+ Then select "Project|Build" from the menu. For example, double click on
+ XercesLib.dll in the manager. Then select "Project|Build XercesLib" from the menu.
+ Once the library has been built, include XercesLib.lib with in application's project
+ and place XercesLib.dll somewhere in your path.
- 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.
+Building Xerces-C++ 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.
- [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.
+ 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.
-Building ICU on Windows
+ 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.
- 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.
+ Operating System C++, C Compilers
+ ---------------- ----------------
+ Redhat Linux 6.1 g++, gcc (egcs)
+ AIX 4.3 xlC_r, xlc_r
+ Solaris 2.6 CC, cc
+ HP-UX 11 aCC, cc
- 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.
+ 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.
- In the first case the project file is:
- xml4c2\Projects\Win32\VC6\IXXML4C2\IXXML4C2\IXXML4C2.dsp
+ 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.
- In the second case the workspace is:
- xml4c2\Projects\Win32\VC6\IXXML4C2\IXXML4C2.dsw
+ 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.
- 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.
+ 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.
-Building ICU on UNIX platforms
+ Next set your Xerces-C++ root path as follows:
- To build ICU on all UNIX platforms you at least need the autoconf tool and GNU's
- gmake utility.
+ export XERCESCROOT=<full path to xerces-c-src1_6_0>
- First make sure that you have defined the following environment variables:
+ This should be the full path of the directory where you extracted Xerces-C++.
+ Building Xerces-C++ library
+ ---------------------------
- export ICUROOT = <icu_installdir>
- export ICU_DATA = <icu_installdir>/data/
+ 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: 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', 'unixware', 'os400', 'irix', 'ptx', 'tru64', 'macosx' )
+ -c <C compiler name> (e.g. gcc, cc, xlc_r, icc)
+ -x <C++ compiler name> (e.g. g++, CC, xlC_r, icc, c++)
+ -d (specifies that you want to build debug version)
+ -m <message loader> can be 'inmem', 'icu', 'MsgFile' or 'iconv'
+ -n <net accessor> can be 'fileonly', 'libwww', 'socket' or 'native'
+ -t <transcoder> can be 'icu', 'Iconv400', 'Iconv390' or 'native'
+ -r <thread option> can be 'pthread' or 'dce' (only used on aix, HP-11 and solaris) or 'sproc' (only on IRIX) or 'none'
+ -l <extra linker options>
+ -z <extra compiler options>
+ -P <install-prefix>
+ -C <any one extra configure 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 -nsocket -tnative -rpthread
+
+ 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: socket
+ Transcoder: native
+ Thread option: pthread
+ Extra configure options:
+ 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 -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) works... yes
+ checking whether the C compiler (gcc -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) 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 -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) works... yes
+ checking whether the C++ compiler (g++ -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) 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 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/Transcoders/MacOSUnicodeConverter/Makefile
+ creating util/Platforms/Makefile
+ creating util/Platforms/Solaris/Makefile
+ creating util/Platforms/AIX/Makefile
+ creating util/Platforms/Linux/Makefile
+ creating util/Platforms/HPUX/Makefile
+ creating util/Platforms/OS390/Makefile
+ creating util/Platforms/OS400/Makefile
+ creating util/Platforms/IRIX/Makefile
+ creating util/Platforms/PTX/Makefile
+ creating util/Platforms/UnixWare/Makefile
+ creating util/Platforms/Tru64/Makefile
+ creating util/Platforms/MacOS/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 util/NetAccessors/Socket/Makefile
+ creating util/NetAccessors/libWWW/Makefile
+ creating util/NetAccessors/MacOSURLAccess/Makefile
+ creating util/regx/Makefile
+ creating validators/Makefile
+ creating validators/common/Makefile
+ creating validators/datatype/Makefile
+ creating validators/DTD/Makefile
+ creating validators/schema/Makefile
+ creating framework/Makefile
+ creating dom/Makefile
+ creating idom/Makefile
+ creating parsers/Makefile
+ creating internal/Makefile
+ creating sax/Makefile
+ creating sax2/Makefile
+ creating ../obj/Makefile
+
+ 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.
+ Go to http://marc.theaimsgroup.com/?l=xerces-c-dev
+
+ In future, you may also directly type the following commands to create the Makefiles.
+
+ export TRANSCODER="NATIVE"
+ export MESSAGELOADER="INMEM"
+ export NETACCESSOR="Socket"
+ export THREADS="pthread"
+ export CC="gcc"
+ export CXX="g++"
+ export CXXFLAGS=" -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET"
+ export CFLAGS=" -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET"
+ export LDFLAGS=""
+ export LIBS=" -lpthread "
+ configure
+
+ If the result of the above commands look OK to you, go to the directory
+ $HOME/xerces-c-src1_6_0/src 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.
+
+ gmake
+
+ Is that it? Yes, that's all you need to build Xerces-C++.
+ Building samples
+ ----------------
+ The installation process for the samples is same on all UNIX platforms.
- Next, go to the directory, the following commands will create a shell script called
- 'configure':
+ cd xerces-c1_6_0-linux/samples
+ ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
+ gmake
+ This will create the object files in each sample directory and the executables in '
+ xerces-c1_6_0-linux/bin' directory.
- cd $ICUROOT
- cd source
- autoconf
+ Note that runConfigure is just a helper script and you are free to use ./configure
+ with the correct parameters to make it work on any platform-compiler combination
+ of your choice. The script needs the following parameters:
+ Usage: runConfigure "options"
+ where options may be any of the following:
+ -p <platform> (accepts 'aix', 'unixware', 'linux', 'solaris',
+ 'hp-10', 'hp-11', 'os400', 'irix', 'ptx', 'tru64', 'macosx')
+ -c <C compiler name> (e.g. gcc, xlc or icc)
+ -x <C++ compiler name> (e.g. g++, xlC, or icc)
+ -d (specifies that you want to build debug version)
+ -h (get help on the above commands)
+ -z <extra compiler options>
+ NOTE:The code samples in this section assume that you are are working on
+ the Linux binary drop. If you are using some other UNIX flavor, please replace
+ '-linux' with the appropriate platform name in the code samples.
- Commands for specific UNIX platforms are different and are described separately
- below.
+ To delete all the generated object files and executables, type:
- 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.
+ gmake clean
- For AIX:
+Building Xerces-C++ as a single-threaded library on Unix platforms
+==================================================================
- Type the following:
+ To build a single-threaded library on Unix platforms you have to update
+ one or more of the following files Makefile.incl, Makefile.in,
+ runConfigure. The following steps guide you to create a
+ single-threaded library for each platform:
+ For Aix -
- 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
+ * 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 Solaris and Linux:
+ 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
- env CC="cc" CXX="CC" C_FLAGS="-w -O" CXX_FLAGS="-w -O"
- ./configure --prefix=$ICUROOT
+ 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
+Building on iSeries (AS/400)
+============================
- For HP-UX with the aCC compiler:
+ The following addresses the requirements and build of Xerces-C++ natively on the iSeries.
+ Building Xerces-C++ library
+ ---------------------------
- env CC="cc" CXX="aCC" C_FLAGS="+DAportable -w -O"
- CXX_FLAGS="+DAportable -w -O" ./configure --prefix=$ICUROOT
+ Requirements:
+ * OS/400 QSHELL interpreter installed (install base option 30, operating system)
+ * OS/400 - Portable App Solutions Environment (PASE) installed (install base option 33, operating system)
+ * QShell Utilities, PRPQ 5799-XEH
+ * iSeries Tools for Developers, PRPQ 5799-PTL (these are the gnu utilities)
+ Compiler:
- For HP-UX with the CC compiler:
+ * For v4r5m0: ILE C++ for AS/400, PRPQ 5799-GDW
+ * For v5: WebSphere Development ToolsSet, 5722-WDS ( installed option 52, Compiler - ILE C++)
+ Recommendations:
- env CC="cc" CXX="CC" C_FLAGS="+DAportable -w -O"
- CXX_FLAGS="+eh +DAportable -w -O" ./configure --prefix=$ICUROOT
+ * There is one option when building the XML4C parser on iSeries. For code page translation, you can use the
+ iSeries native Iconv400 support or ICU as the transcoder plugin. If you choose ICU, follow the instructions to
+ build the ICU service program with the ICU download. Those instructions are not included here.
+ * We recommend the use of Iconv400. The binary posted on Alphaworks uses Iconv400.
+ Setup Instructions:
+ * Make sure that you have the requirements installed on your iSeries. We highly recommend that you read the
+ writeup that accompanies the iSeries Tools for Developers PRPQ. 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 iSeries *module, *pgm and
+ *srvpgm objects in libraries.
+ * Download the source zip file (NT version) directly to an iSeries IFS directory after creating a directory (eg.
+ /XML4Cxxx) and then extract the source using a mapped drive. To do this, from Windows Explorer, select Tools
+ -> Map Network Drive. Then select an available drive (e.g. F:) and specify an iSeries system you want to extract
+ the zip file to (e.g. \\<your iSeries name>\root). Click on Finish. Then find the .zip file and right click on it and
+ select Extract To ... Then select the files you want to extract to the iSeries system.
+ * Create iSeries 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 up to the Xerces-C++ src directory, but not including 'src'>
+ MAKE - '/usr/bin/gmake'
+ OUTPUTDIR - <identifies target iSeries library for *module, *pgm and *srvpgm objects>
+ ICUROOT - (optional if using ICU) <the path of your ICU includes>
-How to build the User Documentation?
+ * For v4r5m0 systems, add QCXXN, to your build process library list. This results in the resolution of
+ CRTCPPMOD used by the icc compiler.
+
+ 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 iSeries build do the following under Qsh:
+
+ qsh:
+ cd <full path to Xerces-C++>/src
+ runConfigure -p os400 -x icc -c icc -m inmem -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 a few 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 or PASE is not installed. The second reason happens because the test modules already exist from a
+ previous run of runConfigure. To correct the problem, do the following:
+
+ CL:
+ DLTMOD <OUTPUTDIR library>/CONFT* and
+ DLTPGM <OUTPUTDIR library>/CONFT*
+
+ Build
+
+ qsh:
+ cd <full path to Xerces-C++>/src
+ gmake
+
+ The above gmake should 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>. It is highly possible that the service program will not create
+ however due to number of modules and path names, see trouble shooting for the workaround.
+
+ After the service program has successfully been created and a link established, 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 iSeries is a binding directory. To create an archive file, use qar
+ command. (see the iSeries Tools for Developers 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. Also, note that the .a file below can have a different name based on the
+ parser version (using apache xerces versioning)):
+
+ qsh:
+ cd <full path to Xerces-C++>/lib
+ qar -cuv libxerces-c1_6_0.a *.o
+ will results in
+ command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/Xerces-C++/lib/libxerces-c1_6_0.a')
+ command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )
+
+ Troubleshooting gmake problem:
+
+ Due to the number of modules (the .o symbolic links) that make up the service program and the path to get to those
+ modules, the qshell ld request to create the service program will likely fail because the request is too large, you may
+ get a message like the following at the end of the gmake request:
+
+ FAILURE: spawnp() with errno = 3491
+ GMAKE: vfork: Argument list too long.
+
+ If this is the case, you can manually create the service progam by doing the following:
+
+ CL:
+ CRTSRVPGM (<OUTPUTDIR-library>/libxercesc) MODULE(<OUTPUTDIR-library>/*ALL) EXPORT(*ALL) TEXT('XML4C parser version xxx')
+ OPTION(*DUPPROC *DUPVAR)
+
+ Note that if you manually create the service program you want to make sure that you do not include any CONFT*
+ modules or samples modules in the OUTPUTDIR library. After the service program is manually created you can add a
+ symbolic link to the service program into the appropriate /lib directory by qsh:
+
+ qsh:
+ cd <full path to Xerces-C++>/lib
+ ln -s /qsys.lib/<outputdir>.lib/libxercesc.srvpgm libxerces-c1_6_0.o
+ qar -cuv libxerces-c1_6_0.a *.o
+
+ If you are on a v4 system using the ILE C++ PRPQ compiler (which is referred to as the 'old' compiler) you will get
+ compiler errors requiring a few manual changes to the source:
+
+ * src/dom/DocumentImpl.cpp
+ * src/dom/DocumentImpl.hpp
+ * src/idom/IDDocumentImpl.cpp
+ * src/idom/IDDocumentImpl.hpp
+ * src/validators/common/ContentSpecNode.hpp
+
+ Update the following routines in src/dom/DocumentImpl.cpp as follows:
+
+ void DocumentImpl::setUserData(NodeImpl* n, void* data)
+ {
+ if (!userData && data)
+ #ifdef __OS400__
+ userData = new RefHashTableOf<char>(29, false, new HashPtr());
+ #else
+ userData = new RefHashTableOf<void>(29, false, new HashPtr());
+ #endif
+ if (!data && userData)
+ userData->removeKey((void*)n);
+ else
+ #ifdef __OS400__
+ userData->put((void*)n,(char*)data);
+ #else
+ userData->put((void*)n,data);
+ #endif
+ }
+
+ void* DocumentImpl::getUserData(NodeImpl* n)
+ {
+ if (userData)
+ #ifdef __OS400__
+ return (void*)userData->get((void*)n);
+ #else
+ return userData->get((void*)n);
+ #endif
+ else
+ return null;
+ }
+
+ To update src/dom/DoumentImpl.hpp as follows:
+
+ #ifdef __OS400__
+ RefHashTableOf<char> *userData;
+ #else
+
+ RefHashTableOf<void> *userData;
+ #endif
+
+ Update the following routines in src/idom/IDDocumentImpl.cpp as follows:
+
+ void IDDocumentImpl::setUserData(IDOM_Node* n, void* data)
+ {
+ if (!fUserData && data)
+ #ifdef __OS400__
+ fUserData = new (this) RefHashTableOf<char>(29, false, new (this) HashPtr());
+ #else
+ fUserData = new (this) RefHashTableOf<void>(29, false, new (this) HashPtr());
+ #endif
+
+ if (!data && fUserData)
+ fUserData->removeKey((void*)n);
+ else
+ #ifdef __OS400__
+ fUserData->put((void*)n,(char*)data);
+ #else
+ fUserData->put((void*)n,data);
+ #endif
+ }
+
+ void* IDDocumentImpl::getUserData(const IDOM_Node* n) const
+ {
+ if (fUserData)
+ #ifdef __OS400__
+ return (void*) fUserData->get((void*)n);
+ #else
+ return fUserData->get((void*)n);
+ #endif
+
+ else
+ return 0;
+ }
+
+ To update src/idom/IDDocumentImpl.hpp:
+
+ #ifdef __OS400__
+ RefHashTableOf<char> *fUserData;
+ #else
+ RefHashTableOf<void> *fUserData;
+ #endif
+
+ Update validators/common/ContentSpecNode.hpp removing the following:
+
+ #ifndef __OS400__
+ inline
+ #endif
+ ContentSpecNode::~ContentSpecNode()
+
+ 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).
+
+ Building Samples on iSeries
+ ---------------------------
-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.
+ Note that the samples will create programs bind to the BND directory object
+ created by qar referenced above.
-Pre-requisites for building the user documentation are:
+ qsh
+ cd <full path to Xerces-C++>/samples
+ runConfigure -p os400 -x icc -c icc
+ gmake
- * JDK 1.2.2 (or later).
- * Xerces-J (1.0.0 or later).
- * Xalan (0.19.3 or later)
- * Stylebook 1.0-b2
+Building Xerces-C++ on OS/2 using Visual Age C++
+================================================
-Setup PATH to include the JDK 1.2.2 bin directory. Also setup CLASSPATH
-environment variable as follows:
+ 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.
- * Under Windows (assumes all jars are in '\jars' directory:)
- CLASSPATH=\jars\stylebook-1.0-b2.jar;\jars\xalan.jar;\jars\xerces.jar
- * Under Unix's (assumes all jars are in '~/jars' directory):
- export
- CLASSPATH="~/jars/stylebook-1.0-b2.jar:~/jars/xalan.jar:~/jars/xerces.jar"
+ Building Xerces-C++ library
+ ---------------------------
-Next, cd to the Xerces-C source drop root directory, and enter
+ Requirements:
+
+ * 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_6_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_6_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_6_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_6_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_6_0\Projects\OS2\VACPP40 directory. Run
+ packageBinaries, giving the source and target directories like this:
+
+ packageBinaries -s x:\xerces-c-src1_6_0 -o x:\temp\xerces-c1_6_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_6_0.)
+
+ Building Samples
+ ----------------
+
+ Building the Xerces-C++ samples using IBM Visual Age C++ Professional 4.0 for
+ OS/2 (VAC++).
+
+ * In the XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40
+ directory, find and edit the VAC++ configuration file basedir.icc.
+ * All of the directories used to build the samples are defined in
+ basedir.icc. You need to edit the directories to match your system.
+ Here are the directories you need to assign: SRC_DIR --
+ XercesCSrcInstallDir; This is where VAC++ should look to find the
+ samples directories containing the source files. BASE_DIR -- The install
+ directory XercesCSrcInstallDir;. VAC++ will store the compiled
+ samples in the bin directory under BASE_DIR. It will also look for the
+ xerces-c.lib file in the lib directory under BASE_DIR. Other
+ directories are set based on these two. You can choose to override them if
+ you wish.
+ * Save basedir.icc
+ * Start the Command Line in the VAC++ folder.
+ * Navigate to the
+ XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40
+ directory.
+ * Run bldsamples.cmd
+ * 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 several executable files.
+
+ Rebuilding the Configuration Files
+
+ Although it shouldn't be necessary, if you want to rebuild the VAC++ configuration
+ files, you'll need to have Object Rexx running on your system:
+
+ * 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. (Note: 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 Projects\OS2\VACPP40 directory, run genICC.cmd. This builds the
+ VAC++ configuration files for the samples you have on your system.
+ * Go to the first step above in the "Building asmples for OS/2" section.
+
+Building Xerces-C++ on Macintosh
+================================
+
+ The Xerces-C++ Mac port has the key following attributes:
+
+ 1.Built atop CoreServices APIs and a limited number of Carbon
+ APIs; supports builds for both Mac OS Classic, Carbon, and Mac
+ OS X systems.
+ 2.Has a Mac OS native transcoder that utilizes the built-in Mac OS
+ Unicode converter [MacOSUnicodeConverter].
+ 3.Has a Mac OS native netaccessor that utilizes the built-in Mac OS
+ URLAccess routines [MacOSURLAccess].
+ 4.Supports builds from Metroworks CodeWarrior, Apple Project
+ Builder, and Mac OS X shell.
+
+
+ Using Xerces-C++ with CodeWarrior
+ ---------------------------------
+ Xerces-C++ and CodeWarrior:
+
+ Xerces-C++ may be built with CodeWarrior under Mac OS Classic or Mac OS X.
+ Since the Xerces-C++ code contains some files with very long names, and
+ CodeWarrior does not yet support use of files with such long names, the installation
+ in this case is somewhat involved.
+
+ Installing Xerces-C++ for use with CodeWarrior:
+
+ For compatibility with CodeWarrior, it is necessary to adjust some of the file names
+ (and referencing include statements). To do this, it is necessary to perform the
+ following steps on a unix (or Mac OS X) machine that has support for long file names
+ (a Windows machine may also work):
+
+ * Retrieve Xerces-C++ from CVS, or untar a packaged build. Note that these
+ steps should not be performed in a Classic Mac OS environment, as file
+ names would then be mangled at this point!
+ * Xerces-C++ comes with a tool that will shorten file names as appropriate, and
+ fix up referencing include statements. Duplicate the file
+ Projects/MacOS/ShortenFiles.pl to the xercesc main directory (the same
+ directory that contains the Projects directory). Executing this perl script from
+ this location will create a new directory MacSrc that contains patched up
+ versions of files from the src directory.
+
+ cd <xercescroot>
+ cp Projects/MacOS/ShortenFiles.pl .
+ perl ShortenFiles.pl
+
+ * The source files will likely not now have proper Mac OS type/creator
+ attribution. CodeWarrior badly wants this to be correct. So set the
+ type/creator of these files somehow. The following should work from Mac OS X
+ (but if you're not going to keep building on a Mac OS X machine, you may well
+ need to perform this step in some other way once you get the files onto your
+ classic machine).
+
+ find . \( -name "*.c" -or -name "*.h" -or -name "*.cpp" -or -name "*.hpp" -or \
+ -name "*.xml" \) -print0 | xargs -0 /Developer/Tools/SetFile -c CWIE -t TEXT
+
+ * Move the entire directory structure to your Mac OS machine.
+
+ Building Xerces-C++ with CodeWarrior:
+
+ * Run CodeWarrior (tested with latest CW Pro 7.0).
+ * Import the project
+ Projects/MacOS/CodeWarrior/XercesLib/XercesLib.mcp.xml, saving it back
+ out to the same directory as XercesLib.mcp.
+ * This project contains five build targets that build all combinations of classic,
+ carbon, debug, and release versions, with an all target that builds all of these.
+ Build any or all of these.
+
+ Building Xerces-C++ Samples with CodeWarrior:
+
+ A CodeWarrior project is included that builds the DOMPrint sample. This may be
+ used as an example from which to build additional sample projects. Please read the
+ following important notes:
+
+ * Once again, it is required that you import the .xml version of the project file,
+ and save it back out.
+ * The Xerces-C++ sample programs are written to assume a command line
+ interface. To avoid making Macintosh-specific changes to these command line
+ programs, we have opted to instead require that you make a small extension
+ to your CodeWarrior runtime that supports such command line programs.
+ Please read and follow the usage notes in
+ XercesSampleSupport/XercesSampleStartupFragment.c.
+
+ Building Xerces-C++ with Project Builder
+ ----------------------------------------
+
+ Projects are included to build the Xerces-C++ library and DOMPrint sample under
+ Apple's Project Builder for Mac OS X. The following notes apply:
+
+ * Since you are running under Mac OS X, and if you are not also performing
+ CodeWarrior builds, it is not necessary to shorten file names or set the
+ type/creator codes as required for CodeWarrior.
+ * The Project Builder project builds XercesLib as the framework
+ Xerces.framework. This framework, however, does not currently include a
+ correct set of public headers. Any referencing code must have an include
+ path directive that points into the Xerces-C++ src directory.
+ * The DOMPrint project illustrates one such usage of the Xerces.framework.
+
+ Building Xerces-C++ from the Mac OS X command line
+ --------------------------------------------------
+
+ Support for Mac OS X command line builds is now included in the standard "unix"
+ Xerces-C++ build infrastructure.
+
+ In general, the Mac OS X command line build follows the generic unix build
+ instructions. You need to set your XERCESCROOT environment variable,
+ ./runConfigure, and make.
+
+ setenv XERCESCROOT "<directory>"
+ cd src
+ ./runConfigure -p macosx -n native
+ make
+
+ Similar instructions apply to build the samples and tests, though the -n flag
+ is not used in these cases:
+
+ cd samples
+ ./runConfigure -p macosx
+ make
+
+ Special usage information for Xerces-C++ on the Macintosh
+ ---------------------------------------------------------
+
+ File Path Specification
+
+ Apart from the build instructions, above, the most important note about use of
+ Xerces-C++ on the Macintosh is that Xerces-C++ expects all filename paths to be
+ specified in unix syntax. If running natively under a Mac OS X system, this path
+ will be the standard posix path as expected by the shell. The easiest means of
+ creating and interpreting these paths will be through the routines
+ XMLCreateFullPathFromFSRef and XMLParsePathToFSRef as declared in
+ the file MacOSPlatformUtils.hpp. FSSpec variants of these routines are also
+ supplied.
+
+ Mac OS Version Compatibility
+
+ Xerces-C++ requires that several key components of the Mac OS be relatively up
+ to date. It should be readily compatible with any system above Mac OS 9.0.
+ Compatibility with earlier systems may perhaps be achieved if you can install
+ appropriate components.
+
+ Required components are:
+
+ * Unicode Converter and Text Encoding Converter. These provide the base
+ transcoding service used to support Xerces-C++ transcoding requirements.
+
+ Optional components are:
+
+ * URLAccess. Provides NetAccessor support to Xerces-C++ for use in
+ fetching network referenced entities. If URLAccess is not installed, any
+ such references will fail; the absence of URLAccess, however, will not in
+ itself prevent Xerces-C++ from running.
+ * Multiprocessing library. Provides mutual exclusion support. Once again,
+ the routines will back down gracefully if Multiprocessing support is not
+ available.
+ * HFS+ APIs. If HFS+ APIs are available, all file access is performed using
+ the HFS+ fork APIs to support long file access, and to support long
+ unicode compliant file names. In the absence of HFS+ APIs, classic HFS
+ APIs are used instead.
+
+Building Xerces-C++ with ICU using bundled Perl scripts on Windows
+==================================================================
+
+ 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.
+
+ 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.
+
+
+ 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'.
+
+ Prerequisites:
+
+ * Perl 5.004 or higher
+ * Cygwin tools or MKS Toolkit
+ * zip.exe
+
+ 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_6_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.
+
+ 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.
+ Then at the prompt enter:
- * Under Windows:
- createDocs
- * Under Unix's:
- sh createDocs.bat
+ set XERCESCROOT=x:\xerces-c-src1_6_0
+ set ICUROOT=x:\icu
+ cd x:\xerces-c-src1_6_0\scripts
+ perl packageBinaries.pl -s x:\xerces-c-src1_6_0 -o x:\temp\xerces-c1_6_0-win32 -t icu
-This should generate the .html files in the 'doc/html' directory.
+ (Match the source directory to your system; the target directory can be
+ anything you want.)
-Ok here is where you can get the three jar files that are referred to above.
+ 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.
- * JDK 1.2.2 is available from http://java.sun.com/products/jdk/1.2/
- * Xerces-J is available from http://xml.apache.org/dist/. Extract the
- xerces.jar file from the binary drop and store it in the 'jars' directory
- as mentioned above.
- * Xalan is also available from http://xml.apache.org/dist/. Extract the
- xalan.jar file from the 'jar' distribution that you just downloaded and
- store it in the same 'jars' directory as mentioned above.
- * Getting to Stylebook is little more involved. You will have to download
- one of the 'xml-stylebook' tar balls from
- http://xml.apache.org/from-cvs/xml-stylebook/ and then extract the file:
- xml-stylebook/bin/stylebook-1.0-b2.jar
+ For a description of options available, you can enter:
- Under Unix's you may enter:
- gzip -d -c xml-stylebook_20000207231311.tar.gz | tar xf -
- xml-stylebook/bin/stylebook-1.0-b2.jar
- to extract this file. Copy it to the 'jars' directory as mentioned above.
-
- Under Windows you may use 'WinZip' to extract the jar file from the tar
- ball.
-
-
- 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?
-
-The answer is 'it depends'. We will mention some of the
-quirks that affect this decision. Hopefully, after reading
-whats below, you will be able to best decide what the right
-definition should be. We could not however, resist making a
-suggestion. Some observations first:
-
- * Xerces-C uses XMLCh as the fundamental type to hold one
- Unicode character as, all processing inside Xerces-C
- happens in Unicode.
- * Most modern C++ compilers today provide 'wchar_t' as a
- fundamental type representing a 'wide character'. Most
- of them define it in using a typedef. This typedef
- definition is not consistent on all the platforms that
- we have come across.
- * The size of wchar_t varies among the various compilers.
- Its either 16-bit or 32-bit. Fortunately, this only
- affects how much memory you need, to process the XML
- data, while everything is still in memory.
- * Again on most platforms wchar_t represents a unicode
- character. HPUX, is one exception to this, that we
- know, where wchar_t does not represent a unicode
- character, rather its a native wide character.
- * Lastly, most OS's/compilers provide a system library to
- manipulate wide character strings taking wchar_t and
- wchar_t* arguments. Most applications which support
- wide-characters make these system calls.
-Our suggestion is:
-
-If your compiler defines wchar_t to represent a unicode
-character, then define XMLCh to be wchar_t. Such a
-definition will allow you to pass the data returned by the
-parser (all api's return XMLCh, which is wchar_t) directly
-to the wide-character system api's for i/o or manipulation.
-This is most efficient and convenient.
-
-However, if your compiler defines wchar_t to be just a
-wide-character which is not Unicode, then define XMLCh to be
-unsigned short. For the Xerces-C parser, XMLCh is always
-Unicode. By defining it to be unsigned short and not
-wchar_t, the compiler will not let you accidently pass what
-is returned, via the parser API's, directly to the
-wide-character library calls. To use the wide-character
-library of functions, you will have to in your application,
-call some transcoding function which will convert it from
-Unicode to the native wide-character form. Again, if your
-application desires for whatever reason, you may define
-XMLCh to be 'unsigned long'. By doing so, you have just
-doubled the memory required to process the XML file.
-
-Hopefully, you will agree that the answer 'it depends' was
-the right one.
-
-
- How can I generate Xerces-C binaries
-which includes the sample NetAccessor
- implementation using Libwww?
-
-This sample implementation has only been minimally tested
-only under Windows NT using Libwww 5.2.8. We have not stress
-tested our implementation can cannot guarantee that there
-are no memory leaks. The error reporting is also not
-adequate. Further, it only handles HTTP style URL's. As you
-can see, this implementation is only for illustrative
-purposes. Much more work is required to have a robust
-cross-platform implementation. We would welcome any
-volunteers who would contribute code to make this happen on
-various platforms.
-
-The software that you need are:
-
- * You need the Xerces-C source archive for Windows.
- * LibWWW 5.2.8. Win32 binaries are available at:
- http://www.idm.ru/libwww.htm. Source archives and other
- details on LibWWW are available at
- http://www.w3.org/Library/.
-
-All required changes in Xerces-C are restricted to the
-Project file settings for the XercesLib. To simplify, we
-will make certain assumptions about how LibWWW binaries
-(.lib) and header files are installed on your machine.
-
- 1. First generate all the LibWWW binaries by using the
- project file supplied. Create a top level (say) \libWWW
- directory on the same disk drive where you installed
- the Xerces-C sources. Copy all the .lib files to
- \libWWW\lib directory. Next, copy all the .dll files to
- \libWWW\bin directory and all the header (*.h) files to
- \libWWW\include directory.
- 2. Next make the following changes to the Xerces-C lib
- project settings. Invoke the project settings dialog
- box.
- 1. In the 'C/C++ : Preprocessor : Preprocessor
- definitions' add XML_USE_NETACCESSOR_LIBWWW
- 2. In the 'C/C++ : Preprocessor : Additional include
- directories' add \libWWW\include.
- 3. Next, rather than listing all the 20 some LibWWW .lib
- files in the link settings, add them as external files
- to the XercesLib project. Right-Click on 'XercesLib
- files' and choose the 'Add Files to Project' menu item.
- Next choose all the *.lib files in \libWWW\lib
- directory and press 'ok'.
- 4. Next, create a new sub-folder in XercesLib:util folder,
- by right-clicking on 'util' and choosing 'New Folder'.
- Call it 'libWWW'.
- 5. Add netaccessor files into this 'libWWW' folder again,
- by right-clicking on 'libWWW' folder and choosing 'Add
- Files to Folder'. Choose the four files in
- <XercesCRoot>\src\util\NetAccessors directory. These
- files are: BinURLInputStream.[ch]pp and
- LibWWWNetAccessor.[ch]pp.
- 6. Rebuild the Xerces-C library.
-
-Make sure you have \libWWW\bin in your PATH environment
-variable, before you run the samples and refer to a XML file
-containing HTTP URL's to remote resources.
-
-
-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 Xerces mailing list archives.
-
-If all else fails, you may ask for help by subscribing to
-the Xerces-C mailing list.
-
-
-Copyright © 2000 The Apache Software Foundation. All Rights Reserved.
+ perl packageBinaries.pl
+
+Building Xerces-C++ COM Wrapper 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
+ http://www.microsoft.com/msdownload/platformsdk/setuplauncher.htm or directly
+ FTP it from
+ ftp://ftp.microsoft.com/developr/PlatformSDK/April2000/Msi/WinNT/x86/InstMsi.exe.
+
+ 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
+ http://xw2k.sdct.itl.nist.gov/BRADY/DOM/. You will have to modify the documents
+ in the NIST suite to load the Xerces COM object instead of the MSIE COM object.
+
+Building 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:
+ createDocs
+ * 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 XercesDefs.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 XercesDefs.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.
+
+ Other concerns are:
+
+ * Does ICU compile on your platform? If not, then you'll need to
+ create a transcoder implementation that uses your local
+ transcoding services. The Iconv transcoder should work for you,
+ though perhaps with some modifications.
+
+ * What message loader will you use? To get started, you can use
+ the "in memory" one, which is very simple and easy. Then, once
+ you get going, you may want to adapt the message catalog
+ message loader, or write one of your own that uses local
+ services.
+
+ That is the work required in a nutshell!
+
+What should I define XMLCh to be?
+=================================
+
+ 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.
+
+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 http://archive.covalent.net and the Bugzilla
+ Apache bug database.
+
+s
\ No newline at end of file