Build Instructions

Build Instructions

Build instructions are provided for the following platforms and compilers:

- UNIX/Linux/Mac OS X/Cygwin/MinGW
- Windows using Microsoft Visual C++
- Windows using Borland C++

Building on UNIX/Linux/Mac OS X/Cygwin/MinGW platforms

For building on UNIX and UNIX-like (GNU/Linux, Max OS X, Cygwin, MinGW-MSYS) platforms &XercesCName; uses the GNU automake-based build systems and requires that you have GNU make installed. On some platforms GNU make is called gmake instead of make.

As with all automake-based projects the build process is divided into two parts: configuration and building. The configuration part is performed using the `configure` script that can be found in the `&XercesC3SrcInstallDir;` directory. The build part is performed by invoking `make`.

Besides the standard `configure` options which you can view by running `configure --help`, &XercesCName; provides a number of project-specific options that are worth mentioning. You can specify one option for each category outlined below. If you do not specify anything for a particular category then `configure` will select the most appropriate default. At the end of its execution `configure` prints the selected values for each category.

Net Accessor (used to access network resources):

Option | Description
--- | ---
`--enable-netaccessor-curl` | use the libcurl library
`--enable-netaccessor-socket` | use plain sockets
`--enable-netaccessor-cfurl` | use the CFURL API (only on Mac OS X)
`--enable-netaccessor-winsock` | use WinSock (only on Windows, Cygwin, MinGW)
`--disable-network` | disable network support

Transcoder (used to convert between internal UTF-16 and other encodings):

Option | Description
--- | ---
`--enable-transcoder-gnuiconv` | use the GNU iconv library
`--enable-transcoder-iconv` | use the iconv library
`--enable-transcoder-icu` | use the ICU library
`--enable-transcoder-macosunicodeconverter` | use Mac OS X APIs (only on Mac OS X)
`--enable-transcoder-windows` | use Windows APIs (only on Windows, Cygwin, MinGW)

Message Loader (used to access diagnostics messages):

Option | Description
--- | ---
`--enable-msgloader-inmemory` | store the messages in memory
`--enable-msgloader-icu` | store the messages using the ICU resource bundles
`--enable-msgloader-iconv` | store the messages in the iconv message catalog

Thread support is enabled by default and can be disabled with the `--disable-threads` option.

By default `configure` selects both shared and static libraries. You can use the `--disable-shared` and `--disable-static` options to avoid building the version you don't need.

Finally, to make the build process cleaner the &XercesCName; build system hides actual compiler commands being executed by `make`. If you would like to see those then you can specify the `--disable-pretty-make` option.

If you need to specify compiler executables that should be used to build &XercesCName;, you can set the CC and CXX variables when invoking `configure`. Similarly, if you need to specify additional compiler or linker options, you can set the CFLAGS, CXXFLAGS, and LDFLAGS variables. For example:

    ./configure --disable-static CC=gcc-4.3 CXX=g++-4.3 CFLAGS=-O3 CXXFLAGS=-O3

Once the configuration part is complete you can run `make` (or `gmake`). Running `make` from the `&XercesC3SrcInstallDir;` directory builds &XercesCName; library and examples. The library is placed into the `src/.libs` directory. If you like to build only the library, you can run make from `&XercesC3SrcInstallDir;/src`.

If you would like to build the tests and run the automated test suite, run `make check` from the `&XercesC3SrcInstallDir;` directory. The automated test suite required Perl and the `diff` command.

Finally, to install the library and examples you can run `make install` (or `gmake install`). To change the installation directory, use the `--prefix` `configure` option.

Some platforms and configurations require extra `configure` and `make` options which are shown in the following table.

Platform | Compiler | Options
--- | --- | ---
Solaris x86 | Sun CC | `./configure CXX=CC CC=cc`
Solaris x86-64 | Sun CC | `./configure CXX=CC CC=cc CFLAGS=-xarch=amd64 CXXFLAGS=-xarch=amd64` (for newer Sun CC versions use -m64 instead of -xarch=amd64)
Solaris SPARC | Sun CC | `./configure CXX=CC CC=cc`
Solaris SPARCv9 | Sun CC | `./configure CXX=CC CC=cc CFLAGS=-xarch=v9 CXXFLAGS=-xarch=v9` (for newer Sun CC versions use -m64 instead of -xarch=v9)
AIX PowerPC | IBM XL C++ | `./configure CXX=xlC_r CC=xlc_r` `gmake libxerces_c_la_LDFLAGS=-qmkshrobj`
AIX PowerPC-64 | IBM XL C++ | `export OBJECT_MODE=64` `./configure CXX=xlC_r CC=xlc_r CXXFLAGS=-q64 CFLAGS=-q64` `gmake libxerces_c_la_LDFLAGS=-qmkshrobj`
HP-UX IA-64-32 | HP aCC | `./configure CXX=aCC CC=aCC CFLAGS=-mt CXXFLAGS=-mt LDFLAGS=-mt`
HP-UX IA-64 | HP aCC | `./configure CXX=aCC CC=aCC CFLAGS="-mt +DD64" CXXFLAGS="-mt +DD64" LDFLAGS="-mt +DD64"`
Mac OS X x86-64 | GCC | `./configure CFLAGS="-arch x86_64" CXXFLAGS="-arch x86_64"`
Mac OS X PowerPC-64 | GCC | `./configure CFLAGS="-arch ppc64" CXXFLAGS="-arch ppc64"`
Mac OS X x86/PowerPC | GCC | `./configure --disable-dependency-tracking CFLAGS="-arch i386 -arch ppc" CXXFLAGS="-arch i386 -arch ppc"`
Mingw x86 | GCC | `./configure LDFLAGS=-no-undefined`
Cygwin x86 | GCC | `./configure LDFLAGS=-no-undefined`

Note that different UNIX platforms use different system environment variable for finding shared libraries. On Linux and Solaris, the environment variable name is `LD_LIBRARY_PATH`, on AIX it is `LIBPATH`, on Mac OS X it is `DYLD_LIBRARY_PATH`, and on HP-UX it is `SHLIB_PATH`.

Note that Cygwin and MinGW are different from the UNIX platforms in the way they find shared libraries at run time. While UNIX platforms may use the `LD_LIBRARY_PATH` environment variable, Cygwin and MinGW use the `PATH` environment variable.

Building on Windows using Microsoft Visual C++

&XercesCName; source distribution comes with Microsoft Visual C++ projects and solutions. The following describes the steps you need to build with this compiler.

To build &XercesCName; from the source distribution you will need to open the solution containing the project. The solutions containing the &XercesCName; project files are in the following sub-directories in the `&XercesC3SrcInstallDir;` directory:

    (For VC7.1)  projects\Win32\VC7.1\xerces-all\xerces-all.sln
    (For VC8.0)  projects\Win32\VC8\xerces-all\xerces-all.sln
    (For VC9.0)  projects\Win32\VC9\xerces-all\xerces-all.sln
    (For VC10.0) projects\Win32\VC10\xerces-all\xerces-all.sln
    (For VC11.0) projects\Win32\VC11\xerces-all\xerces-all.sln
    (For VC12.0) projects\Win32\VC12\xerces-all\xerces-all.sln

Once you have the solution open, you need to build the project named `XercesLib`. You can select Debug/Release, Static/DLL, and, for VC8+, 32/64 bit builds using the Configuration Manager dialog. You can also select whether the &XercesCName; library should use ICU for transcoding.

When building your own applications you need to make sure that you are linking your application with the &XercesC3WindowsLib;.lib (Release) and/or &XercesC3WindowsLib;D.lib (Debug) libraries (or the static versions of them) and also that the associated DLLs are somewhere in the executable/DLL search path (`PATH`).

If you are linking your application to the static &XercesCName; library, then you will need to compile your application with the XERCES_STATIC_LIBRARY preprocessor macro defined in order to turn off the DLL import/export mechanism.

If you would also like to build tests and/or samples, inside the solution files mentioned above, you'll find several other projects which are for the tests and samples. Select all the tests/samples that you would like to build and then right click on the selection. Choose "Build (selection only)" to build all the selected projects in one shot.

Building on Windows using Borland C++

&XercesCName; source distribution comes with the Borland C++ makefiles. The following describes the steps you need to build &XercesCName; with this compiler.

1. Change to the `&XercesC3SrcInstallDir;\projects\Win32\BCC5\Xerces-all` directory
2. Run `MakeBuildDirs.bat`
3. `make -f Xerces-all.mak` to build the library, examples, and tests.