User's Guide
Supported platforms
Generally, xpm binaries packages are available for the following platforms:
- x64 Windows
- x64 GNU/Linux
- aarch64 GNU/Linux
- x64 macOS
- arm64 macOS (Apple Silicon)
Starting with 2022, support for macOS Apple Silicon was added; 32-bit support for Windows and x64 GNU/Linux was discontinued. In 2025 support for arm 32-bit was also discontinued.
XBB supports creating binaries for all these platforms.
For the detailed supported versions, please check the specific release page.
GNU/Linux Arm binaries
Support for arm64v8
& arm32v7
binaries was added in v3.1, in early 2020.
Beginning with version 6.0.0 in 2025, support for arm32v7
was discontinued.
The supported architectures are:
arm64v8
- the ARMv8 64-bit architecture aarch64
macOS Apple Silicon
Support for Apple Silicon was added in v3.4, in late 2021.
Docker specifics
As with any Docker builds, the XBB builds run completely inside Docker containers, which start afresh each time they are instantiated.
To pass the folder with the build scripts in and the results out,
it is usual to use a Work
folder, for example:
$ docker run -it --volume "${HOME}/Work:/Host/Work" ilegeul/debian:amd64-10-xbb-v6.0.0
root@bc7071f2c78a:/# ls -l Host/Work/xpacks
total 8
drwxrwxr-x 11 node node 4096 Mar 24 15:39 openocd-xpack.git
drwxrwxr-x 17 node node 4096 Mar 27 14:15 xbb-helper-xpack.git
In this simple configuration, the builds run with root permissions; with more elaborate configurations it is possible to start the Docker containers with user rights, but they are beyond the scope of this document.
xpm run
For convenience, the new build scripts are xPacks, with multiple build configurations, for all supported platforms, and all actions are defined uniformly as xpm actions.
xpm actions are named sequences of shell commands, that are executed in order when the action is invoked.
For example:
"actions": {
"deep-clean": [
"rm -rf build xpacks node_modules package-lock.json",
"rm -rf ${HOME}/Work/{{ properties.appLcName }}-[0-9]*-*"
],
"install": [
"npm install",
"xpm install"
],
"link-deps": [
"xpm link @xpack-dev-tools/xbb-helper"
],
"git-pull-helper": [
"git -C ${HOME}/Work/xpacks/xbb-helper-xpack.git pull"
],
"git-log": "git log --pretty='%cd * %h %s' --date=short",
"test-xpm": "bash {{ properties.dbg }} scripts/test.sh --xpm",
"build-native": "bash {{ properties.dbg }} scripts/build.sh",
"build-native-develop": "bash {{ properties.dbg }} scripts/build.sh --develop",
"build-native-win": "bash {{ properties.dbg }} scripts/build.sh --windows",
"build-native-win-develop": "bash {{ properties.dbg }} scripts/build.sh --develop --windows"
},
To invoke these actions, the xpm run
command is used.
The helper project
Since there are lots of common files between projects, they were collected into a helper project.
The helper project is a
source xpm package (@xpack-dev-tools/xbb-helper
), which can be installed
as a dependency with:
cd my-project-xpack.git
xpm install --save-dev @xpack-dev-tools/xbb-helper@latest
The result is a folder like:
$ tree -l -L 2 xpacks/
xpacks/
└── xpack-dev-tools-xbb-helper -> /home/ilg/.local/xPacks/@xpack-dev-tools/xbb-helper/1.4.7
├── CHANGELOG.md
├── config
├── dependencies
├── developer
├── extras
├── github-actions
├── LICENSE
├── maintainer
├── package.json
├── patches
├── pkgconfig
├── README.md
├── scripts
├── templates
├── tests
└── travis
13 directories, 4 files
There are many files in the helper, for various use cases. The build scripts
directly include files from the scripts
and dependencies
folders.
Types of builds
From the perspective of the desired outcome, there are two types of builds:
- Local/native builds, intended for development and execution on the local machine
- Distribution builds, designed for xPack binary distributions and operation on production machines
Ideally, the production machines should be CI/CD runners, such as GitHub. However, some builds, like toolchains, take too long and exceed the time limits. In these cases, separate machines running self-hosted runners should be utilised.
The primary use case for XBB is distribution builds, but it can also be used for native builds.
Native builds with all tools from the host machine
In this case all build tools are expected to be available on the host machine. The list of these dependency depends on the distribution and is outside the scope of this project, which recommends the next use Docker use case, presented below.
xpm run install
xpm run build-native
The first command is used to install the helper project; the second command runs the build.
These commands run the same on both GNU/Linux and macOS.
To generate the Windows binaries on GNU/Linux, there is a separate build action:
xpm run install
xpm run build-native-win
Native builds with the major tools coming from xpm packages
Sometimes the native tools available on the host machine may be too old for building modern packages.
A simple solution is to install the main tools as binary xpm packages. The selection of tools depends on the target platform.
The existing projects include separate build configurations for multiple platforms (darwin-x64, darwin-arm64, linux-x64, linux-arm64, win32-x64).
For example, to build the Intel GNU/Linux binaries, use:
xpm run install
xpm run install --config linux-x64
xpm run build --config linux-x64
Docker builds with tools coming from xpm packages
An even more reproducible configuration can be achieved by using Docker containers, with the base system tools.
xpm run install
xpm run docker-prepare --config linux-x64
xpm run docker-build --config linux-x64
Writable helper scripts
For normal builds, the helper project, which is a source xpm packages, is downloaded and marked as read-only, to prevent damaging it.
For development purposes it might be necessary to update it; the xpm solution (inspired by the npm solution) is to download the helper repository into a separate location, and link it to the current project.
This is done in two steps, first a link from the central store to the helper repo is created. This ensures that multiple projects can conveniently use the writable helper.
rm -rf ~/Work/xpacks/xbb-helper-xpack.git && \
mkdir -p ~/Work/xpacks && \
git clone \
--branch xpack-develop \
https://github.com/xpack-dev-tools/xbb-helper-xpack.git \
~/Work/xpacks/xbb-helper-xpack.git && \
xpm link -C ~/Work/xpacks/xbb-helper-xpack.git
The result is a link like:
$ ls -lA ~/.local/xPacks/@xpack-dev-tools/xbb-helper
total 4
dr-xr-xr-x 14 ilg ilg 4096 Mar 24 17:38 1.4.7
lrwxrwxrwx 1 ilg ilg 42 Mar 27 17:16 .link -> /home/ilg/Work/xpacks/xbb-helper-xpack.git
In other words, in the folder where versioned releases are installed, a special hidden symbolic link is created, pointing to the location where the repo was cloned.
In the second step, a link from the build project to the central store is created.
xpm link @xpack-dev-tools/xbb-helper -C my-project-xpack.git
The result is a link like:
$ cd my-project-xpack.git
$ ls -l xpacks/
total 0
lrwxrwxrwx 1 ilg ilg 57 Mar 27 17:21 xpack-dev-tools-xbb-helper -> /home/ilg/.local/xPacks/@xpack-dev-tools/xbb-helper/.link
In other words, the xpack-dev-tools-xbb-helper
link, instead of pointing
to a version, like /home/ilg/.local/xPacks/@xpack-dev-tools/xbb-helper/1.4.7
,
now points to the .link
, which points to the cloned repo.
This double link mechanism allows multiple projects to refer to the writable folder, and allow this folder to be easily moved to another location without having to update all projects that reference it.
For details on the actual usage, please check the build projects.
How to use the XBB tools
Both on GNU/Linux and macOS, the XBB tools are installed as binary
xpm development dependencies in xpacks/.bin
and are fully distinct from
the system tools.
To access them, the application should update the PATH
to prefer
the xpacks/.bin
path.
Common scripts
For consistency between projects, common scripts were grouped in the helper project.
After installing it with xpm install
, the scripts are available
from xpacks/xpack-dev-tools-xbb-helper
.
There are many scripts in this location; the main ones are in the
scripts
folder. The scripts to build various dependencies are in
the dependencies
folder.
The pkg-config-verbose
script
While running the configuration step, it is sometimes useful to trace
how pkg-config
identifies resources to be used during the build.
The standard pkg-config
does not have an option to increase verbosity.
The workaround is to use a separate script that displays the received command and the response on the stderr stream.
This script is not specific to XBB, and can be used with any build.
No more TeX
Starting with v3.4, support for building the manuals was dropped, and the TeX tools are no longer needed.
End of support for Linux distributions
To help decide what base version to use, and how long to keep support for it, a list of main Linux distributions was compiled, with the GLIBC versions: