A Raspberry Pi install page; the build's job count is the core count (from dev 6f49f498c3c6)

README.md

@@ -15,6 +15,7 @@ Installation guides are in [`doc/install/`](doc/install/):
 - Windows, Linux inside WSL — `doc/install/windows_wsl_install.md`
 - Linux, container — `doc/install/linux_container_install.md`
 - macOS, container — `doc/install/macos_container_install.md`
+- Raspberry Pi, from source — `doc/install/raspberry_pi_install.md`
 
 ## Building from source
 
@@ -53,7 +54,7 @@ are regenerated on each release — patches cannot be merged directly.
 Report problems (or send patches) to the author; accepted changes are
 applied to the development tree and appear in a following snapshot.
 
-This snapshot was assembled from development commit `16f82cc887af`.
+This snapshot was assembled from development commit `6f49f498c3c6`.
 
 ## License
 

doc/install/linux_source_install.md

@@ -8,7 +8,9 @@ software.
 
 For the container installation on Linux, see `linux_container_install.md`.
 On Windows, this page also applies unchanged inside the Windows Subsystem
-for Linux; `windows_wsl_install.md` says what is specific to WSL.
+for Linux; `windows_wsl_install.md` says what is specific to WSL. On a
+Raspberry Pi it applies as well; `raspberry_pi_install.md` says what is
+specific to that machine.
 
 
 ## Prerequisites
@@ -109,6 +111,15 @@ you want to install and run:
 make -C com        # lib/libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
 ```
 
+The build compiles as many files at once as the machine has cores (`-j`
+with the core count, in the variable `JOBS`), and more jobs than cores
+gain nothing: a compile keeps a core busy, so eight jobs on a four-core
+machine only take turns. On a machine with little memory the optimizing
+compiler may run out of it and report `out of memory allocating`; if so,
+`make -C com JOBS=2`, or `JOBS=1`: slower, and it finishes. A Raspberry Pi
+5 (four cores, 8 GB) builds with its four in under five minutes and needs
+no such limit.
+
 (For a slower `-O0` debug build with AddressSanitizer, intended for development,
 prefix `DEBUG=1`: `DEBUG=1 make -C com`.)
 

doc/install/macos_source_install.md

@@ -90,6 +90,13 @@ make -C com               # optimized (-O3) by default; libklammertext.so + sks/
 ktext -s '@eval 1 + 1 @' -d  # smoke test — prints 2
 ```
 
+The build compiles as many files at once as the machine has cores (`-j`
+with the core count, in the variable `JOBS`), and more jobs than cores
+gain nothing: a compile keeps a core busy, so eight jobs on a four-core
+machine only take turns. On a machine with little memory the optimizing
+compiler may run out of it and report `out of memory allocating`; if so,
+`make -C com JOBS=2`, or `JOBS=1`: slower, and it finishes.
+
 (For a debug build with AddressSanitizer, intended for development, prefix
 `DEBUG=1`: `DEBUG=1 make -C com`.)
 

doc/install/raspberry_pi_install.md

@@ -0,0 +1,113 @@
+# Klammertext on a Raspberry Pi
+
+A Raspberry Pi runs Linux, and Klammertext's Linux installation applies
+on it: the same compiler, the same Python, the same TeX Live, the same
+`runtime.env`. So this page is short. It says which Pi and which system
+the installation was done on, sends you to the Linux page, and then says
+what is specific to a small machine: what its four cores and its memory
+mean for the build, what TeX Live takes there, and what to do if a step
+runs out of room. The steps were followed on a Raspberry Pi 5 Model B
+with 8 GB of memory, running the 64-bit Raspberry Pi OS (Debian 12,
+"bookworm"), from a fresh clone of the public repository.
+
+
+## The system
+
+Use the **64-bit** Raspberry Pi OS, whichever edition (with desktop or
+Lite). The installation on this page was done on it; the 32-bit edition
+was not tried. Its Debian base has everything the Linux page asks for,
+under the same package names, and `uname -m` says `aarch64`.
+
+Everything below happens in a terminal on the Pi, or over `ssh` to it.
+Nothing needs the desktop.
+
+
+## Installing Klammertext
+
+Follow `linux_source_install.md`, from its first line. Everything on it
+applies: the packages by `apt-get` (`g++`, `make`, `python3-dev`, the
+image library `python3-openimageio`, `poppler-utils`), the clone, the
+line in `~/.bashrc` that sources `runtime.env`, the build, TeX Live by the
+bundled script, the verification. No command on that page is different
+on the Pi.
+
+What the Pi did with them, on the machine this page was written on:
+
+| Step | On a Raspberry Pi 5 (8 GB) |
+|---|---|
+| Compiler | GCC 12.2, the Debian 12 package |
+| Python | 3.11, with OpenImageIO 2.4 from `python3-openimageio` |
+| `make -C com` | under five minutes, four jobs |
+| Engine test suite (`make -C tst test`) | about two minutes, all passing |
+| TeX Live | a 770 MB tree under `~/external/texlive/2026`, `aarch64-linux` binaries |
+| Memory in use at the height of the build | about 1.6 GB |
+| Temperature at the height of the build | 57 °C on the passive heat sink, no throttling |
+
+
+## Cores and memory
+
+The build runs one compile per core, four on a Pi 5, and more jobs than
+cores gain nothing: a compile keeps a core busy, so eight jobs on four
+cores only take turns. Four jobs is what the Linux page's build command
+does on a Pi by itself, with no option to add.
+
+Memory is the other side. The optimizing compiler takes up to about half
+a gigabyte for one of the larger source files, and four of them at once
+took the machine's use to about 1.6 GB, which an 8 GB Pi 5 does not
+notice. By that measurement a 4 GB model has room for the same four-job
+build. On a model with less memory, or if the build ever stops with
+`out of memory allocating`, lower the count:
+
+```bash
+make -C com JOBS=2      # or JOBS=1: slower, and it finishes
+```
+
+The default Raspberry Pi OS swap file is small (512 MB), which is why the
+job count is the thing to lower rather than something to wait out: a
+build that has run out of memory does not finish by itself.
+
+
+## TeX Live
+
+The Linux page's TeX Live script fetches the binaries for the machine it
+runs on, so on a Pi it installs the `aarch64-linux` set with no option
+given. The download is about 600 MB and the finished tree about 770 MB;
+plan the time by your connection, since the download is most of it.
+`runtime.env` finds the tree under `~/external/texlive/2026` on the Pi
+as it does anywhere, and `ktext hello.kt -t pdf` then works from the
+Linux page's verification section.
+
+
+## The container route
+
+The prebuilt Klammertext images are built for `arm64` as well as
+`amd64`, so `linux_container_install.md` applies on a 64-bit Raspberry Pi
+OS with Docker installed, and Docker pulls the `arm64` build by itself.
+That route was not part of the installation this page records; the
+source route above is what was done and measured.
+
+
+## Troubleshooting
+
+**The build stops with `out of memory allocating`, or the Pi freezes
+during it.** The machine has run out of memory for the number of
+compiles running at once. Restart it if it froze, then build with fewer
+jobs, `make -C com JOBS=2` or `JOBS=1`, as in Cores and memory above.
+
+**`python3 -c "import OpenImageIO"` fails.** Install the Debian package,
+`sudo apt-get install python3-openimageio`; it is the OpenImageIO for the
+system Python that `ktext` is built against. A `pip` install is refused
+into the system Python on Debian 12 without `--break-system-packages`,
+and the package avoids that.
+
+**`xelatex: command not found`.** The TeX Live tree is not under
+`~/external/texlive/<year>`, where `runtime.env` looks, or the shell was
+started before the tree existed. Open a new terminal; if that does not
+help, check the path the script was given.
+
+**The Pi gets hot during the build.** A four-core compile for several
+minutes is the hardest thing Klammertext asks of the machine. The build
+on this page peaked at 57 °C on the passive heat sink the Pi came with,
+well below the point where the system slows the processor down, and
+`vcgencmd get_throttled` reported no throttling. A Pi without any heat
+sink may throttle, which makes the build slower but not wrong.