http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Xerces Project

Overview
Charter
Release Info
Advisories
Download

Xerces-C++ 3.3.0
Installation
Build Instructions

Programming
Samples
FAQs

API Reference
DOM C++ Binding
Migration Guide

Feedback
Bug-Reporting
Mailing Lists

Source Repository
Applications

Build Instructions
 

Much of this documentation is historical in nature. The only officially supported platforms with committed testing and maintenance at this time are Windows (native, NOT Cygwin or other variants), Linux, and MacOS. All other builds are unsupported and untested and should be expected to require patching and build debugging. Patches are accepted for other platforms, as are maintainers interested in taking over responsibility for supporting them.

While the CMake support is portable, officially the autoconf support is intended to be used for Linux and MacOS and CMake used for Windows.

Build instructions are provided for the following platforms and compilers:

Building on all platforms with CMake
 

For building on any platform with any supported build system Xerces-C++ uses the CMake build generator and requires that you have CMake installed. Additionally, a build tool such as GNU make or Ninja is required for building. CMake supports a wide range of generators for several different compilers, build tools and popular IDEs, including Eclipse, Kate, Visual Studio, Sublime Text and more. Any of these may be used to build Xerces-C++. Run cmake --help to display the full list of supported generators for your platform.

As with all CMake projects, the build process is divided into several parts: configuration and building, followed by (optional) testing and installation. The configuration part is performed by running the cmake command. The build part is performed by invoking the chosen build tool such as make or ninja, or by opening the generated project files in your IDE, and building from within the IDE.

Besides the standard cmake variables, Xerces-C++ 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 cmake will select the most appropriate default, based upon the available options for your system. At the end of its execution cmake prints the selected values for each category.

Net Accessor (used to access network resources):

Option  Description 
-Dnetwork-accessor=curl  use the libcurl library (only on UNIX) 
-Dnetwork-accessor=socket  use plain sockets (only on UNIX) 
-Dnetwork-accessor=cfurl  use the CFURL API (only on Mac OS X) 
-Dnetwork-accessor=winsock  use WinSock (only on Windows, Cygwin, MinGW) 
-Dnetwork:BOOL=OFF  disable network support 

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

Option  Description 
-Dtranscoder=gnuiconv  use the GNU iconv library 
-Dtranscoder=iconv  use the iconv library 
-Dtranscoder=icu  use the ICU library 
-Dtranscoder=macosunicodeconverter  use Mac OS X APIs (only on Mac OS X) 
-Dtranscoder=windows  use Windows APIs (only on Windows and MinGW) 

Message Loader (used to access diagnostics messages):

Option  Description 
-Dmessage-loader=inmemory  store the messages in memory 
-Dmessage-loader=icu  store the messages using the ICU resource bundles 
-Dmessage-loader=iconv  store the messages in the iconv message catalog 

XMLCh type (UTF-16 character type):

Option  Description 
-Dxmlch-type=char16_t  use char16_t (requires a C++11 compiler) 
-Dxmlch-type=uint16_t  use uint16_t from <cstdint> or <stdint.h>, or another unsigned 16-bit type such as unsigned short if the standard types are unavailable 
-Dxmlch-type=wchar_t  use wchar_t (Windows only) 

MFC debug support is enabled by default (Windows only) and can be disabled with the -Dmfc-debug:BOOL=OFF option.

Thread support is enabled by default and can be disabled with the -Dthreads:BOOL=OFF option. If disabled, it will not be possible to select a mutex manager other than nothreads. If enabled, one of the following mutex managers may be selected:

Option  Description 
-Dmutex-manager=standard  Use Standard C++ mutex (requires a C++11 compiler) 
-Dmutex-manager=posix  Use POSIX threads (pthreads) mutex (only on UNIX and Cygwin) 
-Dmutex-manager=windows  Use Windows threads mutex (Windows and MinGW only) 
-Dmutex-manager=nothreads  Use dummy implementation (default if threading is disabled) 

Shared libraries are built by default. You can use the -DBUILD_SHARED_LIBS:BOOL=OFF option to build static libraries.

If you need to specify compiler executables that should be used to build Xerces-C++, you can set the CC and CXX environment variables when invoking cmake. Similarly, if you need to specify additional compiler or linker options, you can set the CFLAGS, CXXFLAGS, and LDFLAGS environment variables. For example:

CC=gcc-5.3 CXX=g++-5.3 CFLAGS=-O3 CXXFLAGS=-O3 cmake ...
Note If building on Windows, the specific Visual Studio version may be selected with some generators, and this may be run from a normal command prompt. If using a generic generator such as Ninja, then cmake should be run from a Visual Studio command prompt, or in a suitably configured environment, so that the correct compiler will be detected.

Once the configuration part is complete you can run the build tool of choice. This may be done generically using cmake --build . [--config=Debug|Release]. Alternatively, a specific build tool, e.g. make, gmake, ninja or msbuild corresponding to the chosen generator may be used directly. When invoked without a specific target, it will build the Xerces-C++ library, all examples and all unit tests.

If you would like to run the automated test suite, run ctest [-V] [-C Debug|Release]. This will run all tests. Additional options are available, such as running a subset of the tests and running the tests in parallel. If any discrepancies in the output are detected, the differences will be displayed if a diff program is available.

Finally, install the library and examples. This may be done generically using cmake --build . --target install. Alternatively, a specific build tool may be used, e.g. make install. To change the installation directory, use the -DCMAKE_INSTALL_PREFIX=prefix cmake option.

Some platforms and configurations may require extra cmake options. Run cmake -LH to list the additional options, along with a short description for each. For each of the selection categories mentioned above, the help text will list the valid choices detected for your platform. Run cmake -LAH for all the additional advanced settings.

Several examples of configuring, building, testing and installing with CMake using different platforms, generators, and installation options are shown below:

Platform  Generator  Example 
Any  Ninja  mkdir build
cd build
cmake -G Ninja -DCMAKE_INSTALL_PREFIX=/opt/xerces-c -DCMAKE_BUILD_TYPE=Release -Dnetwork-accessor=curl /path/to/xerces-c/source
ninja
ctest -V -j 8
ninja install 
Unix  Unix Makefiles  mkdir build
cd build
cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/opt/xerces-c -DCMAKE_BUILD_TYPE=Debug -Dmessage-loader=icu /path/to/xerces-c/source
make -j8
make test
make install 
Windows  msbuild with VS2015 x64  mkdir build
cd build
cmake -G "Visual Studio 14 2015 Win64" -DCMAKE_INSTALL_PREFIX=D:\libs    \path\to\xerces-c\source
cmake --build . --config Debug
ctest -V -C Debug -j 4
cmake --build . --config Debug --target install 

Note Note that different UNIX platforms use different system environment variables 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_FALLBACK_LIBRARY_PATH, and on HP-UX it is SHLIB_PATH.
Note Note that Windows is different from the UNIX platforms in the way it finds shared libraries at run time. While UNIX platforms may use the LD_LIBRARY_PATH environment variable, Windows uses the PATH environment variable if the library is not in the same directory as the executable.

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 Xerces-C++ 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 xerces-c-3.3.0 directory. The build part is performed by invoking make.

Besides the standard configure options which you can view by running configure --help, Xerces-C++ 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 

XMLCh type (UTF-16 character type):

Option  Description 
--enable-xmlch-char16_t  use char16_t (requires a C++11 compiler) 
--enable-xmlch-uint16_t  use uint16_t from <cstdint> or <stdint.h>, or another unsigned 16-bit type such as unsigned short if the standard types are unavailable 
--enable-xmlch-wchar_t  use wchar_t (Windows only) 

Thread support is enabled by default and can be disabled with the --disable-threads option. If disabled, it will not be possible to select a mutex manager other than nothreads. If enabled, one of the following mutex managers may be selected:

Option  Description 
--enable-mutexmgr-standard  Use Standard C++ mutex (requires a C++11 compiler) 
--enable-mutexmgr-posix  Use POSIX threads (pthreads) mutex (only on UNIX and Cygwin) 
--enable-mutexmgr-windows  Use Windows threads mutex (Windows and MinGW only) 
--enable-mutexmgr-nothreads  Use dummy implementation (default if threading is disabled) 

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 Xerces-C++ 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 Xerces-C++, 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 xerces-c-3.3.0 directory builds Xerces-C++ 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 xerces-c-3.3.0/src.

If you would like to build the tests and run the automated test suite, run make check from the xerces-c-3.3.0 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
(for xlC v11-v13, libxerces_c_la_LDFLAGS is not needed, but CXXFLAGS=-rtti is needed otherwise RTTI is disabled by default) 
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
(for xlC v11-v13, libxerces_c_la_LDFLAGS is not needed, but CXXFLAGS="-q64 -rtti" is needed otherwise RTTI is disabled by default) 
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 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 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.



Copyright © 1999-2017 The Apache Software Foundation. All Rights Reserved.