<?xml version="1.0" standalone="no"?>
<!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd">
<faqs title="Building on Other Platforms">
<faq title="Building &XercesCName; on OS/2 using Visual Age C++">
<q>Building &XercesCName; on OS/2 using Visual Age C++</q>
<a>
<p>OS/2 is a favourite IBM PC platforms. The only
option in this platform is to use
<jump href="http://www-4.ibm.com/software/ad/vacpp/">Visual Age C++ compiler</jump>.
Here are the steps you need to build &XercesCName; using
Visual Age C++ on OS/2.</p>
<s3 title="Building &XercesCName; library">
<p><em>Requirements:</em></p>
<ul>
<li>VisualAge C++ Version 4.0 with Fixpak 1:
<br/>Download the
<jump href="http://www-4.ibm.com/software/ad/vacpp/service/csd.html">Fixpak</jump>
from the IBM VisualAge C++ Corrective Services web page.</li>
</ul>
<p>There are two ways to build &XercesCName;. The "From Existing" method only
requires VAC++. The "From Scratch" method requires both Object Rexx and VAC++
installed.</p>
<p><em>The "From Existing" Method</em></p>
<ol>
<li>In the <code>&XercesCSrcInstallDir;\Projects\OS2\VACPP40</code> directory,
find and edit the VAC++ configuration file <code>project_options.icc</code>.</li>
<li>Change the directory on the first line <code>'BASE_DIR = "..."'</code>
to match the base directory of the &XercesCName; sources on your system.
Note that the directory path must use double backslashes <code>"\\"</code>!</li>
<li>Save <code>project_options.icc</code></li>
<li>Start the Command Line in the VAC++ folder.</li>
<li>Navigate to the <code>&XercesCSrcInstallDir;\Projects\OS2\VACPP40</code> directory.</li>
<li>Run <code>build.cmd</code>. This does a migration build.</li>
<li>When <code>build.cmd</code> finishes, review the file <code>compiler.errors</code>.
This file should contain only informational messages, almost all complaining
about constant values in comparisons.</li>
<li>You should now have a <code>xerces-c.dll</code> and <code>xerces-c.lib</code>.
The library file is an import library for the DLL.</li>
</ol>
<p><em>The "From Scratch" Method</em></p>
<ol>
<li>If you are not currently running <code>Object Rexx</code>,
run the <code>SWITCHRX</code> command from a command line,
answer <code>"yes"</code> to switching to <code>Object Rexx</code>, and follow the
instructions to reboot. You can switch back to <code>"Classic Rexx"</code> by running
<code>SWITCHRX</code> again. But you probably won't need to switch back since
<code>Object Rexx</code> runs almost 100% of Classic Rexx programs.</li>
<li>In the <code>&XercesCSrcInstallDir;\Projects\OS2\VACPP40</code> directory,
run <code>genICC.cmd</code>. This builds the VAC++ configuration files for
the sources you have on your system.</li>
<li>Check the generated <code>ICC</code> 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 <code>ICC</code> file or add them to the "ignore" array in <code>genICC.cmd</code> and
re-run <code>genICC</code>.</li>
<li>Start the Command Line in the VAC++ folder.</li>
<li>Navigate to the <code>&XercesCSrcInstallDir;\Projects\OS2\VACPP40</code> directory.</li>
<li>Run <code>build.cmd</code> This does a migration build.</li>
<li>When <code>build.cmd</code> finishes, review the file <code>compiler.errors</code>.
This file should contain only informational messages, almost all complaining about constant
values in comparisons.</li>
<li>You should now have a <code>xerces-c.dll</code> and <code>xerces-c.lib</code>.
The library file is an import library for the DLL.)</li>
</ol>
<p><em>Packaging the Binaries</em></p>
<p>There is an <code>Object Rexx</code> program that will package the binaries and headers.
(See step 1 of the "From scratch" method on how to switch to <code>Object Rexx</code>.) The
<code>packageBinaries.cmd</code> file is in the <code>&XercesCSrcInstallDir;\Projects\OS2\VACPP40</code>
directory. Run <code>packageBinaries</code>, giving the source and target directories
like this:</p>
<source>packageBinaries -s x:\&XercesCSrcInstallDir; -o x:\temp\&XercesCInstallDir;-os2</source>
<p>(Match the source directory to your system; the target directory can be
anything you want.)</p>
<note>If you don't want to use the <code>Object Rexx</code> 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
<code>&XercesCSrcInstallDir;</code>.)</note>
</s3>
</a>
</faq>
<faq title="Building &XercesCName; on AS/400">
<q>Building &XercesCName; on AS/400</q>
<a>
<p>The following addresses the requirements and build of
&XercesCName; natively on the AS/400.
</p>
<s3 title="Building &XercesCName; library">
<p><em>Requirements:</em></p>
<ul>
<li><code>QSHELL</code> interpreter installed (install base option 30, operating system)</li>
<li>QShell Utilities, PRPQ 5799-XEH</li>
<li>ILE C++ for AS/400, PRPQ 5799-GDW</li>
<li>GNU facilities (the gnu facilities are currently available by request
only. Send e-mail to <jump href="mailto:rchgo400@us.ibm.com">rchgo400@us.ibm.com</jump>)</li>
</ul>
<p><em>Recommendations:</em></p>
<ul>
<li>There are a couple of options when building the &XercesCName; 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 <code>Iconv400</code> 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.</li>
<li>Currently we recommend that you take the options of <code>MsgFile</code> and
<code>Iconv400</code> (see below)</li>
</ul>
<p><em>Setup Instructions:</em></p>
<ul>
<li>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 <code>*module</code>,
<code>*pgm</code> and <code>*srvpgm</code> objects in libraries.</li>
<li>Download the tar file (unix version) to the AS/400
(using a mapped drive), and decompress and <code>untar</code> 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:</li></ul>
<source>qsh:
gunzip -d <tar file.gz>
pax -r -f <uncompressed tar file></source>
<ul>
<li>Create AS400 target library. This library will be the target
for the resulting modules and &XercesCName; service program. You will
specify this library on the <code>OUTPUTDIR</code> environment variable
in step 4</li>
<li>Set up the following environment variables in your build process
(use <code>ADDENVVAR</code> or <code>WRKENVVAR CL</code> commands):</li>
</ul>
<source>XERCESCROOT - <the full path to your &XercesCName; 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></source>
<ul>
<li>Add <code>QCXXN</code>, to your build process library list.
This results in the resolution of <code>CRTCPPMOD</code> used by the
<code>icc</code> compiler.</li>
<li>The runConfigure instruction below uses <code>'egrep'</code>.
This is not on the AS/400 but you can create it by doing the following:
<code>edtf '/usr/bin/egrep'</code> with the following source:</li>
</ul>
<source>#!/usr/bin/sh
/usr/bin/grep -e "$@"</source>
<p>You may want to put the environment variables and library list
setup instructions in a <code>CL</code> program so you will not forget these steps
during your build.</p>
<p><em>Configure</em></p>
<p>To configure the make files for an AS/400 build do the following:</p>
<source>qsh
cd <full path to &XercesCName;>/src
runConfigure -p os400 -x icc -c icc -m MsgFile -t Iconv400</source>
<p>Troubleshooting:</p>
<source>error: configure: error: installation or configuration problem:
C compiler cannot create executables.</source>
<p>If during <code>runConfigure</code> you see the above error message, it
can mean one of two things. Either <code>QCXXN</code> is not on your library
list <em>OR</em> the <code>runConfigure</code> cannot create the temporary
modules (<code>CONFTest1</code>, etc) it uses to test out the compiler
options. The second reason happens because the test modules already exist
from a previous run of <code>runConfigure</code>. To correct the problem,
do the following:</p>
<source>DLTMOD <your OUTPUTDIR library>/CONFT* and
DLTPGM your <OUTPUTDIR library>/CONFT*</source>
<p><em>Build</em></p>
<source>qsh
gmake -e</source>
<p>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 &XercesCName;/lib>. You can either bind your
XML application programs directly to the parser's service program
via the <code>BNDSRVPGM</code> option on the <code>CRTPGM</code> or
<code>CRTSRVPGM</code> command or you can specify a binding directory
on your <code>icc</code> command. To specify an archive file to bind to,
use the <code>-L, -l</code> binding options on icc. An archive file
on AS/400 is a binding directory. To create an archive file, use
<code>qar</code> command. (see the gnu facilities write up).
</p>
<p>
After building the &XercesCName; service program, create a binding directory
by doing the following (note, this binding directory is used when building
the samples):</p>
<source>qsh
cd <full path to &XercesCName;>/lib>
qar -cuv libxercesc1_1.a *.o
command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/&XercesCName;/lib/libxercesc1_1.a')
command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )</source>
<p><em>Troubleshooting:</em></p>
<p>If you are on a V4R3 system, you will get a bind problem
<code>'descriptor QlgCvtTextDescToDesc not found'</code> using Iconv400.
On V4R3 the system doesn't automatically pick up the <code>QSYS/QLGUSR</code> 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 <code>QLGUSR</code>
service program and then specify an additional <code>-L, -l</code> on the
<code>EXTRA_LINK_OPTIONS</code> in <code>Makefile.incl</code>.
See the <code>ln</code> and <code>qar</code> function in the gnu utilities.</p>
<p>To build for transcoder ICU:</p>
<ol>
<li>Make sure you have an <code>ICUROOT</code> path set up so that you can
find the ICU header files (usually <code>/usr/local</code>)</li>
<li>Make sure you have created a binding directory (symbolic link)
in the file system so that you can bind the &XercesCName; service program
to the ICU service program and specify that on the <code>EXTRA_LINK_OPTIONS</code>
in <code>src/Makefile.incl</code> (usually the default is a link
in <code>/usr/local/lib</code>).</li>
</ol>
<p><em>Creating AS400 XML parser message file:</em></p>
<p>As specified earlier, the <code>-m</code> MsgFile support on the
<code>runConfigure</code> 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:</p>
<source>EDTF <full path to &XercesCName;>/src/util/MsgLoaders/MsgFile/CrtXMLMsgs</source>
<p>In the prolog of <code>CrtXMLMsgs</code> there are instructions to create
the message file:</p>
<ol>
<li>Use the <code>CPYFRMSTMF</code> 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.</li>
<li>Create the CL program to create the message file and add the various
message descriptions</li>
<li>Call the CL program, providing the name of the message file
(use <code>QXMLMSG</code> as default) and a library (this can be any
library, including any product library in which you wish to embed
the xml parser)</li>
</ol>
<p>Note that the &XercesCName; source code for resolving parser messages is
using by default message file <code>QXMLMSG, *LIBL</code>.
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 <code>.cpp</code>
files prior to your build.</p>
<source><full path to &XercesCName;>/src/util/MsgLoaders/MsgFile/MsgLoader.cpp
<full path to &XercesCName;>/src/util/Platforms/OS400/OS400PlatformUtils.cpp</source>
<p><em>Troubleshooting:</em></p>
<p>If you are using the parser and are failing to get any message text
for error codes, it may be because of the <code>*LIBL</code> resolution of
the message file.</p>
</s3>
<s3 title="Building Samples on AS/400">
<source>qsh
cd <full path to &XercesCName;>/samples
runConfigure -p os400 -x icc -c icc
gmake -e</source>
<p><em>Troubleshooting:</em></p>
<p>If you take a <code>'sed'</code> error, while trying to make the samples.
This is an AS400 anomaly having to do with certain new line character and
the <code>sed</code> function. A temporary work around is to use <code>EDTF</code>
on the configure stream file (<code>../samples/configure</code>) and delete the
following line near the bottom: <code>s%@DEFS@%$DEFS%g</code>.
</p>
</s3>
</a>
</faq>
<faq title="Building &XercesCName; on Macintosh">
<q>Building &XercesCName; on Macintosh</q>
<a>
<p>The &XercesCName; Mac port has the key following attributes:
</p>
<ol>
<li>Built atop CoreServices APIs and a limited number of Carbon APIs;
supports builds for both Mac OS Classic, Carbon, and Mac OS X systems.
</li>
<li>Has a Mac OS native transcoder that utilizes the built-in Mac OS Unicode
converter [MacOSUnicodeConverter].
</li>
<li>Has a Mac OS native netaccessor that utilizes the built-in Mac OS URLAccess
routines [MacOSURLAccess].
</li>
<li>Supports builds from Metroworks CodeWarrior, Apple Project Builder,
and Mac OS X shell.
</li>
</ol>
<s3 title="Using &XercesCName; with CodeWarrior">
<p><em>&XercesCName; and CodeWarrior:</em>
</p>
<p>&XercesCName; may be built with CodeWarrior under Mac OS Classic or Mac OS X. Since
the &XercesCName; 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.
</p>
<p><em>Installing &XercesCName; for use with CodeWarrior:</em>
</p>
<p>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):
</p>
<ul>
<li>Retrieve &XercesCName; 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!
</li>
<li>&XercesCName; 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.
</li>
</ul>
<source>cd <xercescroot>
cp Projects/MacOS/ShortenFiles.pl .
perl ShortenFiles.pl</source>
<ul>
<li>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).
</li>
</ul>
<source>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</source>
<ul>
<li>Move the entire directory structure to your Mac OS machine.
</li>
</ul>
<p><em>Building &XercesCName; with CodeWarrior:</em>
</p>
<ul>
<li>Run CodeWarrior (tested with latest CW Pro 7.0).
</li>
<li>Import the project Projects/MacOS/CodeWarrior/XercesLib/XercesLib.mcp.xml,
saving it back out to the same directory as XercesLib.mcp.
</li>
<li>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.
</li>
</ul>
<p><em>Building &XercesCName; Samples with CodeWarrior:</em>
</p>
<p>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:
</p>
<ul>
<li>Once again, it is required that you import the .xml version of the project
file, and save it back out.
</li>
<li>The &XercesCName; 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.
</li>
</ul>
</s3>
<s3 title="Building &XercesCName; with Project Builder">
<p>Projects are included to build the &XercesCName; library and DOMPrint sample under
Apple's Project Builder for Mac OS X. The following notes apply:
</p>
<ul>
<li>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.
</li>
<li>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 &XercesCName; src directory.
</li>
<li>The DOMPrint project illustrates one such usage of the Xerces.framework.
</li>
</ul>
</s3>
<s3 title="Building &XercesCName; from the Mac OS X command line">
<p>Support for Mac OS X command line builds is now included in the standard
"unix" &XercesCName; build infrastructure.
</p>
<ul>
<li>In general, the Mac OS X command line build follows the generic unix
build instructions. You need to set your XERCESCROOT environment variable,
<code>./runConfigure</code>, and <code>make</code>.
</li>
</ul>
<source>setenv XERCESCROOT "<directory>"
cd src
./runConfigure -p macosx -n native
make</source>
<ul>
<li>Similar instructions apply to build the samples and tests, though the
<code>-n</code> flag is not used in these cases:
</li>
</ul>
<source>cd samples
./runConfigure -p macosx
make</source>
</s3>
<s3 title="Special usage information for &XercesCName; on the Macintosh">
<p><em>File Path Specification</em></p>
<p>Apart from the build instructions, above, the most important note
about use of &XercesCName; on the Macintosh is that &XercesCName; 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 <code>XMLCreateFullPathFromFSRef</code>
and <code>XMLParsePathToFSRef</code> as declared in the file
<code>MacOSPlatformUtils.hpp</code>. FSSpec variants of these routines are
also supplied.
</p>
<p><em>Mac OS Version Compatibility</em></p>
<p>&XercesCName; 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.
</p>
<p>Required components are:
</p>
<ul>
<li>Unicode Converter and Text Encoding Converter. These provide the base
transcoding service used to support &XercesCName; transcoding requirements.
</li>
</ul>
<p>Optional components are:
</p>
<ul>
<li>URLAccess. Provides NetAccessor support to &XercesCName; 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 &XercesCName; from running.
</li>
<li>Multiprocessing library. Provides mutual exclusion support. Once again,
the routines will back down gracefully if Multiprocessing support is not
available.
</li>
<li>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.
</li>
</ul>
</s3>
</a>
</faq>
</faqs>
