# 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.