Initial commit: Klammertext source distribution
Curated source subset assembled by klammertext-dev's doc/make_dist.sh: the Klammermachine (mac), the Standard Klammer Set (sks), the commands (com), editor plugins and install guides (doc), a test subset (tst), and lib/bin placeholders. Builds with 'make -C com'. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
277
doc/install/linux_source_install.md
Normal file
277
doc/install/linux_source_install.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 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`.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The following packages are required to build Klammertext:
|
||||
|
||||
```bash
|
||||
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 OpenImageIO Python bindings. These must match
|
||||
the Python version that ktext is built against (check with
|
||||
`python3.XX -c "import OpenImageIO"`). For example, if ktext links against
|
||||
Python 3.12:
|
||||
|
||||
```bash
|
||||
pip3.12 install OpenImageIO
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
g++ --version
|
||||
```
|
||||
|
||||
|
||||
## Clone the repository
|
||||
|
||||
```bash
|
||||
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`):
|
||||
|
||||
```bash
|
||||
source /path/to/klammertext/mac/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 `mac/env/runtime.env.local` (sourced at the end).
|
||||
|
||||
After editing your shell profile, reload it:
|
||||
|
||||
```bash
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
|
||||
## Configure the build
|
||||
|
||||
No build configuration is needed. The single `mac/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:
|
||||
|
||||
```bash
|
||||
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. `OPTIMIZE=1` selects an optimized `-O3` build (what
|
||||
you want to install and run); without it you get a slower `-O0` debug build
|
||||
with AddressSanitizer, intended for development:
|
||||
|
||||
```bash
|
||||
make -C com -j OPTIMIZE=1 # lib/libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
|
||||
```
|
||||
|
||||
Verify the build:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```bash
|
||||
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`):
|
||||
|
||||
```bash
|
||||
cat >> "$KLAMMERTEXT_HOME/mac/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):
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```bash
|
||||
export PATH=$HOME/.ghcup/bin:$PATH
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
runghc --version
|
||||
```
|
||||
|
||||
Test in Klammertext:
|
||||
|
||||
```bash
|
||||
ktext -s '@eval :haskell main = putStr "Hello from Haskell" @' -d
|
||||
```
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
# Basic evaluation (Python)
|
||||
ktext -s '@eval 1 + 1 @' -d
|
||||
|
||||
# Shell evaluation
|
||||
ktext -s '@eval :shell date @' -d
|
||||
|
||||
# Show machine state (SKS is loaded by default)
|
||||
ktext -s '' -m
|
||||
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
cd $KLAMMERTEXT_HOME
|
||||
git pull
|
||||
make -C com -j OPTIMIZE=1 # rebuild library, SKS components, and commands
|
||||
```
|
||||
|
||||
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`:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user