11 KiB
Klammertext source installation on Linux (Ubuntu / Pop!_OS)
This document describes how to build and install Klammertext from source on a
Linux system — Ubuntu or Pop!_OS; the steps are identical — without using the
container. A source installation gives full access to all @eval modes,
including :haskell and :shell commands that depend on locally installed
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. On a
Raspberry Pi it applies as well; raspberry_pi_install.md says what is
specific to that machine.
Prerequisites
The following packages are required to build Klammertext:
sudo apt-get update
sudo apt-get install g++ make python3-dev
The C++ compiler must support C++20. GCC 11 or later is required (Ubuntu 22.04 and later include GCC 12+).
The SKS @image klammer requires the OpenImageIO Python bindings, for the
same Python that ktext is built against (the system python3). Ubuntu
packages them:
sudo apt-get install python3-openimageio
python3 -c "import OpenImageIO"
To use a PDF file as an image (@image of a .pdf), poppler's pdfinfo
and pdftoppm must be on the PATH; without them such a document stops
with a message naming the package:
sudo apt-get install poppler-utils
(A pip install works too, but a fresh Ubuntu has no pip until
python3-pip is installed, and since 24.04 it refuses to install into the
system Python without --break-system-packages; the package avoids both.)
Verify:
g++ --version
Clone the repository
git clone https://git.andykopra.com/ack/klammertext.git
cd klammertext
Environment variables
Klammertext's runtime environment is provided by a single self-configuring
file. Source it from your shell profile (e.g., ~/.bashrc or ~/.zshrc):
source /path/to/klammertext/env/runtime.env
It self-locates KLAMMERTEXT_HOME from its own path, adds bin/ and
tst/ to PATH (plus the newest ~/external/texlive/<year>/bin/<arch> if a
TeX Live is installed there), sets LD_LIBRARY_PATH so libklammertext.so is
found, and sets the LSan suppressions. There is no per-host or per-OS variable
to set. For a TeX Live or library in a non-standard location, add it to an
optional, gitignored env/runtime.env.local (sourced at the end).
After editing your shell profile, reload it:
source ~/.bashrc
Configure the build
No build configuration is needed. The single env/makefile.env is
cross-platform: it reads KLAMMERTEXT_HOME from the environment (set by
runtime.env above), auto-detects the platform with uname, and auto-detects
Python with python3-config — no hardcoded version and no per-host file to
edit. Verify the Python development headers are present:
python3-config --includes # prints -I.../python3.XX for your Python
If python3-config is missing, install your distribution's python3-dev
(Debian/Ubuntu) or python3-devel (Fedora/RHEL) package.
Build
Build the shared library, the SKS components, and the three commands with a
single command: make -C com builds its prerequisites in mac/ and sks/
first, then the commands. The build is optimized (-O3) by default — the build
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.)
Verify the build:
ktext -s '@eval 1 + 1 @' -d
This should print 2. For a quick document smoke test, create a small file and
render it to HTML:
cat > hello.kt <<'EOF'
@document
:structure article
:title Hello
:text
@s1 Hello, Klammertext @
This document was built from source.
@
EOF
ktext hello.kt -t html # writes hello/index.html
TeX Live (for PDF output)
The Standard Klammer Set uses XeLaTeX for the pdf target. Build a complete
Klammertext TeX Live tree with the bundled script, giving it a destination
directory under ~/external/texlive/<year> — the location runtime.env
auto-detects. The script needs perl, xz-utils, fontconfig, and either
wget or curl:
sudo apt-get install perl wget xz-utils fontconfig
bash $KLAMMERTEXT_HOME/doc/install/texlive_additional_packages.sh ~/external/texlive/2026
This installs scheme-small plus the additional packages the SKS needs and
rebuilds all formats, fetching the binaries for your architecture. It writes a
KLAMMERTEXT_BUILD_INFO.txt provenance file (mirror, release, package list,
date) into the tree.
Because the tree lives under ~/external/texlive/2026, runtime.env finds it
automatically — open a new shell (or re-source runtime.env) and xelatex
will be on PATH. No manual KLAMMERTEXT_TEXLIVE_BIN is needed.
If you would rather reuse a TeX Live you already have, point runtime.env at it
from the gitignored escape hatch instead, and install the SKS's extra packages
into it yourself (the package list is in doc/install/texlive_additional_packages.sh):
cat >> "$KLAMMERTEXT_HOME/env/runtime.env.local" <<'EOF'
export KLAMMERTEXT_TEXLIVE_BIN=/path/to/texlive/bin/x86_64-linux
export PATH="$KLAMMERTEXT_TEXLIVE_BIN:$PATH"
EOF
Verify and test (reusing the hello.kt from the Build section):
xelatex --version
ktext hello.kt -t pdf # writes hello.pdf
Optional: Haskell (for @eval :haskell)
The @eval :haskell mode requires runghc, which is part of the Haskell
toolchain. Alternatively, the akopra/klammertext:haskell container image
includes GHC (see linux_container_install.md).
The recommended way to install Haskell on Ubuntu is via ghcup:
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
Follow the prompts to install GHC, cabal, and related tools. After
installation, ensure the ghcup bin directory is in your PATH:
export PATH=$HOME/.ghcup/bin:$PATH
Verify:
runghc --version
Test in Klammertext:
ktext -s '@eval :haskell main = putStr "Hello from Haskell" @' -d
Optional: the mdpdf command (Markdown to PDF)
Klammertext ships a second, independent route in sks/tns/: mdpdf renders
a Markdown file to PDF through a headless browser, bypassing Klammertext
entirely. It is for a document that is not written in Klammertext — one you
have not converted yet, or one whose Markdown is not worth converting.
The command is a shell function that env/runtime.env defines, so if you
source that file (see Environment variables above) you already have it —
in shells started after the installation. In a shell that was already
running, source it again:
source $KLAMMERTEXT_HOME/env/runtime.env
type mdpdf # mdpdf is a shell function
Two things it needs that the distribution does not install:
# 1. The Markdown renderer, in a virtual environment of its own. PEP 668
# forbids installing it into the system Python, so this is not optional
# and not a system package.
python3 $KLAMMERTEXT_HOME/sks/tns/md_to_pdf.py --setup
# 2. A Chromium-based browser -- Brave, Chrome or Chromium -- which is the
# renderer. Any one of them will do; install whichever you prefer.
sudo apt install chromium-browser
A browser installed as a flatpak works too and is found without being
told: that is what the Pop!_Shop installs on Pop!_OS, and a flatpak puts
nothing on PATH, so the command looks for the application by name in the
flatpak export directories as well. The document is served to the browser
over the loopback interface rather than handed to it as a file path, so a
sandboxed browser needs no filesystem permission of any kind — including
none to reach the fonts, which is what silently cost a flatpak render its
typography before this was so.
Then:
mdpdf notes.md # writes notes.pdf beside it
mdpdf notes # the .md may be left off
It supplies the fonts, the size matching and the code wrapping, and completes
on *.md at the TAB key. Each default is a variable you may set in your
shell profile — MDPDF_SERIF, MDPDF_SANS, MDPDF_MONO, MDPDF_MATCH,
MDPDF_WRAP, and MDPDF_BROWSER for a browser installed somewhere the
command does not look. Any option of the underlying md_to_pdf.py may also
be given on the command line, where it overrides the default:
mdpdf notes.md --paper letter --margin 0.75
The stylesheet it applies is sks/tns/markdown.css; copy it, edit the copy,
and pass --css yourcopy.css to render to your own taste.
Directory layout after build
klammertext/
├── bin/ ktext, kdesc, kdiag executables (after build)
├── lib/ libklammertext.so shared library (after build)
├── mac/ Klammermachine C++ source
├── sks/ Standard Klammer Set (.k files and .so modules)
│ ├── document/ document.so
│ ├── kutil/ kutil.o
│ └── target/ html_util.o, latex_util.o
├── com/ command source (ktext, kdesc, kdiag) and Makefile
├── doc/ installation guides (doc/install) and editor support (doc/edit)
└── tst/ test suites
Verifying the installation
Run the following commands to verify that everything works:
# Basic evaluation (Python)
ktext -s '@eval 1 + 1 @' -d
# Shell evaluation
ktext -s '@eval :shell date @' -d
# Show the machine's initial state: targets, argument types, the primitive klammers
kdiag --machine
# HTML and PDF output (uses the hello.kt from the Build section)
ktext hello.kt -t html
ktext hello.kt -t pdf # requires TeX Live
# Haskell evaluation (requires ghcup)
ktext -s '@eval :haskell main = putStr "42" @' -d
# Run unit tests
make -C $KLAMMERTEXT_HOME/tst test
Updating
To update an existing source installation to the latest version:
cd $KLAMMERTEXT_HOME
git pull
make -C com # rebuild library, SKS components, and commands (optimized)
The TeX Live tree only needs rebuilding if the SKS's package requirements changed (rare); when they do, re-run the script from the TeX Live section above.
Troubleshooting
"libklammertext.so: cannot open shared object file"
Ensure LD_LIBRARY_PATH includes $KLAMMERTEXT_HOME/lib:
export LD_LIBRARY_PATH=$KLAMMERTEXT_HOME/lib:$LD_LIBRARY_PATH
"KLAMMERTEXT_HOME is not set" Set the environment variable as described in the Environment variables section above.
"python3.XX/Python.h: No such file or directory" Install the Python development headers:
sudo apt-get install python3-dev
"xelatex: command not found" (when using -t pdf)
Install TeX Live and ensure its bin directory is in PATH.
"@eval :haskell requires runghc" Install Haskell via ghcup as described in the Optional: Haskell section.