From 62f08401aa3f3051aab46c0a0f204f192fd72f1d Mon Sep 17 00:00:00 2001 From: Andy Kopra Date: Wed, 30 Sep 2026 23:43:41 +0200 Subject: [PATCH] A Raspberry Pi install page; the build's job count is the core count (from dev 6f49f498c3c6) --- README.md | 3 +- doc/install/linux_source_install.md | 13 +++- doc/install/macos_source_install.md | 7 ++ doc/install/raspberry_pi_install.md | 113 ++++++++++++++++++++++++++++ 4 files changed, 134 insertions(+), 2 deletions(-) create mode 100644 doc/install/raspberry_pi_install.md diff --git a/README.md b/README.md index eb23719..c4e65ee 100644 --- a/README.md +++ b/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 diff --git a/doc/install/linux_source_install.md b/doc/install/linux_source_install.md index 3e96b9f..5683e13 100644 --- a/doc/install/linux_source_install.md +++ b/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`.) diff --git a/doc/install/macos_source_install.md b/doc/install/macos_source_install.md index 8d1e3d4..101055c 100644 --- a/doc/install/macos_source_install.md +++ b/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`.) diff --git a/doc/install/raspberry_pi_install.md b/doc/install/raspberry_pi_install.md new file mode 100644 index 0000000..f2f3cee --- /dev/null +++ b/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/`, 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.