BUILDINSTRUCTIONS.TXT ===================== **************************************************************************** WARNING: This is not the best place to look for build instructions. You should go to http://xml.apache.org/xerces-c/build.html to see the latest stuff. The web-page is maintained more regularly than this text file. However, if you insist, here is a text dump of the same web-page from ancient times. End of warning! **************************************************************************** This page has sections on the following topics: * Building Xerces-C++ on Windows 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? * Where can I look for more help? Building Xerces-C++ on Windows NT/98 ==================================== Xerces-C++ comes with Microsoft Visual C++ projects and workspaces to help you build Xerces-C++. The following describes the steps you need to build Xerces-C++. Building Xerces-C++ library ---------------------------- To build Xerces-C++ from it source (using MSVC), you will need to open the workspace containing the project. If you are building your application, you may want to add the Xerces-C++ project inside your applications's workspace. The workspace containing the Xerces-C++ project file and all other samples is: xerces-c-src1_6_0\Projects\Win32\VC6\xerces-all\xerces-all.dsw Once you are inside MSVC, you need to build the project marked XercesLib. If you want to include the Xerces-C++ project separately, you need to pick up: xerces-c-src1_6_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. 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 ---------------- 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. 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. 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:/xerces-c1_6_0 d:/icu. Instructions: 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. These instructions assume that you install in drive d:\. Replace d with the appropriate drive letter. Building Xerces-C++ on Windows using Borland C++Builder ======================================================= 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++. Building Xerces-C++ library --------------------------- The library and demo projects are all contained in the Xerces-all project group: * xerces-c-src1_6_0\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_6_0\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++ 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 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 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. 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. 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= 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: Helper script to run "configure" for one of the supported platforms Usage: runConfigure "options" where options may be any of the following: -p (accepts 'aix', 'linux', 'solaris', 'hp-10', 'hp-11', 'unixware', 'os400', 'irix', 'ptx', 'tru64', 'macosx' ) -c (e.g. gcc, cc, xlc_r, icc) -x (e.g. g++, CC, xlC_r, icc, c++) -d (specifies that you want to build debug version) -m can be 'inmem', 'icu', 'MsgFile' or 'iconv' -n can be 'fileonly', 'libwww', 'socket' or 'native' -t can be 'icu', 'Iconv400', 'Iconv390' or 'native' -r can be 'pthread' or 'dce' (only used on aix, HP-11 and solaris) or 'sproc' (only on IRIX) or 'none' -l -z -P -C -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. cd xerces-c1_6_0-linux/samples ./runConfigure -p -c -x gmake This will create the object files in each sample directory and the executables in ' xerces-c1_6_0-linux/bin' directory. 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 (accepts 'aix', 'unixware', 'linux', 'solaris', 'hp-10', 'hp-11', 'os400', 'irix', 'ptx', 'tru64', 'macosx') -c (e.g. gcc, xlc or icc) -x (e.g. g++, xlC, or icc) -d (specifies that you want to build debug version) -h (get help on the above commands) -z 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. To delete all the generated object files and executables, type: gmake clean Building Xerces-C++ as a single-threaded library on Unix platforms ================================================================== 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 - * 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 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 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) ============================ The following addresses the requirements and build of Xerces-C++ natively on the iSeries. Building Xerces-C++ library --------------------------- 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 v4r5m0: ILE C++ for AS/400, PRPQ 5799-GDW * For v5: WebSphere Development ToolsSet, 5722-WDS ( installed option 52, Compiler - ILE C++) Recommendations: * 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. \\\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 - MAKE - '/usr/bin/gmake' OUTPUTDIR - ICUROOT - (optional if using ICU) * 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 /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 /CONFT* and DLTPGM /CONFT* Build qsh: cd /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 . 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 /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 (/libxercesc) MODULE(/*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 /lib ln -s /qsys.lib/.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(29, false, new HashPtr()); #else userData = new RefHashTableOf(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 *userData; #else RefHashTableOf *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(29, false, new (this) HashPtr()); #else fUserData = new (this) RefHashTableOf(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 *fUserData; #else RefHashTableOf *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 --------------------------- Note that the samples will create programs bind to the BND directory object created by qar referenced above. qsh cd /samples runConfigure -p os400 -x icc -c icc gmake Building Xerces-C++ 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. 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 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 "" 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: 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 (Match the source directory to your system; the target directory can be anything you want.) 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. For a description of options available, you can enter: 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