ack/klammertext
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Klammertext runs natively on Windows; a Windows source-install guide; the bundled sh for @eval :shell

Browse Source 
Assembled from klammertext-dev f344a37d0f6e. The commands, the library,
the Standard Klammer Set, the reflection klammerset and the Python
binding build and run natively on Windows (MSYS2 UCRT64 gcc, python.org
Python), and both test tiers pass there. doc/install/windows_source_install.md
is the fifth install guide: a source install parallel to the Linux and
macOS ones, verified by following it on a pristine Windows 11.

Behaviour on every system: paths Klammertext prints use forward slashes;
output is LF; the command line is UTF-8 on Windows; @eval :shell is a
POSIX shell command everywhere -- on Windows it runs the sh Klammertext
ships, BusyBox for Windows (win/busybox/, GPLv2, with its licence and the
source pointer). KLAMMERTEXT_FONTS and KLAMMERTEXT_KLAMMERSETS are lists in
the system's PATH convention (';' on Windows). On Linux and macOS nothing
observable changes.
This commit is contained in:
ack committed 2026-09-25 00:32:55 +02:00
1 parent f9af1ff869
commit fe475e774a
55 files changed
+1182 -153
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

doc/install/windows_source_install.md
+305
View File
@@ -0,0 +1,305 @@
# 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.