113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
|
# 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.
|