|
| 1 | +--- |
| 2 | + |
| 3 | +title: Prerequisites for building xPack Binary Development Tools |
| 4 | +description: The tools required to run the build scripts. |
| 5 | +keywords: |
| 6 | + - xpack |
| 7 | + - build |
| 8 | + - prerequisites |
| 9 | + |
| 10 | +date: 2017-07-06 20:55:00 +0300 |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +import Tabs from '@theme/Tabs'; |
| 15 | +import TabItem from '@theme/TabItem'; |
| 16 | + |
| 17 | +import CodeBlock from '@theme/CodeBlock'; |
| 18 | +import Heading from '@theme/Heading'; |
| 19 | + |
| 20 | +import NpmXpmTlDr from './_npm-xpm-tldr.mdx' |
| 21 | +import NpmXpmDetails from './_npm-xpm-details.mdx' |
| 22 | + |
| 23 | +{/* ------------------------------------------------------------------------ */} |
| 24 | + |
| 25 | +# Prerequisites for building xPack Binary Development Tools |
| 26 | + |
| 27 | +The scripts utilised to build the |
| 28 | +[xPack Binary Development Tools](https://github.com/xpack-dev-tools/) |
| 29 | +are based on the |
| 30 | +[xPack Build Box (XBB)](https://github.com/xpack/xpack-build-box) v5.1.0. |
| 31 | + |
| 32 | +The build scripts run on **GNU/Linux** and **macOS**. |
| 33 | + |
| 34 | +The **Windows** binaries are generated on x64 GNU/Linux, |
| 35 | +using [mingw-w64](https://mingw-w64.org). |
| 36 | + |
| 37 | +<Tabs groupId="operating-systems"> |
| 38 | + |
| 39 | +<TabItem value="macos" label="macOS"> |
| 40 | + |
| 41 | +The macOS builds run natively on x64 and arm64 |
| 42 | +machines, and apart from the usual **Command Line Tools** (provided by |
| 43 | +Apple) and `xpm`, the host machine has no other special |
| 44 | +requirements. |
| 45 | + |
| 46 | +The prerequisites are: |
| 47 | + |
| 48 | +- `npm` (shipped with Node.js; installed via nvm) |
| 49 | +- `xpm` (installed via `npm`) |
| 50 | +- the **Command Line Tools** from Apple |
| 51 | + |
| 52 | +Some build scripts may require **Python 3**. On modern systems, it should be |
| 53 | +available in the standard Apple distribution. If not, install it from Python |
| 54 | +[downloads](https://www.python.org/downloads/macos/). |
| 55 | + |
| 56 | +For development builds, the procedure can be executed on a recent macOS |
| 57 | +version (currently tested up to 14.6). |
| 58 | + |
| 59 | +For production builds it is recommended to use a slightly older version, |
| 60 | +for example **macOS 10.13** is a good compromise. |
| 61 | + |
| 62 | +It is not mandatory to have a physical macOS 10.13 machine, a virtual |
| 63 | +machine is also perfectly fine. Both Parallels and VirtualBox were |
| 64 | +tested and found to be functional (although VirtualBox was not as |
| 65 | +stable as Parallels). |
| 66 | + |
| 67 | +The build scripts were tested on: |
| 68 | + |
| 69 | +- macOS 14.6.1, running on an x64 MacMini |
| 70 | +- macOS 12.6.8, running on an x64 MacMini |
| 71 | +- macOS 10.14, running on a Intel NUC NUC8i7BEH |
| 72 | +- macOS 10.13, running inside a Parallels virtual machine |
| 73 | +- macOS 11.7.4, running on an Apple Silicon MacMini |
| 74 | + |
| 75 | +<NpmXpmTlDr /> |
| 76 | + |
| 77 | +:::info |
| 78 | + |
| 79 | +When running on macOS this script also installs |
| 80 | +the Command Line Tools. |
| 81 | + |
| 82 | +::: |
| 83 | + |
| 84 | +<NpmXpmDetails /> |
| 85 | + |
| 86 | + |
| 87 | +## The Command Line Tools |
| 88 | + |
| 89 | +The macOS compiler and other development tools are included in a |
| 90 | +separate Xcode add-on. The best place to obtain it is from the |
| 91 | +[Apple Developer Downloads](https://developer.apple.com/downloads/) site, |
| 92 | +although this might require enrolling in the developer program |
| 93 | +(free of charge). |
| 94 | + |
| 95 | +If you followed the _Quick instructions_, CLT should be already installed. |
| 96 | + |
| 97 | +Otherwise, the recommended method is to install the Command Line Tools |
| 98 | +separately via the command line: |
| 99 | + |
| 100 | +```console |
| 101 | +% xcode-select --install |
| 102 | +% xcode-select -p |
| 103 | +/Library/Developer/CommandLineTools |
| 104 | +$ gcc --version |
| 105 | +Apple clang version 15.0.0 (clang-1500.3.9.4) |
| 106 | +Target: x86_64-apple-darwin23.6.0 |
| 107 | +Thread model: posix |
| 108 | +InstalledDir: /Library/Developer/CommandLineTools/usr/bin |
| 109 | +``` |
| 110 | + |
| 111 | +:::info |
| 112 | + |
| 113 | +Xcode alone includes the compiler |
| 114 | +in the Xcode.app folder, which may vary in different versions; |
| 115 | +for a stable configuration it is |
| 116 | +necessary to install the CommandLineTools package. |
| 117 | + |
| 118 | +::: |
| 119 | + |
| 120 | +## No macOS Docker |
| 121 | + |
| 122 | +Due to the specifics of macOS, Docker cannot run natively; instead, |
| 123 | +it uses a GNU/Linux virtual machine running in Apple HyperKit |
| 124 | +(Apple's virtualization framework), and a file system compatibility |
| 125 | +layer. |
| 126 | + |
| 127 | +The end result is that Docker runs slowly, consumes a lot of memory, |
| 128 | +and is not reliable, so it is not recommended to run the |
| 129 | +Linux/Windows builds on macOS. |
| 130 | + |
| 131 | +</TabItem> |
| 132 | + |
| 133 | +<TabItem value="linux" label="GNU/Linux"> |
| 134 | + |
| 135 | +The GNU/Linux build scripts use a set |
| 136 | +of [Docker](https://www.docker.com) |
| 137 | +images based on older |
| 138 | +and more conservative distributions to avoid issues when |
| 139 | +running the executables on older systems. |
| 140 | + |
| 141 | +**Any x86_64/aarch64/armhf GNU/Linux distribution |
| 142 | +capable of running Docker should suffice**; a physical machine is not |
| 143 | +necessary, as virtual machines are |
| 144 | +perfectly adequate. For optimal results, allocate 3-4 cores and 8-12 GB of RAM. |
| 145 | + |
| 146 | +The XBB v5.0.0 Docker images are built on **Ubuntu 18 LTS** for both |
| 147 | +x64 and Arm GNU/Linux, ensuring the resulting binaries can |
| 148 | +run on any system based on **GLIBC >= 2.27**. |
| 149 | + |
| 150 | +:::info |
| 151 | + |
| 152 | +Building Arm binaries necessitates an Arm machine. A Raspberry |
| 153 | +Pi 4 with 8GB of RAM, paired with a Samsung Portable T7 USB 3 SSD, |
| 154 | +is an excellent solution. A Raspberry Pi 5 with an NVME SSD |
| 155 | +is even better. |
| 156 | + |
| 157 | +::: |
| 158 | + |
| 159 | +:::info |
| 160 | + |
| 161 | +Although Arm 32-bit binaries can be built inside Docker containers |
| 162 | +running on AArch64 machines, it is still recommended to use a 32-bit |
| 163 | +OS to avoid issues caused by the differences between armv7 and armv8. |
| 164 | + |
| 165 | +::: |
| 166 | + |
| 167 | +The prerequisites are: |
| 168 | + |
| 169 | +- `curl` (installed via the system package manager) |
| 170 | +- `git` (installed via the system package manager) |
| 171 | +- `docker` (preferably a recent one, installed from **docker.com**) |
| 172 | +- `npm` (shipped with Node.js; installed via **nvm**, |
| 173 | + **not** the system package manager) |
| 174 | +- `xpm` (installed via `npm`) |
| 175 | + |
| 176 | +The build scripts perform most of the actual work in a Docker container, and |
| 177 | +apart from `curl`, `git` `docker` and `xpm`, the host machine has no other |
| 178 | +special requirements. |
| 179 | + |
| 180 | +The build scripts were tested on: |
| 181 | + |
| 182 | +- Debian 11 (bullseye), running on an AMD Ryzen 5600G with 32 GB of RAM |
| 183 | +- Debian 10 (buster), running on an AMD Ryzen 5600G with 32 GB of RAM |
| 184 | +- Ubuntu 18.04 LTS, running on an Intel NUC NUC8i7BEH (i7) with 32 GB of RAM |
| 185 | +- Raspberry Pi OS 64-bit, running on a Raspberry Pi 4 with 8 GB of RAM |
| 186 | +- Raspberry Pi OS 32-bit, running on a Raspberry Pi 4 with 4 GB of RAM |
| 187 | + |
| 188 | +## curl & git |
| 189 | + |
| 190 | +Install `curl` & `git` using the system package manager. |
| 191 | + |
| 192 | +For example on Ubuntu and Debian-derived distributions, use: |
| 193 | + |
| 194 | +```sh |
| 195 | +sudo apt-get install --yes curl git |
| 196 | +``` |
| 197 | + |
| 198 | +## Docker |
| 199 | + |
| 200 | +A **recent Docker** is necessary. it can probably be used, but it |
| 201 | +is generally recommended to update to the latest stable version |
| 202 | +available directly from docker.com. |
| 203 | + |
| 204 | +For **any GNU/Linux** distribution, follow the |
| 205 | +[specific instructions](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/#install-using-the-repository). |
| 206 | + |
| 207 | +For example, the steps to install Docker on a modern **Ubuntu** system |
| 208 | +are essentially: |
| 209 | + |
| 210 | +```sh |
| 211 | +sudo apt-get update && \ |
| 212 | +\ |
| 213 | +sudo apt-get install ca-certificates curl gnupg && \ |
| 214 | +\ |
| 215 | +sudo mkdir -m 0755 -p /etc/apt/keyrings && \ |
| 216 | +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \ |
| 217 | +\ |
| 218 | +echo \ |
| 219 | + "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ |
| 220 | + "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ |
| 221 | + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null && \ |
| 222 | +\ |
| 223 | +sudo apt-get update && \ |
| 224 | +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin |
| 225 | +``` |
| 226 | + |
| 227 | +To check if the install is functional, run the _Hello World_ image, |
| 228 | +for the moment as `sudo`: |
| 229 | + |
| 230 | +```console |
| 231 | +$ sudo docker run hello-world |
| 232 | +Unable to find image 'hello-world:latest' locally |
| 233 | +latest: Pulling from library/hello-world |
| 234 | +b04784fba78d: Pull complete |
| 235 | +Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f |
| 236 | +Status: Downloaded newer image for hello-world:latest |
| 237 | + |
| 238 | +Hello from Docker! |
| 239 | +... |
| 240 | +``` |
| 241 | + |
| 242 | +### Configure Docker to run as a regular user |
| 243 | + |
| 244 | +To allow Docker to run as a regular user, you need to be a member of |
| 245 | +the `docker` group. |
| 246 | + |
| 247 | +```sh |
| 248 | +sudo groupadd docker |
| 249 | +sudo gpasswd -a ${USER} docker |
| 250 | + |
| 251 | +sudo service docker restart |
| 252 | +``` |
| 253 | + |
| 254 | +The above commands are for Ubuntu and the Debian family. For other |
| 255 | +distributions, the last line may differ. For example, for Arch Linux use: |
| 256 | + |
| 257 | +```sh |
| 258 | +systemctl restart docker |
| 259 | +``` |
| 260 | + |
| 261 | +To make these changes effective, it is preferable to **reboot** the machine. |
| 262 | + |
| 263 | +To check if the configuration change is functional, run the same |
| 264 | +_Hello World_ image without sudo: |
| 265 | + |
| 266 | +```console |
| 267 | +$ docker run hello-world |
| 268 | + |
| 269 | +Hello from Docker! |
| 270 | +... |
| 271 | +``` |
| 272 | + |
| 273 | +### Docker images |
| 274 | + |
| 275 | +The Docker images are available from |
| 276 | +[Docker Hub](https://hub.docker.com/u/ilegeul/). They were build using |
| 277 | +the Dockerfiles available from |
| 278 | +[XBB (xPack Build Box)](https://github.com/xpack/xpack-build-box/tree/master/). |
| 279 | + |
| 280 | +If not already loaded, Docker will load the images upon first usage. |
| 281 | +The images are reasonably large, currently below 1 GB. |
| 282 | + |
| 283 | +More details can be found on each script's documentation page. |
| 284 | + |
| 285 | +<NpmXpmTlDr /> |
| 286 | + |
| 287 | +<NpmXpmDetails /> |
| 288 | + |
| 289 | +</TabItem> |
| 290 | + |
| 291 | +</Tabs> |
| 292 | + |
| 293 | +## Visual Studio Code |
| 294 | + |
| 295 | +Although not mandatory, VS Code is a valuable addition to the |
| 296 | +development environment. With the |
| 297 | +[xPack extension](https://marketplace.visualstudio.com/items?itemName=ilg-vscode.xpack), |
| 298 | +some actions are just a mouse click away. |
0 commit comments