Installing XSD/e with build2
The latest XSD/e
compiler and runtime library (libxsde) 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/e compiler and XSD/e runtime library.
Instead of building XSD/e from source you could use binary distribution packages provided for a number of mainstream platforms.
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/e is cross-compiled, use your host development platform to select the instructions to follow. Then build the XSD/e compiler for the host and the XSD/e 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/e compiler, and use MinGW GCC to build the XSD/e 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/e 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/e 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/e Compiler
The recommended way to build the XSD/e 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 xsde-build $ cd xsde-build $ bpkg create -d xsde-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 xsde-gcc-N
To build:
$ bpkg build xsde@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 xsde@https://pkg.cppget.org/1/stable ?sys:libxerces-c
To test:
$ bpkg test xsde
To install:
$ bpkg install xsde $ which xsde $ xsde --version
To uninstall:
$ bpkg uninstall xsde
To upgrade:
$ bpkg fetch $ bpkg status $ bpkg uninstall xsde $ bpkg build --upgrade --recursive $ bpkg install xsde
See Package
Consumption for more information on these bpkg
commands.
1.3 Building XSD/e Runtime Library
While it doesn't matter much which C++ compiler you use to build the
XSD/e compiler, when it comes to the XSD/e runtime library
(libxsde), it's a good idea to use the same C++ compiler and
settings as for the application in which you will be using XSD/e. In this
section we will use GCC as an example.
First create the build configuration (replace N with the GCC major version):
$ cd xsde-build $ bpkg create -d libxsde-gcc-N cc \ config.cxx=g++ \ config.cc.coptions=-O3 \ config.install.root=/usr/local \ config.install.sudo=sudo $ cd libxsde-gcc-N
To build:
$ bpkg add https://pkg.cppget.org/1/stable $ bpkg fetch $ bpkg build libxsde
The runtime library provides a number of config.libxsde.*
configuration variables that allow you to enable/disable and fine-tune
certain features. See the build/root.build file inside the
libxsde package for details.
By default libxsde uses a bundled copy of the Expat library
but it's possible to configure it to use external Expat:
$ bpkg build config.libxsde.external_expat=true -- libxsde
Or to use the system-installed version of Expat:
$ bpkg build config.libxsde.external_expat=true -- libxsde \ ?sys:libexpat
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 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/xsde (replace N with the
Clang major version):
$ bpkg create -d libxsde-clang-N-libc++-debug cc \ config.cxx=clang++ \ config.cc.coptions=-g \ config.cxx.coptions=-stdlib=libc++ \ config.install.root=$HOME/install/xsde
After the installation the XSD/e runtime headers (and XML parser headers,
if applicable) will be in ~/install/xsde/include and libraries
– in ~/install/xsde/lib. To use this build simply add the
corresponding -I and -L options to your project's
build configuration.
2 Windows
The overall plan is as follows: first install the build2
toolchain then use it to build and install the XSD/e 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/e Compiler
Open a command prompt, then run:
> set "PATH=C:\build2\bin;%PATH%" > C: > md \xsde-build > cd \xsde-build
Create the build configuration:
> bpkg create -d xsde-msvc cc^ config.cxx=cl^ config.cc.coptions=/O2^ config.install.root=C:\xsde > cd xsde-msvc
To build:
> bpkg build xsde@https://pkg.cppget.org/1/stable
To test:
> bpkg test xsde
To install:
> bpkg install xsde > C:\xsde\bin\xsde.exe --version
After the installation, the XSD/e compiler binary can be found in
C:\xsde\bin\. You can either add this directory to your
PATH or invoke the compiler using the absolute path.
Note that copying xsde.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 xsde
To upgrade:
> bpkg fetch > bpkg status > bpkg uninstall xsde > bpkg build --upgrade --recursive > bpkg install xsde
See Package
Consumption for more information on these bpkg
commands.
2.3 Building XSD/e Runtime Library
When it comes to the XSD/e runtime library (libxsde), it's a
good idea to use the same C++ compiler and settings as for the application
in which you will be using XSD/e. 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,
libxsde-msvc-release-64) and installation directories (for
example, C:\xsde\release-64\) to avoid clashes.
In the Visual Studio command prompt run:
> set "PATH=C:\build2\bin;%PATH%" > C: > cd \xsde-build
Create the Release and Debug build configurations:
> bpkg create -d libxsde-msvc-release cc^ config.cxx=cl^ "config.cc.coptions=/O2 /MD"^ config.install.root=C:\xsde\release > bpkg create -d libxsde-msvc-debug cc^ config.cxx=cl^ "config.cc.coptions=/Od /MDd /Zi"^ config.cc.loptions=/DEBUG:FULL^ config.install.root=C:\xsde\debug
If you wish to build a static library with debug information, use this Debug configuration instead:
> bpkg create -d libxsde-msvc-debug cc^ config.cxx=cl^ "config.cc.coptions=/Od /MDd /Z7"^ config.install.root=C:\xsde\debug
To build, perform the following steps for each build configuration. Here
replace XXX either with debug or
release:
> cd libxsde-msvc-XXX > bpkg add https://pkg.cppget.org/1/stable > bpkg fetch > bpkg build libxsde
The runtime library provides a number of config.libxsde.*
configuration variables that allow you to enable/disable and fine-tune
certain features. See the build/root.build file inside the
libxsde package for details.
By default libxsde uses a bundled copy of the Expat library
but it's possible to configure it to use external Expat:
> bpkg build config.libxsde.external_expat=true -- libxsde
Or to use the system-installed version of Expat:
> bpkg build config.libxsde.external_expat=true -- libxsde^ ?sys:libexpat
To install:
> bpkg install --all --recursive
The result (both shared and static libraries) will be in the
C:\xsde\XXX\ directories with headers in the
include\ subdirectory, static libraries and DLL import stubs
(.lib) in lib\ and DLLs in bin\.
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/e 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/e Compiler
First create the build configuration (replace N with the Clang major version):
$ mkdir xsde-build $ cd xsde-build $ bpkg create -d xsde-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 xsde-clang-N
To build:
$ bpkg build xsde@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 xsde@https://pkg.cppget.org/1/stable ?sys:libxerces-c
To test:
$ bpkg test xsde
To install:
$ bpkg install xsde $ which xsde $ xsde --version
To uninstall:
$ bpkg uninstall xsde
To upgrade:
$ bpkg fetch $ bpkg status $ bpkg uninstall xsde $ bpkg build --upgrade --recursive $ bpkg install xsde
See Package
Consumption for more information on these bpkg
commands.
3.3 Building XSD/e Runtime Library
When it comes to the XSD/e runtime library (libxsde), it's a
good idea to use the same C++ compiler and settings as for the application
in which you will be using XSD/e. In this section we will use Apple Clang as
an example.
First create the build configuration (replace N with the Clang major version):
$ cd xsde-build $ bpkg create -d libxsde-clang-N cc \ config.cxx=clang++ \ config.cc.coptions=-O3 \ config.install.root=/usr/local \ config.install.sudo=sudo $ cd libxsde-clang-N
To build:
$ bpkg add https://pkg.cppget.org/1/stable $ bpkg fetch $ bpkg build libxsde
The runtime library provides a number of config.libxsde.*
configuration variables that allow you to enable/disable and fine-tune
certain features. See the build/root.build file inside the
libxsde package for details.
By default libxsde uses a bundled copy of the Expat library
but it's possible to configure it to use external Expat:
$ bpkg build config.libxsde.external_expat=true -- libxsde
Or to use the system-installed version of Expat:
$ bpkg build config.libxsde.external_expat=true -- libxsde \ ?sys:libexpat
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/xsde (replace N with the Clang major
version):
$ bpkg create -d libxsde-clang-N-debug cc \ config.cxx=clang++ \ config.cc.coptions=-g \ config.install.root=$HOME/install/xsde
After the installation the XSD/e runtime headers (and XML parser headers,
if applicable) will be in ~/install/xsde/include and libraries
– in ~/install/xsde/lib. To use this build simply add the
corresponding -I and -L options to your project's
build configuration.
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/e
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/e Compiler
To build and install the XSD/e compiler without network access, follow
the normal instructions for your platform from one of the above sections
until the bpkg build command:
$ bpkg build xsde@https://pkg.cppget.org/1/stable
Instead of executing this command (which will attempt to download the
xsde package and all its dependencies over the network), on a
machine with network access go with your web browser to the xsde package page and
navigate to the desired xsde package version page (use the
latest version if unsure).
On the xsde package version page you will find the download
link to the xsde compiler package
(xsde-X.Y.Z.tar.gz) as well as the Depends section with links
to the libxsde-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 libxsde-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 xsde-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 xsde-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 xsde-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/e.
4.3 Building XSD/e Runtime Library
To build and install the XSD/e 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 libxsde
Instead of executing these commands (which will attempt to download the
XSD/e runtime library over the network), follow the same
procedure as for the XSD/e compiler: download the archive of the runtime
library (as well as its dependency if you wish to use external Expat) and
then build those archives.
For example, if you need just libxsde, go to the libxsde package page,
pick the same versions as the XSD/e compiler, and download its archive. At
the end of this exercise you should have the following file in your build
configuration directory:
libxsde-X.Y.Z.tar.gz
Now instead of the above bpkg
add/fetch/build commands execute:
$ bpkg build libxsde-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/e.