klammertext/doc/install/windows_source_install.md

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.

This is one of three ways to have Klammertext on Windows. If you are at home in Linux, the Windows Subsystem for Linux gives you the Linux installation unchanged, with the Windows editors and browser alongside: windows_wsl_install.md. If you want no build at all, the prebuilt container images run on Windows through Docker Desktop, which that page also describes. This page is the native route: Windows programs, no Linux layer.

Prerequisites

Git and Python

In PowerShell (search for "PowerShell" in the Start menu):

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:

python -m pip install OpenImageIO
python -c "import OpenImageIO"

To use a PDF file as an image (@image of a .pdf), Klammertext runs poppler's pdfinfo and pdftoppm; without them such a document stops with a message naming the package. MSYS2 (installed below) provides them: in the UCRT64 shell pacman -S mingw-w64-ucrt-x86_64-poppler, and for use from PowerShell put C:\msys64\ucrt64\bin on your Path as well.

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:

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:

setx MSYS2_PATH_TYPE inherit

Verify, in the UCRT64 shell:

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/<you> for C:\Users\<you>:

cd /c/Users/<you>
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:

echo 'source /c/Users/<you>/klammertext/env/runtime.env' >> ~/.bashrc
source ~/.bashrc

On Windows it sets KLAMMERTEXT_HOME and TMPDIR in the form Windows programs understand (C:/Users/<you>/klammertext), adds bin/ to PATH, finds a TeX Live installed under C:\Users\<you>\external\texlive\<year> (see below), and sets PYTHON=python. Nothing is edited by hand.

Build

In the UCRT64 shell, in the repository:

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 (klammertext.dll), the Standard Klammer Set's components and the three commands (ktext.exe, kdesc.exe, kdiag.exe) 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:

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:

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\<you>\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-<date>.

2. In that folder, create a file texlive.profile with this content, replacing <you> with your Windows user name:

   selected_scheme scheme-small
   TEXDIR C:/Users/<you>/external/texlive/2026
   TEXMFLOCAL C:/Users/<you>/external/texlive/2026/texmf-local
   TEXMFSYSCONFIG C:/Users/<you>/external/texlive/2026/texmf-config
   TEXMFSYSVAR C:/Users/<you>/external/texlive/2026/texmf-var
   TEXMFHOME C:/Users/<you>/texmf
   TEXMFVAR C:/Users/<you>/.texlive2026/texmf-var
   TEXMFCONFIG C:/Users/<you>/.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:

   .\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:

   $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:

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 two directories on the Path and set KLAMMERTEXT_HOME, once, as user environment variables (Settings ▸ System ▸ About ▸ Advanced system settings ▸ Environment Variables, or from PowerShell):

[Environment]::SetEnvironmentVariable("KLAMMERTEXT_HOME", "C:\Users\<you>\klammertext", "User")
$p = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$p;C:\Users\<you>\klammertext\bin;C:\Users\<you>\external\texlive\2026\bin\windows", "User")

(Not setx Path "$env:Path;…": $env:Path is the machine and user values merged, so that copies every machine entry into your user Path, and setx silently cuts a value over 1024 characters.) 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.

One PowerShell rule to know when you pass Klammertext text with -s: an apostrophe inside a single-quoted string ends the string, so It's must be written It''s (two apostrophes), or the whole text put in double quotes. The error you get otherwise mentions a "here-string header", because PowerShell reads the next @' as one; it is PowerShell's message, not Klammertext's.

ktext -s '@i It''s a Pyrrhic victory! @' -d
ktext -s "@i It's a Pyrrhic victory! @" -d

Verifying the installation

In the UCRT64 shell:

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

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. (The Standard Klammer Set's own suites are part of the development repository, not of this distribution.)

Updating

In the UCRT64 shell:

cd $KLAMMERTEXT_HOME
git pull
make -C com -j

Editor support

Klammertext's editor support (doc\edit\, one shared implementation behind VS Code, Sublime Text, Vim and Emacs integrations) works on Windows with the Python already installed. Each editor's README in doc\edit\ has the details; the Windows-specific steps are these.

Visual Studio Code. Build the extension package in the UCRT64 shell, then install it from PowerShell (or from any window where code is on the Path):

cd ~/klammertext/doc/edit/vscode && ./make_vsix.sh

code --install-extension C:\Users\<you>\klammertext\doc\edit\vscode\klammertext.vsix

Reload VS Code. The extension runs python from the Path and finds the language server inside the package; nothing needs configuring.

Sublime Text 4. Copy the package and the shared core into Sublime's Packages directory (Preferences ￫ Browse Packages… opens it):

$p = "$env:AppData\Sublime Text\Packages\Klammertext"
New-Item -ItemType Directory -Force $p | Out-Null
Copy-Item C:\Users\<you>\klammertext\doc\edit\sublime\* $p
Copy-Item C:\Users\<you>\klammertext\doc\edit\shared\klammertext_edit.py $p

Sublime loads the package live.

Notepad++. Highlighting comes from a User Defined Language file, the delimiter check and reindentation from two Run-menu commands (doc\edit\notepadpp\README.md has both):

$d = "$env:AppData\Notepad++\userDefineLangs"
New-Item -ItemType Directory -Force $d | Out-Null
Copy-Item C:\Users\<you>\klammertext\doc\edit\notepadpp\Klammertext.udl.xml $d

Restart Notepad++; .kt and .k files open as Klammertext.

Vim. As in doc\edit\vim\README.md; the plugin runs the shared core through python on Windows automatically.

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.

"klammertext.dll 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\<you>\external\texlive\<year>; 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.