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.


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

```bash
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:

```bash
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:

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

   ```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\<you>\klammertext"
setx Path "$env:Path;C:\Users\<you>\klammertext\bin;C:\Users\<you>\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\<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.