Installing XSD with build2
The latest XSD
compiler and runtime library (libxsd) as well as their
dependencies (for example, Xerces-C++) can now be built and installed on all
the major platforms (Linux, Windows, Mac OS, and FreeBSD) from source
packages available in the build2 cppget.org
repository (or, alternatively, from pre-downloaded package archives if installing offline). See the current CI build status for
the XSD compiler and XSD runtime library.
Instead of building XSD from source you could use binary
distribution packages provided for a number of mainstream platforms.
Note also that most major Linux distributions (Debian, Ubuntu, Fedora, RHEL)
as well as add-on package managers (for example, Homebrew) have XSD packaged
and available from their official repositories, though it may not be the
most recent version (on some, the package and/or the XSD compiler binary is
called xsdcxx instead of xsd).
This installation method uses the build2 package manager
(bpkg) which has a uniform interface across all the platforms
and compilers. It significantly simplifies the initial build as well as the
ongoing maintenance (upgrades/downgrades, etc). Note also that your own
projects don't have to use build2 to benefit from this
installation method. But if you would like to learn more, see The
build2 Toolchain Introduction.
If the application in which you will be using XSD is cross-compiled, use your host development platform to select the instructions to follow. Then build the XSD compiler for the host and the XSD runtime library for the target. For example, if you would like to cross-compile from Linux to Windows using the MinGW GCC cross-compiler, then you would follow the UNIX-like (Linux, FreeBSD, etc) instructions, use your host's native C++ compiler to build the XSD compiler, and use MinGW GCC to build the XSD runtime library.
Note also that in build2 no special steps are required to
cross-compile. Simply specifying the correct compiler to use should be
sufficient in most cases. Continuing with the above example, if the MinGW
GCC cross-compiler binary is called x86_64-w64-mingw32-g++,
then all you have to do is to pass
config.cxx=x86_64-w64-mingw32-g++ when creating the build
configuration for the XSD runtime library.
1 UNIX-like (Linux, FreeBSD, etc)
The overall plan is as follows: first install the build2
toolchain then use it to build and install the XSD compiler and the runtime
library.
In this section we use /usr/local as the installation
directory but this can be changed by adjusting the relevant configuration
variables. Note also that with build2 everything can be cleanly
uninstalled at any moment as long as you keep the build configurations that
were used for the installation.
1.1 Installing build2
Build the latest build2 toolchain by following the UNIX (Linux, Mac OS,
FreeBSD) installation instructions.
1.2 Building XSD Compiler
The recommended way to build the XSD compiler on UNIX-like platforms is to use the system-default C++ compiler. In this section we will use GCC which is the default on most Linux distributions.
First create the build configuration (replace N with the GCC major version):
$ mkdir xsd-build $ cd xsd-build $ bpkg create -d xsd-gcc-N cc \ config.cxx=g++ \ config.cc.coptions=-O3 \ config.bin.rpath=/usr/local/lib \ config.install.root=/usr/local \ config.install.sudo=sudo $ cd xsd-gcc-N
To build:
$ bpkg build xsd@https://pkg.cppget.org/1/stable
If you would prefer to use the system-installed version of Xerces-C++
instead of building it from source, adjust the above build
command as follows:
$ bpkg build xsd@https://pkg.cppget.org/1/stable ?sys:libxerces-c
To test:
$ bpkg test xsd
To install:
$ bpkg install xsd $ which xsd $ xsd --version
To uninstall:
$ bpkg uninstall xsd
To upgrade:
$ bpkg fetch $ bpkg status $ bpkg uninstall xsd $ bpkg build --upgrade --recursive $ bpkg install xsd
See Package
Consumption for more information on these bpkg
commands.
1.3 Building XSD Runtime Library
While it doesn't matter much which C++ compiler you use to build the XSD
compiler, when it comes to the XSD runtime library (libxsd),
it's a good idea to use the same C++ compiler and settings as for the
application in which you will be using XSD. In this section we will use GCC
as an example.
First create the build configuration (replace N with the GCC major version):
$ cd xsd-build $ bpkg create -d libxsd-gcc-N cc \ config.cxx=g++ \ config.cc.coptions=-O3 \ config.install.root=/usr/local \ config.install.sudo=sudo $ cd libxsd-gcc-N
XSD requires an underlying XML parser library. The C++/Tree mapping
can only use Xerces-C++ while the C++/Parser
mapping can use Xerces-C++ or Expat. The XSD runtime itself (which is
header-only) does not depend on either library but you will need to link one
of them to your application. You have the option to build and install one
(or both) of the XML parsers together with libxsd or use a
system-installed version. In the latter case, simply omit the relevant
command lines from the below steps.
To build:
$ bpkg add https://pkg.cppget.org/1/stable $ bpkg fetch $ bpkg build libxerces-c $ bpkg build libexpat $ bpkg build libxsd
To install:
$ bpkg install --all --recursive
To uninstall:
$ bpkg uninstall --all --recursive
To upgrade:
$ bpkg fetch $ bpkg status $ bpkg uninstall --all --recursive $ bpkg build --upgrade --recursive $ bpkg install --all --recursive
Note also that you can create as many builds of the runtime library (and
XML parser, if applicable) as you need: different compilers, debug/release,
32/64-bit, etc. Simply create another build configuration with the desired
settings and repeat the above steps. For such development builds you will
also probably want to adjust the installation location to somewhere private.
For, example, this is how we can create a debug build that uses Clang with
the libc++ runtime and install it into
~/install/xsd (replace N with the Clang major
version):
$ bpkg create -d libxsd-clang-N-libc++-debug cc \ config.cxx=clang++ \ config.cc.coptions=-g \ config.cxx.coptions=-stdlib=libc++ \ config.install.root=$HOME/install/xsd
After the installation the XSD runtime headers (and XML parser headers,
if applicable) will be in ~/install/xsd/include and libraries
– in ~/install/xsd/lib. To use this build simply add the
corresponding -I and -L options to your project's
build configuration. Note that libxsd is header-only.
2 Windows
The overall plan is as follows: first install the build2
toolchain then use it to build and install the XSD compiler and the runtime
library. In this section we will use MSVC as the C++ compiler but Clang and
MinGW GCC can be used as well.
2.1 Installing build2
Build the latest build2 toolchain by following the Windows with MSVC
installation instructions.
Note: if your organization's network security breaks the installation
process (often the case on Windows when trying to use curl),
then consider Installing Offline.
2.2 Building XSD Compiler
Open a command prompt, then run:
> set "PATH=C:\build2\bin;%PATH%" > C: > md \xsd-build > cd \xsd-build
Create the build configuration:
> bpkg create -d xsd-msvc cc^ config.cxx=cl^ config.cc.coptions=/O2^ config.install.root=C:\xsd > cd xsd-msvc
To build:
> bpkg build xsd@https://pkg.cppget.org/1/stable
To test:
> bpkg test xsd
To install:
> bpkg install xsd > C:\xsd\bin\xsd.exe --version
After the installation, the XSD compiler binary can be found in
C:\xsd\bin\. You can either add this directory to your
PATH or invoke the compiler using the absolute path.
Note that copying xsd.exe somewhere else is not going to
work unless you build a statically-linked version by adding
config.bin.lib=static when creating the build configuration
above.
To uninstall:
> bpkg uninstall xsd
To upgrade:
> bpkg fetch > bpkg status > bpkg uninstall xsd > bpkg build --upgrade --recursive > bpkg install xsd
See Package
Consumption for more information on these bpkg
commands.
2.3 Building XSD Runtime Library
When it comes to the XSD runtime library (libxsd), it's a
good idea to use the same C++ compiler and settings as for the application
in which you will be using XSD. The easiest way to accomplish this is by
starting a Visual Studio command prompt (for example, x86 or
x64) that corresponds to your application's build.
If you have multiple builds (for example, 32 and 64-bit), then repeat the
steps in this section for each of them. In this case you will also want to
include the build type into the configuration names (for example,
libxsd-msvc-release-64) and installation directories (for
example, C:\xsd\release-64\) to avoid clashes.
In the Visual Studio command prompt run:
> set "PATH=C:\build2\bin;%PATH%" > C: > cd \xsd-build
Create the Release and Debug build configurations:
> bpkg create -d libxsd-msvc-release cc^ config.cxx=cl^ "config.cc.coptions=/O2 /MD"^ config.install.root=C:\xsd\release > bpkg create -d libxsd-msvc-debug cc^ config.cxx=cl^ "config.cc.coptions=/Od /MDd /Zi"^ config.cc.loptions=/DEBUG:FULL^ config.install.root=C:\xsd\debug
If you wish to build a static library with debug information, use this Debug configuration instead:
> bpkg create -d libxsd-msvc-debug cc^ config.cxx=cl^ "config.cc.coptions=/Od /MDd /Z7"^ config.install.root=C:\xsd\debug
XSD requires an underlying XML parser library. The C++/Tree mapping
can only use Xerces-C++ while the C++/Parser
mapping can use Xerces-C++ or Expat. The XSD runtime itself (which is
header-only) does not depend on either library but you will need to link one
of them to your application. You have the option to build and install one
(or both) of the XML parsers together with libxsd or use an
existing build if you already have it. In the latter case, simply omit the
relevant command lines from the below steps.
To build, perform the following steps for each build configuration. Here
replace XXX either with debug or
release:
> cd libxsd-msvc-XXX > bpkg add https://pkg.cppget.org/1/stable > bpkg fetch > bpkg build libxerces-c > bpkg build libexpat > bpkg build libxsd
To install:
> bpkg install --all --recursive
The result (both shared and static libraries) will be in the
C:\xsd\XXX\ directories with headers in the
include\ subdirectory, static libraries and DLL import stubs
(.lib) in lib\ and DLLs in bin\. Note
that libxsd is header-only.
To uninstall:
> bpkg uninstall --all --recursive
To upgrade:
> bpkg fetch > bpkg status > bpkg uninstall --all --recursive > bpkg build --upgrade --recursive > bpkg install --all --recursive
3 Mac OS
The overall plan is as follows: first install the build2
toolchain then use it to build and install the XSD compiler and the runtime
library. In this section we will use Apple Clang (from Xcode or Command Line
Tools) as the C++ compiler but Homebrew GCC can be used as well.
As a first step, make sure you have Apple Clang:
$ clang++ --version
If it's not present, install it as part of the Command Line Tools:
$ xcode-select --install
In this section we use /usr/local as the installation
directory but this can be changed by adjusting the relevant configuration
variables. Note also that with build2 everything can be cleanly
uninstalled at any moment as long as you keep the build configurations that
were used for the installation.
3.1 Installing build2
Build the latest build2 toolchain by following the UNIX (Linux, Mac OS,
FreeBSD) installation instructions.
3.2 Building XSD Compiler
First create the build configuration (replace N with the Clang major version):
$ mkdir xsd-build $ cd xsd-build $ bpkg create -d xsd-clang-N cc \ config.cxx=clang++ \ config.cc.coptions=-O3 \ config.bin.rpath=/usr/local/lib \ config.install.root=/usr/local \ config.install.sudo=sudo $ cd xsd-clang-N
To build:
$ bpkg build xsd@https://pkg.cppget.org/1/stable
If you would prefer to use the system-installed version of Xerces-C++
instead of building it from source, adjust the above build
command as follows:
$ bpkg build xsd@https://pkg.cppget.org/1/stable ?sys:libxerces-c
To test:
$ bpkg test xsd
To install:
$ bpkg install xsd $ which xsd $ xsd --version
To uninstall:
$ bpkg uninstall xsd
To upgrade:
$ bpkg fetch $ bpkg status $ bpkg uninstall xsd $ bpkg build --upgrade --recursive $ bpkg install xsd
See Package
Consumption for more information on these bpkg
commands.
3.3 Building XSD Runtime Library
When it comes to the XSD runtime library (libxsd), it's a
good idea to use the same C++ compiler and settings as for the application
in which you will be using XSD. In this section we will use Apple Clang as
an example.
First create the build configuration (replace N with the Clang major version):
$ cd xsd-build $ bpkg create -d libxsd-clang-N cc \ config.cxx=clang++ \ config.cc.coptions=-O3 \ config.install.root=/usr/local \ config.install.sudo=sudo $ cd libxsd-clang-N
XSD requires an underlying XML parser library. The C++/Tree mapping
can only use Xerces-C++ while the C++/Parser
mapping can use Xerces-C++ or Expat. The XSD runtime itself (which is
header-only) does not depend on either library but you will need to link one
of them to your application. You have the option to build and install one
(or both) of the XML parsers together with libxsd or use a
system-installed version. In the latter case, simply omit the relevant
command lines from the below steps.
To build:
$ bpkg add https://pkg.cppget.org/1/stable $ bpkg fetch $ bpkg build libxerces-c $ bpkg build libexpat $ bpkg build libxsd
To install:
$ bpkg install --all --recursive
To uninstall:
$ bpkg uninstall --all --recursive
To upgrade:
$ bpkg fetch $ bpkg status $ bpkg uninstall --all --recursive $ bpkg build --upgrade --recursive $ bpkg install --all --recursive
Note also that you can create as many builds of the runtime library (and
XML parser, if applicable) as you need: different compilers, debug/release,
etc. Simply create another build configuration with the desired settings and
repeat the above steps. For such development builds you will also probably
want to adjust the installation location to somewhere private. For, example,
this is how we can create a debug build and install it into
~/install/xsd (replace N with the Clang major
version):
$ bpkg create -d libxsd-clang-N-debug cc \ config.cxx=clang++ \ config.cc.coptions=-g \ config.install.root=$HOME/install/xsd
After the installation the XSD runtime headers (and XML parser headers,
if applicable) will be in ~/install/xsd/include and libraries
– in ~/install/xsd/lib. To use this build simply add the
corresponding -I and -L options to your project's
build configuration. Note that libxsd is header-only.
4 Installing Offline
The installation process described in the previous sections requires
network access. If you need to install offline or if your organization's
network security breaks the installation process (often the case on Windows
when trying to use curl), then it's possible to install XSD
without the network access by pre-downloading and copying the required files
from another computer (or using tools compatible with your organization's
network security, such as the web browser). This section describes the
changes to the above installation process that are required to accomplish
this.
4.1 Installing build2
To install build2 without network access follow the
instructions in the How to install
offline FAQ entry.
4.2 Building XSD Compiler
To build and install the XSD compiler without network access, follow the
normal instructions for your platform from one of the above sections until
the bpkg build command:
$ bpkg build xsd@https://pkg.cppget.org/1/stable
Instead of executing this command (which will attempt to download the
xsd package and all its dependencies over the network), on a
machine with network access go with your web browser to the xsd package page and navigate
to the desired xsd package version page (use the latest version
if unsure).
On the xsd package version page you will find the download
link to the xsd compiler package
(xsd-X.Y.Z.tar.gz) as well as the Depends section with links to
the libxsd-frontend, libcutl, and
libxerces-c dependencies that it requires (you don't need the
optional cli dependency). Click on the version number next to
the dependency package name to go directly to its package version page.
There download libxsd-frontend-X.Y.Z.tar.gz,
libcutl-X.Y.Z.tar.gz, and
libxerces-c-X.Y.Z.tar.gz. Repeat this process for the
libxerces-c's dependencies libicuuc-X.Y.Z.tar.gz
and libicui18n-X.Y.Z.tar.gz (the X.Y.Z versions
for all these packages will most likely be different). At the end of this
exercise you should have the following files in your build configuration
directory:
libicuuc-X.Y.Z.tar.gz libicui18n-X.Y.Z.tar.gz libxerces-c-X.Y.Z.tar.gz libcutl-X.Y.Z.tar.gz libxsd-frontend-X.Y.Z.tar.gz xsd-X.Y.Z.tar.gz
ICU dependencies are only required on Linux. They can also be satisfied with system-installed versions.
Now instead of the above bpkg build command
execute:
$ bpkg build --configure-only libicuuc-X.Y.Z.tar.gz $ bpkg build --configure-only libicui18n-X.Y.Z.tar.gz $ bpkg build --configure-only libxerces-c-X.Y.Z.tar.gz $ bpkg build --configure-only libcutl-X.Y.Z.tar.gz $ bpkg build --configure-only libxsd-frontend-X.Y.Z.tar.gz $ bpkg build xsd-X.Y.Z.tar.gz
If you would prefer to use the system-installed version of Xerces-C++
instead of building it from source, you can skip downloading
libxerces-c-X.Y.Z.tar.gz and its dependencies and replace the
above command lines with:
$ bpkg build --configure-only sys:libxerces-c/* $ bpkg build --configure-only libcutl-X.Y.Z.tar.gz $ bpkg build --configure-only libxsd-frontend-X.Y.Z.tar.gz $ bpkg build xsd-X.Y.Z.tar.gz
Once this is done, you can continue with the normal instructions for your platform. Note, however, that the upgrade step will not be possible with this setup and you will need to repeat the above manual download steps to upgrade to a newer version of XSD.
4.3 Building XSD Runtime Library
To build and install the XSD runtime library without network access,
follow the normal instructions for your platform from one of the above
sections until the bpkg
add/fetch/build commands:
$ bpkg add https://pkg.cppget.org/1/stable $ bpkg fetch $ bpkg build libxerces-c ...
Instead of executing these commands (which will attempt to download the
XSD runtime library and the underlying XML parser library over
the network), follow the same procedure as for the XSD compiler: download
the archives of the libraries you are interested in as well as their
dependencies and then build those archives.
For example, if you need libxsd and
libxerces-c, go to the libxsd package and libxerces-c package
pages, pick the same versions as the XSD compiler for libxsd,
and download their archives and dependencies. At the end of this exercise
you should have the following files in your build configuration
directory:
libicuuc-X.Y.Z.tar.gz libicui18n-X.Y.Z.tar.gz libxerces-c-X.Y.Z.tar.gz libxsd-X.Y.Z.tar.gz
ICU dependencies are only required on Linux. They can also be satisfied with system-installed versions.
Now instead of the above bpkg
add/fetch/build commands execute:
$ bpkg build libicuuc-X.Y.Z.tar.gz $ bpkg build libicui18n-X.Y.Z.tar.gz $ bpkg build libxerces-c-X.Y.Z.tar.gz $ bpkg build libxsd-X.Y.Z.tar.gz
Once this is done, you can continue with the normal instructions for your platform. Note, however, that the upgrade step will not be possible with this setup and you will need to repeat the above manual download steps to upgrade to a newer version of XSD.