| 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. |
| * Building Xerces-C on UNIX. |
| * Building Xerces-C on Windows using Visual Age. |
| * Building Xerces-C on OS/2 using Visual Age. |
| * Building Xerces-C on AS/400. |
| * Building Xerces-C on Macintosh. |
| * Building ICU. |
| * How to build the User Documentation?. |
| * I wish to port Xerces to my favourite platform. Do you have any suggestions? |
| * What should I define XMLCh to be? |
| * How can I generate Xerces-C binaries which includes the sample NetAccessor implementation using Libwww? |
| * Where can I look for more help? |
| |
| |
| Building on Windows 2000/NT/98 |
| ============================== |
| |
| Borland C++Builder Compiler |
| --------------------------- |
| Xerces-C comes with Borland C++Builder projects to help you build Xerces-C. |
| The following describes the steps you need to build Xerces-C. The library |
| and demo projects are all contained in the Xerces-all project group: |
| |
| xerces-c-src1_5_1\Projects\Win32\BCB5\Xerces-all\Xerces-all.bpg |
| |
| Each project in the group refers a directory belog \Xerces-all. For example |
| the XercesLib project files are contained in the directory |
| |
| xerces-c-src1_5_1\Projects\Win32\BCB5\Xerces-all\XercesLib |
| |
| To build any project, open the project manager. Double click on the project |
| name. Then select "Project|Build" from the menu. For example, double click |
| on XercesLib.dll in the manager. Then select "Project|Build XercesLib" from |
| the menu. |
| |
| Once the library has been built, include XercesLib.lib with in application's |
| project and place XercesLib.dll somewhere in your path. |
| |
| |
| Microsoft Visual C++ |
| -------------------- |
| Xerces-C comes with Microsoft Visual C++ projects and workspaces to help you |
| build Xerces-C. The following describes the steps you need to build Xerces-C. |
| |
| 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-src-1_1_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-src-1_1_0\Projects\Win32\VC6\xerces-all\XercesLib\XercesLib.dsp |
| |
| You must make sure that you are linking your application with the xerces-c_1.lib |
| library and also make sure that the associated DLL is somewhere in your path. |
| |
| [Note] |
| If you are working on the AlphaWorks version which uses ICU, you must either |
| have the environment variable ICU_DATA set, or keep the international converter |
| files relative to the Xerces DLL (as it came with the original binary drop) for |
| the program to find it. For finding out where you can get ICU from and build it, |
| look at the last section of this page. |
| |
| |
| Building samples |
| |
| Inside the same workspace (xerces-all.dsw), you'll find |
| several other projects. These are for the samples. Select |
| all the samples and right click on the selection. Then |
| choose "Build (selection only)" to build all the samples in |
| one shot. |
| |
| |
| Building on UNIX platforms |
| |
| Xerces-C uses GNU tools like Autoconf and GNU Make to build the system. You must first make |
| sure you have these tools installed on your system before proceeding. If you don not have |
| required tools, ask your system administrator to get them for you. These tools are free under |
| the GNU Public Licence and may be obtained from the Free Software Foundation. |
| |
| Do not jump into the build directly before reading this. |
| |
| Spending some time reading the following instructions will save you a lot of wasted time and |
| support-related e-mail communication. The Xerces-C build instructions are a little different |
| from normal product builds. Specifically, there are some wrapper-scripts that have been |
| written to make life easier for you. You are free not to use these scripts and use Autoconf |
| and GNU Make directly, but we want to make sure you know what you are by-passing and what |
| risks you are taking. So read the following instructions carefully before attempting to build |
| it yourself. |
| |
| Besides having all necessary build tools, you also need to know what compilers we have tested |
| Xerces-C on. The following table lists the relevant platforms and compilers. |
| |
| Operating System Compiler |
| Redhat Linux 6.1 egcs |
| AIX 4.3.3 and higher xlC |
| Solaris 2.6 CC |
| HP-UX 10.2 CC |
| HP-UX 11 aCC |
| |
| If you are not using any of these compilers, you are taking a calculated risk by exploring |
| new grounds. Your effort in making Xerces-C work on this new compiler is greatly appreciated |
| and any problems you face can be addressed on the Xerces-C mailing list. |
| |
| Differences between the UNIX platforms: The description below is generic, but as every |
| programmer is aware, there are minor differences within the various UNIX flavors the world |
| has been bestowed with. The one difference that you need to watch out in the discussion |
| below, pertains to the system environment variable for finding libraries. On Linux and |
| Solaris, the environment variable name is called LD_LIBRARY_PATH, on AIX it is LIBPATH, while |
| on HP-UX it is SHLIB_PATH. The following discussion assumes you are working on Linux, but it |
| is with subtle understanding that you know how to interpret it for the other UNIX flavors. |
| |
| [Note] If you wish to build Xerces-C with ICU, look at the last section of this page. It |
| tells you where you can find ICU and how you can build Xerces-C to include the ICU |
| internationalization library. |
| |
| Setting build environment variables |
| |
| Before doing the build, you must first set your environment |
| variables to pick-up the compiler and also specify where you |
| extracted Xerces-C on your machine. While the first one is probably |
| set for you by the system administrator, just make sure you can |
| invoke the compiler. You may do so by typing the compiler invocation |
| command without any parameters (e.g. xlc_r, or g++, or cc) and check |
| if you get a proper response back. |
| |
| Next set your Xerces-C root path as follows: |
| |
| |
| |
| export XERCESCROOT=<full path to xerces-c-src-1_1_0> |
| |
| |
| |
| This should be the full path of the directory where you extracted |
| Xerces-C. |
| |
| |
| Building Xerces-C library |
| |
| As mentioned earlier, you must be ready with the GNU tools like autoconf and gmake before |
| you attempt the build. |
| |
| The autoconf tool is required on only one platform and produces a set of portable scripts |
| (configure) that you can run on all other platforms without actually having the autoconf |
| tool installed everywhere. In all probability the autoconf-generated script (called |
| configure) is already in your src directory. If not, type: |
| |
| |
| cd $XERCESCROOT/src |
| autoconf |
| |
| |
| |
| This generates a shell-script called configure. It is tempting to run this script directly |
| as is normally the case, but wait a minute. If you are using the default compilers like gcc |
| and g++ you do not have a problem. But if you are not on the standard GNU compilers, you |
| need to export a few more environment variables before you can invoke configure. |
| |
| Rather than make you to figure out what strange environment variables you need to use, we |
| have provided you with a wrapper script that does the job for you. All you need to tell the |
| script is what your compiler is, and what options you are going to use inside your build, |
| and the script does everything for you. Here is what the script takes as input: |
| |
| |
| runConfigure |
| runConfigure: Helper script to run "configure" for one of the |
| supported platforms. |
| Usage: runConfigure "options" |
| where options may be any of the following: |
| -p <platform> (accepts 'aix', 'linux', 'solaris', |
| 'hp-10', 'hp-11', 'irix', 'unixware') |
| -c <C compiler name> (e.g. gcc, cc, xlc) |
| -x <C++ compiler name> (e.g. g++, CC, xlC) |
| -d (specifies that you want to build debug version) |
| -m <message loader> can be 'inmem', 'icu', 'iconv' |
| -n <net accessor> can be 'fileonly', 'libwww' |
| -t <transcoder> can be 'icu' or 'native' |
| -r <thread option> can be 'pthread' or 'dce' (only used on HP-11) |
| -l <extra linker options> |
| -z <extra compiler options> |
| -h (to get help on the above commands) |
| |
| |
| [Note] Xerces-C builds as a standalone library and also as a library dependent on |
| International Components for Unicode (ICU). For simplicity, the following discussion |
| only targets standalone builds. |
| |
| One of the common ways to build Xerces-C is as follows: |
| |
| |
| runConfigure -plinux -cgcc -xg++ -minmem -nfileonly -tnative |
| |
| |
| |
| The response will be something like this: |
| |
| |
| Platform: linux |
| C Compiler: gcc |
| C++ Compiler: g++ |
| Extra compile options: |
| Extra link options: |
| Message Loader: inmem |
| Net Accessor: fileonly |
| Transcoder: native |
| Thread option: |
| Debug is OFF |
| |
| creating cache ./config.cache |
| checking for gcc... gcc |
| checking whether the C compiler (gcc -O -DXML_USE_NATIVE_TRANSCODER |
| -DXML_USE_INMEM_MESSAGELOADER ) works... yes |
| checking whether the C compiler (gcc -O -DXML_USE_NATIVE_TRANSCODER |
| -DXML_USE_INMEM_MESSAGELOADER ) is a cross-compiler... no |
| checking whether we are using GNU C... yes |
| checking whether gcc accepts -g... yes |
| checking for c++... g++ |
| checking whether the C++ compiler (g++ -O -DXML_USE_NATIVE_TRANSCODER |
| -DXML_USE_INMEM_MESSAGELOADER ) works... yes |
| checking whether the C++ compiler (g++ -O -DXML_USE_NATIVE_TRANSCODER |
| -DXML_USE_INMEM_MESSAGELOADER ) is a cross-compiler... no |
| checking whether we are using GNU C++... yes |
| checking whether g++ accepts -g... yes |
| checking for a BSD compatible install... /usr/bin/install -c |
| checking for autoconf... autoconf |
| checking for floor in -lm... yes |
| checking how to run the C preprocessor... gcc -E |
| checking for ANSI C header files... yes |
| checking for XMLByte... no |
| checking host system type... i686-pc-linux-gnu |
| updating cache ./config.cache |
| creating ./config.status |
| creating Makefile |
| creating util/Makefile |
| creating util/Transcoders/ICU/Makefile |
| creating util/Transcoders/Iconv/Makefile |
| creating util/Transcoders/Iconv400/Makefile |
| creating util/Platforms/Makefile |
| creating util/Compilers/Makefile |
| creating util/MsgLoaders/InMemory/Makefile |
| creating util/MsgLoaders/ICU/Makefile |
| creating util/MsgLoaders/MsgCatalog/Makefile |
| creating util/MsgLoaders/MsgFile/Makefile |
| creating validators/DTD/Makefile |
| creating framework/Makefile |
| creating dom/Makefile |
| creating parsers/Makefile |
| creating internal/Makefile |
| creating sax/Makefile |
| creating ../obj/Makefile |
| creating conf.h |
| conf.h is unchanged |
| |
| In future, you may also directly type the following commands to |
| create the Makefiles. |
| |
| export TRANSCODER=NATIVE |
| export MESSAGELOADER=INMEM |
| export USELIBWWW=0 |
| export CC=gcc |
| export CXX=g++ |
| export CXXFLAGS=-O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER |
| export CFLAGS=-O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER |
| export LIBS= -lpthread |
| configure |
| |
| If the result of the above commands look OK to you, go to the directory |
| $XERCESCROOT/src and type "gmake" to make the XERCES-C system. |
| |
| |
| |
| So now you see what the wrapper script has actually been doing! It has invoked configure to |
| create the Makefiles in the individual sub-directories, but in addition to that, it has set |
| a few environment variables to correctly configure your compiler and compiler flags too. |
| |
| Now that the Makefiles are all created, you are ready to do the actual build. |
| |
| |
| |
| gmake |
| |
| |
| |
| Is that it? Yes, that's all you need to build Xerces-C. |
| |
| |
| Building samples |
| |
| Similarly, you can build the samples by giving the same commands in the |
| samples directory. |
| |
| |
| cd $XERCESCROOT/samples |
| runConfigure -plinux -cgcc -xg++ |
| gmake |
| |
| |
| |
| The samples get built in the bin directory. Before you run the samples, |
| you must make sure that your library path is set to pick up libraries |
| from $XERCESCROOT/lib. If not, type the following to set your library |
| path properly. |
| |
| |
| |
| export LD_LIBRARY_PATH=$XERCESCROOT/lib:$LD_LIBRARY_PATH |
| |
| |
| |
| You are now set to run the sample applications. |
| |
| |
| Building Xerces-C on Windows using |
| |
| Visual Age C++ |
| |
| A few unsupported projects are also packaged with Xerces-C. |
| Due to origins of Xerces-C inside IBM labs, we do have |
| projects for IBM's Visual Age C++ compiler on Windows. The |
| following describes the steps you need to build Xerces-C |
| using Visual Age C++. |
| |
| |
| Building Xerces-C library |
| |
| Requirements: |
| |
| * VisualAge C++ Version 4.0 with Fixpak 1: |
| Download the Fixpak from the IBM VisualAge C++ |
| Corrective Services web page. |
| |
| To include the ICU library: |
| |
| * ICU Build: |
| You should have the ICU Library in the same directory |
| as the Xerces-C library. For example if Xerces-C is at |
| the top level of the d drive, put the ICU library at |
| the top level of d e.g. d:/xml4c, d:/icu. |
| |
| Instructions: |
| |
| 1. Change the directory to d:\xml4c\Projects\Win32 |
| 2. If a d:\xml4c\Project\Win32\VACPP40 directory does not |
| exist, create it. |
| 3. Copy the IBM VisualAge project file, XML4C2X.icc, to |
| the VACPP40 directory. |
| 4. From the VisualAge main menu enter the project file |
| name and path. |
| 5. When the build finishes the status bar displays this |
| message: Last Compile completed Successfully with |
| warnings on date. |
| |
| [Note] These instructions assume that you install in drive |
| d:\. Replace d with the appropriate drive letter. |
| |
| |
| Building on OS/2 using Visual Age C++ |
| |
| OS/2 is a favourite IBM PC platforms. The only option in |
| this platform is to use Visual Age C++ compiler. Here are |
| the steps you need to build Xerces-C using Visual Age C++ on |
| OS/2. |
| |
| |
| Building Xerces-C library |
| |
| Requirements: |
| |
| * VisualAge C++ Version 4.0 with Fixpak 1: |
| Download the Fixpak from the IBM VisualAge C++ |
| Corrective Services web page. |
| |
| To include the ICU library: |
| |
| * ICU Build: |
| You should have the ICU Library in the same directory |
| as the Xerces-C library. For example if Xerces-C is at |
| the top level of the d drive, put the ICU library at |
| the top level of d e.g. d:/xml4c, d:/icu. |
| |
| Instructions |
| |
| 1. Change directory to d:\xml4c\Projects\OS2 |
| 2. If a d:\xml4c\Project\OS2\VACPP40 directory does not |
| exist, create it. |
| 3. Copy the IBM VisualAge project file, XML4C2X.icc, to |
| the VACPP40 directory. |
| 4. From the VisualAge main menu enter the project file |
| name and path. |
| 5. When the build finishes the status bar displays this |
| message: Last Compile completed Successfully with |
| warnings on date. |
| |
| [Note] These instructions assume that you install in drive |
| d:\. Replace d with the appropriate drive letter. |
| |
| |
| Building on AS/400 |
| |
| The following addresses the requirements and build of Xerces-C natively on the AS/400. |
| |
| |
| Building Xerces-C library |
| |
| Requirements: |
| |
| * QSHELL interpreter installed (install base option 30, operating system) |
| * QShell Utilities, PRPQ 5799-XEH |
| * ILE C++ for AS/400, PRPQ 5799-GDW |
| * GNU facilities (the gnu facilities are currently available by request only. Send e-mail to |
| rchasgo400@us.ibm.com) |
| |
| Recommendations: |
| |
| * There are a couple of options when building the XML4C parser on AS/400. For messaging support, you can |
| use the in memory message option or the message file support. For code page translation, you can use |
| the AS/400 native Iconv400 support or ICU. If you choose ICU, follow the instructions to build the ICU |
| service program with the ICU download. Those instructions are not included here. |
| * Currently we recommend that you take the options of MsgFile and Iconv400 (see below) |
| |
| Setup Instructions: |
| |
| * Make sure that you have the requirements installed on your AS/400. We highly recommend that you read |
| the writeup that accompanies the gnu facilities download. There are install instructions as well as |
| information about how modules, programs and service programs can be created in Unix-like fashion using |
| gnu utilities. Note that symbolic links are use in the file system to point to actual AS/400 *module, |
| *pgm and *srvpgm objects in libraries. |
| * Download the tar file (unix version) to the AS/400 (using a mapped drive), and decompress and untar the |
| source. We have had difficulty with the tar command on AS/400. This is under investigation. If you have |
| trouble, we recommend the following work around: |
| |
| |
| qsh: |
| gunzip -d <tar file.gz> |
| pax -r -f <uncompressed tar file> |
| |
| |
| |
| * Create AS400 target library. This library will be the target for the resulting modules and Xerces-C |
| service program. You will specify this library on the OUTPUTDIR environment variable in step 4 |
| * Set up the following environment variables in your build process (use ADDENVVAR or WRKENVVAR CL |
| commands): |
| |
| |
| XERCESCROOT - <the full path to your Xerces-C sources> |
| PLATFORM - 'OS400' |
| MAKE - '/usr/bin/gmake' |
| OUTPUTDIR - <identifies target as400 library for *module, *pgm and *srvpgm objects> |
| ICUROOT - (optional if using ICU) <the path of your ICU includes> |
| |
| |
| |
| * Add QCXXN, to your build process library list. This results in the resolution of CRTCPPMOD used by the |
| icc compiler. |
| * The runConfigure instruction below uses 'egrep'. This is not on the AS/400 but you can create it by |
| doing the following: edtf '/usr/bin/egrep' with the following source: |
| |
| |
| #!/usr/bin/sh |
| /usr/bin/grep -e "$@" |
| |
| |
| |
| You may want to put the environment variables and library list setup instructions in a CL program so you |
| will not forget these steps during your build. |
| |
| Configure |
| |
| To configure the make files for an AS/400 build do the following: |
| |
| |
| qsh |
| cd <full path to Xerces-C>/src |
| runConfigure -p os400 -x icc -c icc -m MsgFile -t Iconv400 |
| |
| |
| |
| Troubleshooting: |
| |
| |
| error: configure: error: installation or configuration problem: |
| C compiler cannot create executables. |
| |
| |
| |
| If during runConfigure you see the above error message, it can mean one of two things. Either QCXXN is not |
| on your library list OR the runConfigure cannot create the temporary modules (CONFTest1, etc) it uses to |
| test out the compiler options. The second reason happens because the test modules already exist from a |
| previous run of runConfigure. To correct the problem, do the following: |
| |
| |
| DLTMOD <your OUTPUTDIR library>/CONFT* and |
| DLTPGM your <OUTPUTDIR library>/CONFT* |
| |
| |
| |
| Build |
| |
| |
| qsh |
| gmake -e |
| |
| |
| |
| The above gmake will result in a service program being created in your specified library and a symbolic link |
| to that service program placed in <path to Xerces-C/lib>. You can either bind your XML application programs |
| directly to the parser's service program via the BNDSRVPGM option on the CRTPGM or CRTSRVPGM command or you |
| can specify a binding directory on your icc command. To specify an archive file to bind to, use the -L, -l |
| binding options on icc. An archive file on AS/400 is a binding directory. To create an archive file, use qar |
| command. (see the gnu facilities write up). |
| |
| After building the Xerces-C service program, create a binding directory by doing the following (note, this |
| binding directory is used when building the samples): |
| |
| |
| qsh |
| cd <full path to Xerces-C>/lib> |
| qar -cuv libxercesc1_1.a *.o |
| command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/Xerces-C/lib/libxercesc1_1.a') |
| command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) ) |
| |
| |
| |
| Troubleshooting: |
| |
| If you are on a V4R3 system, you will get a bind problem 'descriptor QlgCvtTextDescToDesc not found' using |
| Iconv400. On V4R3 the system doesn't automatically pick up the QSYS/QLGUSR service program for you when |
| resolving this function. This is not the case on V4R4. To fix this, you can either manually create the |
| service program after creating all the resulting modules in your <OUTPUTDIR> library or you can create a |
| symbolic link to a binding directory that points to the QLGUSR service program and then specify an |
| additional -L, -l on the EXTRA_LINK_OPTIONS in Makefile.incl. See the ln and qar function in the gnu |
| utilities. |
| |
| To build for transcoder ICU: |
| |
| 1. Make sure you have an ICUROOT path set up so that you can find the ICU header files (usually |
| /usr/local) |
| 2. Make sure you have created a binding directory (symbolic link) in the file system so that you can bind |
| the Xerces-C service program to the ICU service program and specify that on the EXTRA_LINK_OPTIONS in |
| src/Makefile.incl (usually the default is a link in /usr/local/lib). |
| |
| Creating AS400 XML parser message file: |
| |
| As specified earlier, the -m MsgFile support on the runConfigure enable the parser messages to be pulled |
| from an AS/400 message file. To view the source for creating the message file and the XML parser messages, |
| see the following stream file: |
| |
| |
| |
| EDTF <full path to Xerces-C>/src/util/MsgLoaders/MsgFile/CrtXMLMsgs |
| |
| |
| |
| In the prolog of CrtXMLMsgs there are instructions to create the message file: |
| |
| 1. Use the CPYFRMSTMF to copy the CL source to an AS/400 source physical file. Note that the target source |
| file needs to have record length of about 200 bytes to avoid any truncation. |
| 2. Create the CL program to create the message file and add the various message descriptions |
| 3. Call the CL program, providing the name of the message file (use QXMLMSG as default) and a library |
| (this can be any library, including any product library in which you wish to embed the xml parser) |
| |
| Note that the Xerces-C source code for resolving parser messages is using by default message file QXMLMSG, |
| *LIBL. If you want to change either the message file name or explicitly qualify the library to match your |
| product needs, you must edit the following .cpp files prior to your build. |
| |
| |
| <full path to Xerces-C>/src/util/MsgLoaders/MsgFile/MsgLoader.cpp |
| <full path to Xerces-C>/src/util/Platforms/OS400/OS400PlatformUtils.cpp |
| |
| |
| |
| Troubleshooting: |
| |
| If you are using the parser and are failing to get any message text for error codes, it may be because of |
| the *LIBL resolution of the message file. |
| |
| |
| Building Samples on AS/400 |
| |
| |
| qsh |
| cd <full path to Xerces-C>/samples |
| runConfigure -p os400 -x icc -c icc |
| gmake -e |
| |
| |
| |
| Troubleshooting: |
| |
| If you take a 'sed' error, while trying to make the |
| samples. This is an AS400 anomaly having to do with certain |
| new line character and the sed function. A temporary work |
| around is to use EDTF on the configure stream file |
| (../samples/configure) and delete the following line near |
| the bottom: s%@DEFS@%$DEFS%g. |
| |
| |
| Building on Macintosh using CodeWarrior |
| |
| |
| Building Xerces-C library |
| |
| The directions in this file cover installing and building |
| Xerces-C and ICU under the MacOS using CodeWarrior. |
| |
| 1. Create a folder: |
| for the Xerces-C and ICU distributions, the "src drop" |
| folder |
| 2. Download and uncompress: |
| the ICU and Xerces-C source distribution |
| the ICU and Xerces-C binary distributions, for the |
| documentation included |
| 3. Move the new folders: |
| move the newly created Xerces-C and icu124 folders to |
| the "src drop" folder. |
| 4. Drag and drop: |
| the Xerces-C folder into the "rename file" application |
| located in the same folder as this readme. |
| This is a MacPerl script that renames files that have |
| names too long to fit in a HFS/HFS+ filesystem. It |
| also searches through all of the source code and |
| changes the #include statements to refer to the new |
| file names. |
| 5. Move the MacOS folder: |
| from the in the Projects folder to "src |
| drop:Xerces-C:Projects". |
| 6. Open and build Xerces-C: |
| open the CodeWarrior project file "src |
| drop:Xerces-C:Projects:MacOS:Xerces-C:Xerces-C" and |
| build the Xerces-C library. |
| 7. Open and build ICU: |
| open the CodeWarrior project file "src |
| drop:Xerces-C:Projects:MacOS:icu:icu" and build the |
| ICU library. |
| 8. Binary distribution: |
| If you wish, you can create projects for and build the |
| rest of the tools and test suites. They are not needed |
| if you just want to use Xerces-C. I suggest that you |
| use the binary data files distributed with the binary |
| distribution of ICU instead of creating your own from |
| the text data files in the ICE source distribution. |
| |
| There are some things to be aware of when creating your own |
| projects using Xerces-C. |
| |
| 1. You will need to link against both the ICU and |
| Xerces-C libraries. |
| 2. The options "Always search user paths" and "Interpret |
| DOS and Unix Paths" are very useful. Some of the code |
| won't compile without them set. |
| 3. Most of the tools and test code will require slight |
| modification to compile and run correctly (typecasts, |
| command line parameters, etc), but it is possible to |
| get them working correctly. |
| 4. You will most likely have to set up the Access Paths. |
| The access paths in the Xerces-C projects should serve |
| as a good example. |
| |
| [Note] These instructions were originally contributed by J. |
| Bellardo. Xerces-C has undergone many changes since |
| these instructions were written. So, these |
| instructions are not upto date. But it will give you |
| a jump start if you are struggling to get it to work |
| for the first time. We will be glad to get your |
| changes. Please respond to xerces-dev@xml.apache.org |
| with your comments and corrections. |
| |
| |
| How to Build ICU |
| |
| As mentioned earlier, Xerces-C may be built in stand-alone mode using native |
| encoding support and also using ICU where you get support for 100's of encodings. |
| ICU stands for International Components for Unicode and is an open source |
| distribution from IBM. You can get ICU libraries from IBM's developerWorks site or |
| go to the ICU download page directly. |
| |
| |
| Buiding ICU for Xerces-C |
| |
| You can find generic instructions to build ICU in the ICU |
| documentation. What we describe below are the minimal steps |
| needed to build ICU for Xerces-C. Not all ICU components |
| need to be built to make it work with Xerces-C. |
| |
| |
| [Note] Important: Please remember that ICU and Xerces-C |
| must be built with the same compiler, preferably |
| with the same version. You cannot for example, build |
| ICU with a threaded version of the xlC compiler and |
| build Xerces-C with a non-threaded one. |
| |
| |
| Building ICU on Windows |
| |
| To build ICU from its source, invoke the project |
| \icu\source\allinone\allinone.dsw and build the sub-project |
| labeled common. You may also want to build tools/makeconv |
| to make the converter tool. All others are not required for |
| the Xerces-C build to proceed. |
| |
| To build Xerces-C from it source, you will need to include |
| a project file in your workspace to program your |
| application. Otherwise, you can use the provided workspace |
| and add your application to it as a separate project. |
| |
| In the first case the project file is: |
| xml4c2\Projects\Win32\VC6\IXXML4C2\IXXML4C2\IXXML4C2.dsp |
| |
| In the second case the workspace is: |
| xml4c2\Projects\Win32\VC6\IXXML4C2\IXXML4C2.dsw |
| |
| You must make sure that you are linking your application |
| with the xerces-c_1.lib library and also make sure that the |
| associated DLL is somewhere in your path. Note that you |
| must either have the environment variable ICU_DATA set, or |
| keep the international converter files relative to the |
| Xerces DLL (as it came with the original binary drop) for |
| the program to find it. |
| |
| |
| Building ICU on UNIX platforms |
| |
| To build ICU on all UNIX platforms you at least need the autoconf tool and GNU's |
| gmake utility. |
| |
| First make sure that you have defined the following environment variables: |
| |
| |
| export ICUROOT = <icu_installdir> |
| export ICU_DATA = <icu_installdir>/data/ |
| |
| |
| |
| Next, go to the directory, the following commands will create a shell script called |
| 'configure': |
| |
| |
| cd $ICUROOT |
| cd source |
| autoconf |
| |
| |
| |
| Commands for specific UNIX platforms are different and are described separately |
| below. |
| |
| You will get a more detailed description of the use of configure in the ICU |
| documentation. The differences lie in the arguments passed to the configure script, |
| which is a platform-independent generated shell-script (through autoconf) and is |
| used to generate platform-specific Makefiles from generic Makefile.in files. |
| |
| For AIX: |
| |
| Type the following: |
| |
| |
| env CC="xlc_r -L/usr/lpp/xlC/lib" CXX="xlC_r -L/usr/lpp/xlC/lib" |
| C_FLAGS="-w -O" CXX_FLAGS="-w -O" |
| configure --prefix=$ICUROOT |
| cd common |
| gmake |
| gmake install |
| cd ../tools/makeconv |
| gmake |
| |
| |
| |
| For Solaris and Linux: |
| |
| |
| env CC="cc" CXX="CC" C_FLAGS="-w -O" CXX_FLAGS="-w -O" |
| ./configure --prefix=$ICUROOT |
| |
| |
| |
| For HP-UX with the aCC compiler: |
| |
| |
| env CC="cc" CXX="aCC" C_FLAGS="+DAportable -w -O" |
| CXX_FLAGS="+DAportable -w -O" ./configure --prefix=$ICUROOT |
| |
| |
| |
| For HP-UX with the CC compiler: |
| |
| |
| env CC="cc" CXX="CC" C_FLAGS="+DAportable -w -O" |
| CXX_FLAGS="+eh +DAportable -w -O" ./configure --prefix=$ICUROOT |
| |
| |
| |
| |
| How to build the 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.0 or later). |
| * Xalan (0.19.3 or later) |
| * Stylebook 1.0-b2 |
| |
| Setup PATH to include the JDK 1.2.2 bin directory. Also setup CLASSPATH |
| environment variable as follows: |
| |
| * Under Windows (assumes all jars are in '\jars' directory:) |
| CLASSPATH=\jars\stylebook-1.0-b2.jar;\jars\xalan.jar;\jars\xerces.jar |
| * Under Unix's (assumes all jars are in '~/jars' directory): |
| export |
| CLASSPATH="~/jars/stylebook-1.0-b2.jar:~/jars/xalan.jar:~/jars/xerces.jar" |
| |
| 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. |
| |
| Ok here is where you can get the three jar files that are referred to above. |
| |
| * JDK 1.2.2 is available from http://java.sun.com/products/jdk/1.2/ |
| * Xerces-J is available from http://xml.apache.org/dist/. Extract the |
| xerces.jar file from the binary drop and store it in the 'jars' directory |
| as mentioned above. |
| * Xalan is also available from http://xml.apache.org/dist/. Extract the |
| xalan.jar file from the 'jar' distribution that you just downloaded and |
| store it in the same 'jars' directory as mentioned above. |
| * Getting to Stylebook is little more involved. You will have to download |
| one of the 'xml-stylebook' tar balls from |
| http://xml.apache.org/from-cvs/xml-stylebook/ and then extract the file: |
| xml-stylebook/bin/stylebook-1.0-b2.jar |
| |
| Under Unix's you may enter: |
| gzip -d -c xml-stylebook_20000207231311.tar.gz | tar xf - |
| xml-stylebook/bin/stylebook-1.0-b2.jar |
| to extract this file. Copy it to the 'jars' directory as mentioned above. |
| |
| Under Windows you may use 'WinZip' to extract the jar file from the tar |
| ball. |
| |
| |
| I wish to port Xerces to my favourite |
| |
| platform. Do you have any suggestions? |
| |
| All platform dependent code in Xerces has been isolated to a |
| couple of files, which should ease the porting effort. Here |
| are the basic steps that should be followed to port Xerces. |
| |
| 1. The directory 'src/util/Platforms' contains the |
| platform sensitive files while 'src/util/Compilers' |
| contains all development environment sensitive files. |
| Each operating system has a file of its own and each |
| development environment has another one of its own too. |
| |
| As an example, the Win32 platform as a Win32Defs.hpp |
| file and the Visual C++ environment has a VCPPDefs.hpp |
| file. These files set up certain define tokens, |
| typedefs, constants, etc... that will drive the rest of |
| the code to do the right thing for that platform and |
| development environment. AIX/CSet have their own |
| AIXDefs.hpp and CSetDefs.hpp files, and so on. You |
| should create new versions of these files for your |
| platform and environment and follow the comments in |
| them to set up your own. Probably the comments in the |
| Win32 and Visual C++ will be the best to follow, since |
| that is where the main development is done. |
| 2. Next, edit the file XML4CDefs.hpp , which is where all |
| of the fundamental stuff comes into the system. You |
| will see conditional sections in there where the above |
| per-platform and per-environment headers are brought |
| in. Add the new ones for your platform under the |
| appropriate conditionals. |
| 3. Now edit 'AutoSense.hpp'. Here we set canonical Xerces |
| internal #define tokens which indicate the platform and |
| compiler. These definitions are based on known platform |
| and compiler defines. |
| AutoSense.hpp is included in XML4CDefs.hpp and the |
| canonical platform and compiler settings thus defined |
| will make the particular platform and compiler headers |
| to be the included at compilation. |
| It might be a little tricky to decipher this file so be |
| careful. If you are using say another compiler on |
| Win32, probably it will use similar tokens so that the |
| platform will get picked up already using what is |
| already there. |
| 4. Once this is done, you will then need to implement a |
| version of the 'platform utilities' for your platform. |
| Each operating system has a file which implements some |
| methods of the XMLPlatformUtils class, specific to that |
| operating system. These are not terribly complex, so it |
| should not be a lot of work. The Win32 verions is |
| called Win32PlatformUtils.cpp, the AIX version is |
| AIXPlatformUtils.cpp and so on. Create one for your |
| platform, with the correct name, and empty out all of |
| the implementation so that just the empty shells of the |
| methods are there (with dummy returns where needed to |
| make the compiler happy.) Once you've done that, you |
| can start to get it to build without any real |
| implementation. |
| 5. Once you have the system building, then start |
| implementing your own platform utilties methods. Follow |
| the comments in the Win32 version as to what they do, |
| the comments will be improved in subsequent versions, |
| but they should be fairly obvious now. Once you have |
| these implementations done, you should be able to start |
| debugging the system using the demo programs. |
| |
| That is the work required in a nutshell! |
| |
| |
| What should I define XMLCh to be? |
| |
| The answer is 'it depends'. We will mention some of the |
| quirks that affect this decision. Hopefully, after reading |
| whats below, you will be able to best decide what the right |
| definition should be. We could not however, resist making a |
| suggestion. Some observations first: |
| |
| * Xerces-C uses XMLCh as the fundamental type to hold one |
| Unicode character as, all processing inside Xerces-C |
| happens in Unicode. |
| * Most modern C++ compilers today provide 'wchar_t' as a |
| fundamental type representing a 'wide character'. Most |
| of them define it in using a typedef. This typedef |
| definition is not consistent on all the platforms that |
| we have come across. |
| * The size of wchar_t varies among the various compilers. |
| Its either 16-bit or 32-bit. Fortunately, this only |
| affects how much memory you need, to process the XML |
| data, while everything is still in memory. |
| * Again on most platforms wchar_t represents a unicode |
| character. HPUX, is one exception to this, that we |
| know, where wchar_t does not represent a unicode |
| character, rather its a native wide character. |
| * Lastly, most OS's/compilers provide a system library to |
| manipulate wide character strings taking wchar_t and |
| wchar_t* arguments. Most applications which support |
| wide-characters make these system calls. |
| Our suggestion is: |
| |
| If your compiler defines wchar_t to represent a unicode |
| character, then define XMLCh to be wchar_t. Such a |
| definition will allow you to pass the data returned by the |
| parser (all api's return XMLCh, which is wchar_t) directly |
| to the wide-character system api's for i/o or manipulation. |
| This is most efficient and convenient. |
| |
| However, if your compiler defines wchar_t to be just a |
| wide-character which is not Unicode, then define XMLCh to be |
| unsigned short. For the Xerces-C parser, XMLCh is always |
| Unicode. By defining it to be unsigned short and not |
| wchar_t, the compiler will not let you accidently pass what |
| is returned, via the parser API's, directly to the |
| wide-character library calls. To use the wide-character |
| library of functions, you will have to in your application, |
| call some transcoding function which will convert it from |
| Unicode to the native wide-character form. Again, if your |
| application desires for whatever reason, you may define |
| XMLCh to be 'unsigned long'. By doing so, you have just |
| doubled the memory required to process the XML file. |
| |
| Hopefully, you will agree that the answer 'it depends' was |
| the right one. |
| |
| |
| How can I generate Xerces-C binaries |
| which includes the sample NetAccessor |
| implementation using Libwww? |
| |
| This sample implementation has only been minimally tested |
| only under Windows NT using Libwww 5.2.8. We have not stress |
| tested our implementation can cannot guarantee that there |
| are no memory leaks. The error reporting is also not |
| adequate. Further, it only handles HTTP style URL's. As you |
| can see, this implementation is only for illustrative |
| purposes. Much more work is required to have a robust |
| cross-platform implementation. We would welcome any |
| volunteers who would contribute code to make this happen on |
| various platforms. |
| |
| The software that you need are: |
| |
| * You need the Xerces-C source archive for Windows. |
| * LibWWW 5.2.8. Win32 binaries are available at: |
| http://www.idm.ru/libwww.htm. Source archives and other |
| details on LibWWW are available at |
| http://www.w3.org/Library/. |
| |
| All required changes in Xerces-C are restricted to the |
| Project file settings for the XercesLib. To simplify, we |
| will make certain assumptions about how LibWWW binaries |
| (.lib) and header files are installed on your machine. |
| |
| 1. First generate all the LibWWW binaries by using the |
| project file supplied. Create a top level (say) \libWWW |
| directory on the same disk drive where you installed |
| the Xerces-C sources. Copy all the .lib files to |
| \libWWW\lib directory. Next, copy all the .dll files to |
| \libWWW\bin directory and all the header (*.h) files to |
| \libWWW\include directory. |
| 2. Next make the following changes to the Xerces-C lib |
| project settings. Invoke the project settings dialog |
| box. |
| 1. In the 'C/C++ : Preprocessor : Preprocessor |
| definitions' add XML_USE_NETACCESSOR_LIBWWW |
| 2. In the 'C/C++ : Preprocessor : Additional include |
| directories' add \libWWW\include. |
| 3. Next, rather than listing all the 20 some LibWWW .lib |
| files in the link settings, add them as external files |
| to the XercesLib project. Right-Click on 'XercesLib |
| files' and choose the 'Add Files to Project' menu item. |
| Next choose all the *.lib files in \libWWW\lib |
| directory and press 'ok'. |
| 4. Next, create a new sub-folder in XercesLib:util folder, |
| by right-clicking on 'util' and choosing 'New Folder'. |
| Call it 'libWWW'. |
| 5. Add netaccessor files into this 'libWWW' folder again, |
| by right-clicking on 'libWWW' folder and choosing 'Add |
| Files to Folder'. Choose the four files in |
| <XercesCRoot>\src\util\NetAccessors directory. These |
| files are: BinURLInputStream.[ch]pp and |
| LibWWWNetAccessor.[ch]pp. |
| 6. Rebuild the Xerces-C library. |
| |
| Make sure you have \libWWW\bin in your PATH environment |
| variable, before you run the samples and refer to a XML file |
| containing HTTP URL's to remote resources. |
| |
| |
| Where can I look for more help? |
| |
| If you have read this page, followed the instructions, and |
| still cannot resolve your problem(s), there is more help. |
| You can find out if others have solved this same problem |
| before you, by checking the Xerces mailing list archives. |
| |
| If all else fails, you may ask for help by subscribing to |
| the Xerces-C mailing list. |
| |
| |
| Copyright © 2000 The Apache Software Foundation. All Rights Reserved. |