The macOS builds run natively on x64 and arm64 machines, and apart from the usual Command Line Tools (provided by Apple) and xpm, the host machine has no other special requirements.
The prerequisites are:
npm (shipped with Node.js; installed via nvm)xpm (installed via npm)Some build scripts may require Python 3. On modern systems, it should be available in the standard Apple distribution. If not, install it from Python downloads.
For development builds, the procedure can be executed on a recent macOS version (currently tested up to 14.6).
For production builds it is recommended to use a slightly older version, for example 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 tested and found to be functional (although VirtualBox was not as stable as Parallels).
The build scripts were tested on:
If you are confident in your knowledge and prefer a shortcut, copy and paste the following script into a terminal (otherwise, perform the steps one by one).
caution
For security reasons, conscientious users should first check the content of the file before executing it.
mkdir -pv "${HOME}/Downloads/"
curl --output "${HOME}/Downloads/install-nvm-node-npm-xpm.sh" https://raw.githubusercontent.com/xpack/assets/master/scripts/install-nvm-node-npm-xpm.sh
cat "${HOME}/Downloads/install-nvm-node-npm-xpm.sh"
bash "${HOME}/Downloads/install-nvm-node-npm-xpm.sh"
exit
This script will install nvm (the Node Version Manager), node, npm and xpm.
info
To activate nvm automatically, the script adds several lines to the shell initialisation script.
info
When running on macOS this script also installs the Command Line Tools.
node/npmnpm is included with Node.js and is required to install xpm.
For full details on installing Node.js, please refer to the xPack prerequisites page.
caution
Ensure you do not install npm with administrative rights, such as via a system package manager. Instead, use nvm as instructed to avoid permission-related issues.
xpm is a portable Node.js command line application.
If you followed the Quick instructions, it is already installed.
Otherwise, to install it, follow the steps in the xpm install page.
If you are confident in your knowledge and prefer a shortcut, issue the following command:"
npm install --global xpm@latest
The macOS compiler and other development tools are included in a separate Xcode add-on. The best place to obtain it is from the Apple Developer Downloads site, although this might require enrolling in the developer program (free of charge).
If you followed the Quick instructions, CLT should be already installed.
Otherwise, the recommended method is to install the Command Line Tools separately via the command line:
% xcode-select --install
% xcode-select -p
/Library/Developer/CommandLineTools
$ gcc --version
Apple clang version 15.0.0 (clang-1500.3.9.4)
Target: x86_64-apple-darwin23.6.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin
info
Xcode alone includes the compiler in the Xcode.app folder, which may vary in different versions; for a stable configuration it is necessary to install the CommandLineTools package.
No macOS DockerDue 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 slowly, consumes a lot of memory, and is not reliable, so it is not recommended to run the Linux/Windows builds on macOS.
The GNU/Linux build scripts use a set of Docker images based on older and more conservative distributions to avoid issues when running the executables on older systems.
Any x86_64/aarch64/armhf GNU/Linux distribution capable of running Docker should suffice; a physical machine is not necessary, as virtual machines are perfectly adequate. For optimal results, allocate 3-4 cores and 8-12 GB of RAM.
The XBB v5.0.0 Docker images are built on Ubuntu 18 LTS for both x64 and Arm GNU/Linux, ensuring the resulting binaries can run on any system based on GLIBC >= 2.27.
info
Building Arm binaries necessitates an Arm machine. A Raspberry Pi 4 with 8GB of RAM, paired with a Samsung Portable T7 USB 3 SSD, is an excellent solution. A Raspberry Pi 5 with an NVME SSD is even better.
info
Although Arm 32-bit binaries can be built inside Docker containers running on AArch64 machines, it is still recommended to use a 32-bit OS to avoid issues caused by the differences between armv7 and armv8.
The prerequisites are:
curl (installed via the system package manager)git (installed via the system package manager)docker (preferably a recent one, installed from docker.com)npm (shipped with Node.js; installed via nvm, not the system package manager)xpm (installed via npm)The build scripts perform most of the actual work in a Docker container, and apart from curl, git docker and xpm, the host machine has no other special requirements.
The build scripts were tested on:
Install curl & git using the system package manager.
For example on Ubuntu and Debian-derived distributions, use:
sudo apt-get install --yes curl git
A recent Docker is necessary. it can probably be used, but it is generally recommended to update to the latest stable version available directly from docker.com.
For any GNU/Linux distribution, follow the specific instructions.
For example, the steps to install Docker on a modern Ubuntu system are essentially:
sudo apt-get update && \
\
sudo apt-get install ca-certificates curl gnupg && \
\
sudo mkdir -m 0755 -p /etc/apt/keyrings && \
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \
\
echo \
"deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
"$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null && \
\
sudo apt-get update && \
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
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!
...
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 commands are for Ubuntu and the Debian family. For other distributions, the last line may differ. For example, for Arch Linux use:
To make these changes effective, it is preferable to 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!
...
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 upon first usage. The images are reasonably large, currently below 1 GB.
More details can be found on each script's documentation page.
npm/xpm Quick instructionsIf you are confident in your knowledge and prefer a shortcut, copy and paste the following script into a terminal (otherwise, perform the steps one by one).
caution
For security reasons, conscientious users should first check the content of the file before executing it.
mkdir -pv "${HOME}/Downloads/"
curl --output "${HOME}/Downloads/install-nvm-node-npm-xpm.sh" https://raw.githubusercontent.com/xpack/assets/master/scripts/install-nvm-node-npm-xpm.sh
cat "${HOME}/Downloads/install-nvm-node-npm-xpm.sh"
bash "${HOME}/Downloads/install-nvm-node-npm-xpm.sh"
exit
This script will install nvm (the Node Version Manager), node, npm and xpm.
info
To activate nvm automatically, the script adds several lines to the shell initialisation script.
npm is included with Node.js and is required to install xpm.
For full details on installing Node.js, please refer to the xPack prerequisites page.
caution
Ensure you do not install npm with administrative rights, such as via a system package manager. Instead, use nvm as instructed to avoid permission-related issues.
xpm is a portable Node.js command line application.
If you followed the Quick instructions, it is already installed.
Otherwise, to install it, follow the steps in the xpm install page.
If you are confident in your knowledge and prefer a shortcut, issue the following command:"
npm install --global xpm@latest
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4