Skip to content

Commit b818a1b

Browse files
ilg-ulilg-ul
committed
Revert "website: updates"
This reverts commit 2ed042f.
1 parent 2ed042f commit b818a1b

File tree

3 files changed

+370
-0
lines changed

3 files changed

+370
-0
lines changed

‎website/docs/developer/install/prerequisites/_npm-xpm-details.mdx

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
2+
3+
### node/npm
4+
5+
`npm` is included with Node.js and is required to install `xpm`.
6+
7+
For full details on installing Node.js, please refer to the
8+
[xPack prerequisites](http://xpack.github.io/install/) page.
9+
10+
:::caution
11+
12+
Ensure you **do not** install npm with administrative rights,
13+
such as via a system package manager. Instead, use `nvm` as
14+
instructed to avoid permission-related issues.
15+
16+
:::
17+
18+
### xpm
19+
20+
[`xpm`](https://xpack.github.io/xpm/) is a portable
21+
[Node.js](https://nodejs.org/) command line application.
22+
23+
If you followed the _Quick instructions_, it is already installed.
24+
25+
Otherwise, to install it, follow the steps in the
26+
[xpm install](http://xpack.github.io/xpm/install/) page.
27+
28+
If you are confident in your knowledge and prefer a shortcut,
29+
issue the following command:"
30+
31+
32+
```sh
33+
npm install --global xpm@latest
34+
```

‎website/docs/developer/install/prerequisites/_npm-xpm-tldr.mdx

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
2+
3+
## npm/xpm
4+
5+
### Quick instructions
6+
7+
If you are confident in your knowledge and prefer a shortcut, copy and
8+
paste the following
9+
[script](https://github.com/xpack/assets/blob/master/scripts/install-nvm-node-npm-xpm.sh)
10+
into a terminal (otherwise, perform the steps one by one).
11+
12+
:::caution
13+
14+
For security reasons, conscientious users should first check
15+
the content of the file before executing it.
16+
17+
:::
18+
19+
```sh
20+
mkdir -pv "${HOME}/Downloads/"
21+
curl --output "${HOME}/Downloads/install-nvm-node-npm-xpm.sh" https://raw.githubusercontent.com/xpack/assets/master/scripts/install-nvm-node-npm-xpm.sh
22+
cat "${HOME}/Downloads/install-nvm-node-npm-xpm.sh"
23+
24+
bash "${HOME}/Downloads/install-nvm-node-npm-xpm.sh"
25+
26+
exit
27+
```
28+
29+
This script will install `nvm` (the Node Version Manager), `node`,
30+
`npm` and `xpm`.
31+
32+
:::info
33+
34+
To activate `nvm` automatically,
35+
the script adds several lines
36+
to the shell initialisation script.
37+
38+
:::

‎website/docs/developer/install/prerequisites/index.mdx

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
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

Comments
 (0)