| <?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 6.2). |
| </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> |
| |
| <li>Note that the Carbon targets contain an access path for a Carbon Support |
| folder in the compiler folder. Up-to-date Apple headers and libraries |
| are required. Either create a Carbon Support folder with recent headers and |
| libraries or, if your MacOS Support folder is up to date, point the |
| access path to this, or make an alias to it called "Carbon Support". |
| </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> |
