| <?xml version="1.0" standalone="no"?> |
| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| --> |
| |
| <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd"> |
| |
| <s1 title="Building on Other Platforms"> |
| <anchor name="iSeries"/> |
| <s2 title="Building &XercesCName; on iSeries (AS/400)"> |
| <p>The following addresses the requirements and build of |
| &XercesCName; natively on the iSeries. |
| </p> |
| <s3 title="Building &XercesCName; library"> |
| <p><em>Requirements:</em></p> |
| |
| <ul> |
| <li>OS/400 <code>QSHELL</code> interpreter installed (install base option 30, operating system)</li> |
| <li>OS/400 - Portable App Solutions Environment (PASE) installed (install base option 33, operating system)</li> |
| <li>iSeries Tools for Developers, PRPQ 5799-PTL (these are the gnu utilities)</li> |
| <li>For v5: WebSphere Development ToolsSet, 5722-WDS ( installed option 52, Compiler - ILE C++)</li> |
| </ul> |
| |
| <p><em>Recommendation:</em></p> |
| |
| <ul> |
| <li>There is one option when building the XML4C parser on iSeries. |
| For code page translation, you can use the iSeries |
| native <code>Iconv400</code> support or <code>icu</code> as the transcoder plug in. 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 <code>Iconv400</code>.</li> |
| </ul> |
| |
| <p><em>Setup Instructions:</em></p> |
| |
| <ul> |
| <li>Make sure that you have the requirements installed on your iSeries. |
| We highly recommend that you read the write up 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 <code>*module</code>, |
| <code>*pgm</code> and <code>*srvpgm</code> objects in libraries.</li> |
| |
| <li>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.</li> |
| |
| <li>Create iSeries target library. This library will be the target |
| for the resulting modules and &XercesCName; service program. You will |
| specify this library on the OUTPUTDIR 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 up to the &XercesCName; src directory, but not including 'src'> |
| MAKE - '/qibm/proddata/developertools/qsh/bin/gmake' |
| OUTPUTDIR - <identifies target iSeries library for *module, *pgm and *srvpgm objects> |
| PATH - '/usr/bin:/qibm/proddata/developertools/qsh/bin' |
| ICUROOT - (if using ICU) <the path of your ICU installation> |
| </source> |
| |
| <ul> |
| <li>For v4r5m0 systems, add QCXXN, to your build process library list. |
| This results in the resolution of CRTCPPMOD used by the icc compiler.</li> |
| </ul> |
| |
| <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 iSeries build do the following under Qsh:</p> |
| <source>qsh: |
| cd <full path to &XercesCName;>/src/xercesc |
| edit runConfigure and comment out the line: |
| getoptErr=`getopt p:c:x:dm:n:t:r:b:l:z:P:C:h $*` |
| runConfigure -p os400 -x icc -c icc -m inmem -t Iconv400 -r none</source> |
| |
| <p>Troubleshooting:</p> |
| <source>error: configure: error: installation or configuration problem: |
| C compiler cannot create executables.</source> |
| |
| <p>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 <em>OR</em> the <code>runConfigure</code> cannot create the temporary |
| modules (<code>CONFTest1</code>, etc) it uses to test out the compiler |
| options or <code>PASE</code> is not installed. 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>CL: |
| DLTMOD <OUTPUTDIR library>/CONFT* and |
| DLTPGM <OUTPUTDIR library>/CONFT*</source> |
| |
| <p><em>Build</em></p> |
| <p>If runConfigure runs fine then do the following under Qsh to actually build the modules:</p> |
| <source>qsh: |
| cd <full path to &XercesCName;>/src/xercesc |
| gmake</source> |
| |
| <p>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 &XercesCName;/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.</p> |
| |
| <p>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 <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 iSeries is a binding directory. To create an archive file, use |
| <code>qar</code> command. (see the iSeries Tools for Developers write up). |
| </p> |
| |
| <p>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)):</p> |
| <source>qsh: |
| cd <full path to &XercesCName;>/lib |
| qar -cuv &XercesCUnixLib;&XercesCUnixSoName;.so *.o |
| will results in |
| command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/&XercesCName;/lib/&XercesCUnixLib;&XercesCUnixSoName;.so') |
| command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )</source> |
| |
| |
| <p><em>Troubleshooting gmake problem:</em></p> |
| <p>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:</p> |
| <source> |
| FAILURE: spawnp() with errno = 3491 |
| GMAKE: vfork: Argument list too long. |
| </source> |
| |
| <p>If this is the case, you can manually create the service program by doing the following:</p> |
| |
| <source>CL: |
| CRTSRVPGM (<OUTPUTDIR-library>/libxercesc) MODULE(<OUTPUTDIR-library>/*ALL) EXPORT(*ALL) TEXT('XML4C parser version xxx') |
| OPTION(*DUPPROC *DUPVAR *NOWARN) AUT(*USE) |
| </source> |
| |
| <p>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:</p> |
| |
| <source> |
| qsh: |
| cd <full path to &XercesCName;>/lib |
| ln -s /qsys.lib/<outputdir>.lib/libxercesc.srvpgm &XercesCUnixLib;&XercesCUnixSoName;.so |
| qar -cuv &XercesCUnixLib;&XercesCUnixSoName;.so *.o |
| </source> |
| |
| <p>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:</p> |
| |
| <ul> |
| <li>src/xercesc/dom/impl/DOMDocumentImpl.cpp</li> |
| <li>src/xercesc/dom/impl/DOMDocumentImpl.hpp</li> |
| <li>src/xercesc/dom/deprecated/DocumentImpl.cpp</li> |
| <li>src/xercesc/dom/deprecated/DocumentImpl.hpp</li> |
| <li>src/xercesc/validators/common/ContentSpecNode.hpp</li> |
| </ul> |
| |
| <p>Update the following routines in src/xercesc/dom/deprecated/DocumentImpl.cpp as follows:</p> |
| <source> |
| 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; |
| } |
| </source> |
| |
| <p>To update src/xercesc/dom/deprecated/DoumentImpl.hpp as follows:</p> |
| |
| <source> |
| #ifdef __OS400__ |
| RefHashTableOf<char> *userData; |
| #else |
| |
| RefHashTableOf<void> *userData; |
| #endif |
| </source> |
| |
| <p>Update the following routines in src/xercesc/dom/impl/DOMDocumentImpl.cpp as follows:</p> |
| <source> |
| void DOMDocumentImpl::setUserData(DOMNode* 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* DOMDocumentImpl::getUserData(const DOMNode* n) const |
| { |
| if (fUserData) |
| #ifdef __OS400__ |
| return (void*) fUserData->get((void*)n); |
| #else |
| return fUserData->get((void*)n); |
| #endif |
| |
| else |
| return 0; |
| } |
| </source> |
| |
| <p>To update src/xercesc/dom/impl/DOMDocumentImpl.hpp:</p> |
| <source> |
| #ifdef __OS400__ |
| RefHashTableOf<char> *fUserData; |
| #else |
| RefHashTableOf<void> *fUserData; |
| #endif |
| </source> |
| <p>Update validators/common/ContentSpecNode.hpp removing the following:</p> |
| <source> |
| #ifndef __OS400__ |
| inline |
| #endif |
| ContentSpecNode::~ContentSpecNode() |
| </source> |
| |
| <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/xercesc/Makefile.incl</code> (usually the default is a link |
| in <code>/usr/local/lib</code>).</li> |
| </ol> |
| |
| </s3> |
| |
| <s3 title="Building Samples on iSeries"> |
| |
| <p>Note that the samples will create programs bind to the BND directory object |
| created by qar referenced above.</p> |
| <source>qsh |
| cd <full path to &XercesCName;>/samples |
| runConfigure -p os400 -x icc -c icc |
| gmake </source> |
| |
| </s3> |
| </s2> |
| |
| <anchor name="Mac"/> |
| <s2 title="Building &XercesCName; on Macintosh"> |
| <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 two Mac OS native netaccessor classes. The first is based on Carbon and |
| classic supported URLAccess and may be used in the broadest variety of |
| configurations [MacOSURLAccess]. The second [MacOSURLAccessCF] is based on |
| CFURLAccess, which requires either Carbon or Mac OS X CoreServices.framework. |
| This second NetAccessor is useful in Mac OS X configurations where reliance on |
| the full Carbon.framework would prohibit execution of the Xerces code in a |
| remote context that has no access to the GUI. |
| </li> |
| |
| <li>Supports builds from Metroworks CodeWarrior, Apple Xcode, |
| and Mac OS X shell. Projects for Apple Project Builder are still included, |
| but may not be up to date (you may need to revise the projects to accomodate |
| recent file additions, deletions, or other changes in &XercesCName;). |
| </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 earlier versions |
| of Mac OS, as well as earlier versions of CodeWarrior, did not support file names |
| longer than 32 characters, CodeWarrior 8.0 is required. If you are building &XercesCName; |
| on a Mac OS 9 system, be extremely careful in how to unpack and/or transfer the &XercesCName; |
| files to that system, to ensure that their file names are not truncated in the process. |
| </p> |
| |
| <p><em>Installing &XercesCName; for use with CodeWarrior:</em> |
| </p> |
| |
| <p>Note: versions of CodeWarrior prior to 8.0 did not support HFS+ long file names, |
| and thus required special steps to alter the file names prior to use. This restriction |
| has been removed for CodeWarrior 8.0, and the projects now directly reference the unaltered |
| source tree. The project files in this release require CodeWarrior v8.0 or higher. |
| </p> |
| |
| <p>It is extemely important to ensure that you retrieve and unpack the sources |
| with a tool that does not truncate file names. The command line gnutar utility on Mac |
| OS X will do the right thing; older versions of StuffIt truncate names to 31 characters as |
| they unpack tar archives, though versions >= 7.0.1 seem to work, at least on Mac OS X. |
| The command line tool tar will truncate path names that get too long; gnutar should be |
| used instead. Failure to heed these warnings will result in broken projects. |
| </p> |
| |
| <p><em>Building &XercesCName; with CodeWarrior:</em> |
| </p> |
| |
| <ul> |
| <li>Run CodeWarrior (requires CodeWarrior 8.0 with support for long file names). |
| </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 Xcode"> |
| |
| <p>Projects are included to build the &XercesCName; library and DOMPrint sample under |
| Apple's Xcode for Mac OS X. The following notes apply: |
| </p> |
| |
| <ul> |
| <li>Be sure to heed warnings under "special instructions" below regarding which |
| tools must be used to unpack archives: gnutar is your friend. |
| </li> |
| |
| <li>The Xcode 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 |
| (the full path up to the Xerces-C++ src directory, but not including 'src'), |
| <code>./runConfigure</code>, and <code>make</code>. Be sure to heed warnings |
| under "special instructions" below regarding which tools must be used to unpack |
| archives: gnutar is your friend. |
| </li> |
| </ul> |
| |
| <source>export XERCESCROOT="<xerces-c-directory>" |
| cd src/xercesc |
| ./runConfigure -p macosx -n native -t native |
| make</source> |
| |
| <ul> |
| <li>Similar instructions apply to build the samples and tests, though the |
| <code>-n</code> and <code>-t</code> flags are 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>Unpacking the tar archive</em></p> |
| |
| <p>It is extemely important to ensure that you retrieve and unpack the sources |
| with a tool that does not truncate file names. The command line gnutar utility on Mac |
| OS X will do the right thing; older versions of StuffIt truncate names to 31 characters as |
| they unpack tar archives, though versions >= 7.0.1 seem to work, at least on Mac OS X. |
| The command line tool tar will truncate path names that get too long; gnutar should be |
| used instead. Failure to heed these warnings will result in broken projects. |
| </p> |
| |
| <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>. <code>FSSpec</code> 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. If &XercesCName; is |
| configured to use MacOSURLAccessCF, then URLAccess (and thus Carbon) |
| is not required, but CoreServices.framework is required for Mac OS X. |
| </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> |
| </s2> |
| </s1> |