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.

**Before you start.** The prerequisites install for all users of the
machine, so the account you use must be an administrator, which on a
personal machine it normally is; the build and everyday use need no
special rights. Allow an hour or two the first time: the downloads are
about a gigabyte in all, TeX Live alone takes twenty to thirty minutes,
and the build a few minutes. Nothing here needs to be done twice.

**Smart App Control must be off.** A clean installation of Windows 11
runs Smart App Control, a security feature that blocks any program
Microsoft has not seen signed and widespread — and the MSYS2 compiler,
`make` and the `bash` shell on which this page depends are not signed, nor
is the Perl that TeX Live's installer brings with it, so with it on the
MSYS2 installer never finishes, the MSYS2 shell does not open, the build
cannot start and TeX Live cannot be installed ("An Application Control
policy has blocked this file"; the notice from Windows Security says the
program "might not work because we can't confirm who published it").
Check it first:
Windows Security ￫ **App & browser control** ￫ **Smart App Control
settings**. It is in one of three states. *Off* is what you need. *On*
blocks MSYS2; switch it off. *Evaluation* lets everything run for now,
but Windows turns it on by itself when it decides the machine is used
"safely", at which point a working installation stops without warning —
so switch it off at once rather than wait. Switching it off cannot be
undone short of reinstalling Windows, which is why Microsoft asks you to
confirm; the rest of Windows Security (Defender, SmartScreen for
downloads) stays on and is not affected. A machine upgraded from Windows
10, or one on which an unsigned program has already been installed, has
it off already.


## 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"
```

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:

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

The repository's path must contain no space: GNU Make cannot build under
one. If your user name has a space in it (`C:\Users\Anna Maria`), clone
somewhere else, for example into `C:\klammertext`, and write that path
wherever `C:\Users\<you>\klammertext` appears below. Accented letters in
the path are fine for the commands; only the Python binding (`kpy\`) needs
a path of plain ASCII letters.

Klammertext's `.kt` files, `.k` files and shell scripts are LF files, and
the repository says so itself (`.gitattributes`), so the clone is correct
whatever your Git's `core.autocrlf` setting. A `.kt` you write with
Windows line endings is fine too: ktext reads them as newlines.


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

The build compiles as many files at once as the machine has cores. 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, `make -C com
JOBS=2`, or `JOBS=1`: 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:

```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:\texlive\2026`,
TeX Live's own default location on Windows, where `runtime.env` finds it.
(It also looks under `C:\Users\<you>\external\texlive\<year>`, the place
the Linux and macOS pages use, but TeX Live does not work under a path
with a space or an accented letter, and a user name may have either.)
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:

   ```
   selected_scheme scheme-small
   TEXDIR C:/texlive/2026
   TEXMFLOCAL C:/texlive/2026/texmf-local
   TEXMFSYSCONFIG C:/texlive/2026/texmf-config
   TEXMFSYSVAR C:/texlive/2026/texmf-var
   TEXMFHOME C:/texlive/2026/texmf-home
   TEXMFVAR C:/texlive/2026/texmf-uvar
   TEXMFCONFIG C:/texlive/2026/texmf-uconfig
   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 = "C:\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 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):

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

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

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

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:

```bash
cd $KLAMMERTEXT_HOME
git pull
make -C com
```


## 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`):

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

```powershell
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):

```powershell
$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):

```powershell
$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`
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:\texlive\<year>` or `C:\Users\<you>\external\texlive\<year>`; in
PowerShell add it as shown above.

**`make` stops at once with `"python" is C:/msys64/ucrt64/python, not
python.org's interpreter`.** MSYS2's own Python was installed as a
dependency (poppler brings it), and in the UCRT64 shell it precedes
python.org's on the `Path`. `runtime.env` puts python.org's first: source
it (a new UCRT64 shell does, once the line is in `~/.bashrc`) and run
`make` again.

**`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.

**"An Application Control policy has blocked this file", the MSYS2
installer runs without ever finishing, or the MSYS2 shell does not open.**
Smart App Control is on; see *Before you start*. Close the installer,
switch Smart App Control off, and run the installer again.
It can turn itself on after the installation, in which case the
installation is intact and only the setting needs changing.

**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.