Skip to main content

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)
info

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: