Prerequisites for building xPack binaries

Edit

The latest generation of the build scripts use the xPack Build Box (XBB), a set of Docker containers (separate 32/64-bit containers) based on older and more conservative distributions, to avoid problems when attempting to run the executables on older versions.

The XBB v5.0.0 uses Ubuntu 18 LTS for both Intel and Arm GNU/Linux.

Note: Building Arm binaries requires an Arm machine. A Raspberry Pi 4 8GB equipped with a Samsung Portable T7 USB 3 SSD is a good solution.

Note: Although Arm 32 binaries can be build inside Docker containers running on AArch64 machines.

The Windows binaries are generated on the same Docker Intel GNU/Linux container, using mingw-w64.

GNU/Linux

Any GNU/Linux distribution that is able to run Docker should be ok; it is not necessary to have a physical machine, virtual machines are perfectly fine. For better results, dedicate 3-4 cores and 8-12 GB of RAM.

The procedure was tested on:

Ubuntu 18.04 LTS, running on an Intel NUC NUC8i7BEH with 32 GB of RAM
Debian 10 (buster), running on an AMD Ryzen 5600G with 32 GB of RAM
Raspberry Pi OS 64-bit, running on a Raspberry Pi 4 with 8 GB of RAM
Raspberry Pi OS 32-bit, running on a Raspberry Pi 4 with 4 GB of RAM

The build scripts do most of the actual work in the Docker container, and, apart from Docker, the host machine has no other special requirements.

Install Docker

For any GNU/Linux distribution, follow the specific instructions.

For example, the steps to install Docker on a modern 64-bit Ubuntu system are basically:

sudo apt-get update

sudo apt-get install apt-transport-https ca-certificates  curl software-properties-common

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

version_name=$(lsb_release -cs)
sudo add-apt-repository  "deb [arch=amd64] https://download.docker.com/linux/ubuntu  ${version_name} stable"

sudo apt-get update
sudo apt-get -y install docker-ce

Warning: Please note that the above lines get the current version name via lsb_release and assumes that a folder with that name is available at https://download.docker.com/linux/ubuntu/dists/. This is true for most versions, except the very latest one, which might not yet be made available by the Docker team. In this case set the version_name manually to the previous version. You can also do this by manually editing the /etc/apt/sources.list file.

To check if the install is functional, run the Hello World image, for the moment as sudo:

$ sudo docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b04784fba78d: Pull complete
Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
...

Configure Docker to run as a regular user

To allow Docker to run as a regular user, you need to be a member of the docker group.

sudo groupadd docker
sudo gpasswd -a ${USER} docker
sudo service docker restart

The above script are for Ubuntu and the Debian family. For other distributions, the last line may differ, for example for Arch Linux use:

systemctl restart docker

To make these changes effective, preferably reboot the machine.

To check if the configuration change is functional, run the same Hello World image without sudo:

$ docker run hello-world

Hello from Docker!
...

macOS

For development build, the procedure is executed on a recent macOS version (currently 12.6).

For production builds it is recommended to use a slightly older version. macOS 10.13 is a good compromise.

It is not mandatory to have a physical macOS 10.13 machine, a virtual machine is also perfectly fine. Both Parallels and VirtualBox were checked and were functional (although VirtualBox was not as stable as Parallels).

Install the Command Line Tools

The macOS compiler and other development tools are packed in a separate Xcode add-on. The best place to get it is from the Developer site, although this might require enrolling to the developer program (free of charge).

The recommended way is to install the Command Line Tools separately via a command line:

$ xcode-select --install
$ xcode-select -p
/Library/Developer/CommandLineTools
$ gcc --version
Configured with: --prefix=/Library/Developer/CommandLineTools/usr --with-gxx-include-dir=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/4.2.1
Apple clang version 13.0.0 (clang-1300.0.29.3)
Target: x86_64-apple-darwin20.6.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin

Note: Xcode alone includes the compiler in the Xcode.app folder, which may very in different versions; for a stable configuration it is required to install the CommandLineTools package.

macOS Docker

Due to the specifics of macOS, Docker cannot run natively; instead, it uses a GNU/Linux virtual machine running in Apple HyperKit (Apple’s virtualization framework), and a file system compatibility layer.

The end result is that Docker runs slow, consumes a lot of memory, and is not reliable, so it is not recommended to run the Linux/Windows builds on macOS.

Docker images

The Docker images are available from Docker Hub. They were build using the Dockerfiles available from XBB (xPack Build Box).

If not already loaded, Docker will load the images at first usage. The images are reasonably large, currently below 1 GB.

More details in each script documentation page.

Comments on the content of this page that might be useful for other readers are welcomed here. For question and general support, please use GitHub Discussions.