# Klammertext source installation on Windows This document describes how to build and install Klammertext from source on Windows 10 or 11, so that the three commands `ktext`, `kdesc` and `kdiag` run as native Windows programs. Klammertext is developed on Linux and macOS; Windows is a supported place to *use* it, and installing it there takes more steps than on those systems, because Windows has no package manager that supplies a C++ compiler and `make`. The steps below were followed on a fresh Windows 11 machine and are the ones that worked. The installation uses three things a Windows user installs once: **MSYS2**, which provides the compiler, `make` and a Unix-style shell for building; **Python** from python.org, which Klammertext embeds; and **TeX Live**, for PDF output. Everyday use needs only PowerShell. ## Prerequisites ### Git and Python In PowerShell (search for "PowerShell" in the Start menu): ```powershell winget install --id Git.Git -e winget install --id Python.Python.3.12 -e --override "/quiet InstallAllUsers=1 PrependPath=1" ``` The second command installs Python for all users into `C:\Program Files\Python312` and puts it on the `Path`. Open a new PowerShell window (the `Path` of an open one does not change) and install the image library the `@image` klammer uses: ```powershell python -m pip install OpenImageIO python -c "import OpenImageIO" ``` Note that the interpreter is called `python` on Windows. There is no `python3`; the `python3` that Windows itself offers is a placeholder that opens the Microsoft Store, and Klammertext does not use it. ### MSYS2 and the compiler Install MSYS2 from https://www.msys2.org/ (or `winget install --id MSYS2.MSYS2 -e`). It installs into `C:\msys64`. Open the **"MSYS2 UCRT64"** shell from the Start menu — that one, not "MSYS2 MSYS" or "MINGW64": the UCRT64 environment shares its C runtime with python.org's Python, which is what lets the two be linked together. Update it and install the toolchain: ```bash pacman -Syu # if it closes the window, reopen the UCRT64 shell and run it again pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-make make \ mingw-w64-ucrt-x86_64-pkgconf mingw-w64-ucrt-x86_64-dlfcn diffutils ``` `diffutils` is only needed to run Klammertext's test suites. By default the MSYS2 shell does not see the programs Windows has on its `Path`, which means it cannot see `git` or `python`. Tell it to, once, in PowerShell, then reopen the UCRT64 shell: ```powershell setx MSYS2_PATH_TYPE inherit ``` Verify, in the UCRT64 shell: ```bash g++ --version # g++.exe (Rev4, Built by MSYS2 project) 16.x python --version # Python 3.12.x (python.org's, from the Windows Path) git --version ``` ## Clone the repository In the UCRT64 shell. Windows paths are written with forward slashes there, `/c/Users/` for `C:\Users\`: ```bash cd /c/Users/ git clone https://git.andykopra.com/ack/klammertext.git cd klammertext ``` Git for Windows must not translate line endings: Klammertext's `.kt` files, `.k` files and shell scripts are LF files. The clone above respects that as long as `core.autocrlf` is not `true`; check with `git config --get core.autocrlf` and, if it prints `true`, set it to `false` and clone again. ## Environment variables Klammertext's runtime environment is one self-configuring file, the same one Linux and macOS use. Source it from the UCRT64 shell's profile: ```bash echo 'source /c/Users//klammertext/env/runtime.env' >> ~/.bashrc source ~/.bashrc ``` On Windows it sets `KLAMMERTEXT_HOME` and `TMPDIR` in the form Windows programs understand (`C:/Users//klammertext`), adds `bin/` to `PATH`, finds a TeX Live installed under `C:\Users\\external\texlive\` (see below), and sets `PYTHON=python`. Nothing is edited by hand. ## Build In the UCRT64 shell, in the repository: ```bash make -C com -j ``` `-j` compiles in parallel; on a machine with 8 GB of memory or less the optimizing compiler may run out of memory and report `out of memory allocating`. If so, run `make -C com` without `-j`: slower, and it finishes. This builds the library, the Standard Klammer Set's components and the three commands into `bin\`, and copies the library and the compiler's runtime DLLs there too, so `bin\` is self-contained. The Python binding is built into `kpy\`. Verify: ```bash ktext -s '@eval 1 + 1 @' -d # prints 2 ktext -s '@eval :shell echo hello | tr a-z A-Z @' -d # prints HELLO ``` The second line shows that `@eval :shell` runs a POSIX shell on Windows as it does elsewhere: Klammertext ships one (`win\busybox\`), so a document's `:shell` command means the same thing on every system. For a first document, create `hello.kt`: ``` @document :structure article :title Hello :text @s1 Hello, Klammertext @ This document was built from source on Windows. @ ``` and render it: ```bash ktext hello.kt -t html # writes hello\index.html ``` ## TeX Live (for PDF output) The Standard Klammer Set renders PDF with **XeLaTeX**. Install TeX Live's `scheme-small` plus the packages the SKS needs into `C:\Users\\external\texlive\2026`, where `runtime.env` finds it. This is a download of about 600 MB and takes twenty to thirty minutes. 1. Download `install-tl.zip` from a CTAN mirror, for example `https://ctan.math.illinois.edu/systems/texlive/tlnet/install-tl.zip`, and unzip it. It unpacks into a folder named `install-tl-`. 2. In that folder, create a file `texlive.profile` with this content, replacing `` with your Windows user name: ``` selected_scheme scheme-small TEXDIR C:/Users//external/texlive/2026 TEXMFLOCAL C:/Users//external/texlive/2026/texmf-local TEXMFSYSCONFIG C:/Users//external/texlive/2026/texmf-config TEXMFSYSVAR C:/Users//external/texlive/2026/texmf-var TEXMFHOME C:/Users//texmf TEXMFVAR C:/Users//.texlive2026/texmf-var TEXMFCONFIG C:/Users//.texlive2026/texmf-config tlpdbopt_install_docfiles 0 tlpdbopt_install_srcfiles 0 tlpdbopt_autobackup 0 tlpdbopt_desktop_integration 0 tlpdbopt_file_assocs 0 tlpdbopt_w32_multi_user 0 ``` 3. In PowerShell, in that folder, run the installer without its graphical interface, naming the same mirror: ```powershell .\install-tl-windows.bat -no-gui -profile texlive.profile -repository https://ctan.math.illinois.edu/systems/texlive/tlnet ``` Leave the window open until it reports that the installation is complete. (A warning about `tlaunch.ini` is harmless.) 4. Still in PowerShell, install the additional packages the SKS requires beyond `scheme-small` — the same list `doc/install/texlive_additional_packages.sh` installs on Linux and macOS — and rebuild the formats: ```powershell $tl = "$env:USERPROFILE\external\texlive\2026\bin\windows" $env:Path = "$tl;$env:Path" & "$tl\tlmgr.bat" option repository https://ctan.math.illinois.edu/systems/texlive/tlnet & "$tl\tlmgr.bat" install adjustbox collectbox collection-fontsrecommended enumitem fontaxes footmisc inconsolata layouts mdframed multirow needspace opensans pict2e textpos titlesec upquote zref & "$tl\fmtutil-sys.exe" --all ``` The second line matters: `tlmgr` and `fmtutil` start helper programs such as `kpsewhich` by name and find them only through the `Path`. Open a new UCRT64 shell (so `runtime.env` runs again and finds the tree) and verify: ```bash xelatex --version ktext hello.kt -t pdf # writes hello.pdf ``` ## Using the commands from PowerShell Building needs the UCRT64 shell; using Klammertext does not. For everyday use from PowerShell, put three directories on the `Path` and set `KLAMMERTEXT_HOME`, once, as user environment variables (Settings ▸ System ▸ About ▸ Advanced system settings ▸ Environment Variables, or with `setx`): ```powershell setx KLAMMERTEXT_HOME "C:\Users\\klammertext" setx Path "$env:Path;C:\Users\\klammertext\bin;C:\Users\\external\texlive\2026\bin\windows" ``` Python is already on the `Path` from its installer. Open a new PowerShell window and `ktext`, `kdesc` and `kdiag` work there directly. Paths Klammertext prints use forward slashes on every system; paths you type may use either. ## Verifying the installation In the UCRT64 shell: ```bash ktext -s '@eval 1 + 1 @' -d # Python evaluation ktext -s '@eval :shell date @' -d # shell evaluation (the bundled sh) kdesc -t # the targets kdesc --typeface # the fonts Klammertext ships ktext hello.kt -t html # html ktext hello.kt -t pdf # pdf, requires TeX Live make -C $KLAMMERTEXT_HOME/tst test # the engine's test suites make -C $KLAMMERTEXT_HOME/sks/tst test # the Standard Klammer Set's suites (needs TeX Live) ``` A few suite cases report `SKIP` on Windows for things the MSYS2 shell cannot provide, such as a real terminal for the colour tests or a symbolic link; that is expected. ## Updating In the UCRT64 shell: ```bash cd $KLAMMERTEXT_HOME git pull make -C com -j ``` ## Troubleshooting **The command window closes at once, or "The code execution cannot proceed because python312.dll was not found".** Python's directory is not on the `Path` of that window. Reinstall Python with "Add to PATH" selected, or add `C:\Program Files\Python312` to the `Path` yourself, and open a new window. **`import OpenImageIO` fails with "DLL load failed while importing OpenImageIO".** The OpenImageIO package needs the Microsoft Visual C++ runtime, which nearly every Windows machine already has but a freshly installed one may not. Install it from https://aka.ms/vs/17/release/vc_redist.x64.exe and try the import again. **"libklammertext.so was not found" or "libstdc++-6.dll was not found".** `bin\` is not on the `Path`, or the build did not finish: `make -C com -j` places the library and the runtime DLLs in `bin\` beside the commands. **"The shell Klammertext runs sh commands with on Windows is missing".** `win\busybox\busybox64u.exe` is part of the repository; the clone is incomplete or `KLAMMERTEXT_HOME` points elsewhere. **"The 'xelatex' command required to make PDF files is not installed".** TeX Live's `bin\windows` directory is not on the `Path` of the shell you are using. In the UCRT64 shell `runtime.env` adds it when the tree is under `C:\Users\\external\texlive\`; in PowerShell add it as shown above. **`git` or `python` are "command not found" in the UCRT64 shell.** `MSYS2_PATH_TYPE` is not set to `inherit`, or the shell was opened before you set it. Set it and open a new UCRT64 shell. **The build is slow.** Windows Defender scans every file the compiler writes. Excluding the repository folder from real-time scanning speeds the build up considerably; it is not required.