klammertext/doc/install/windows_wsl_install.md

Klammertext on Windows through the Windows Subsystem for Linux

This is how Klammertext is installed on Windows. The Windows Subsystem for Linux (WSL 2) runs a real Linux kernel and an ordinary Ubuntu inside Windows, and Klammertext's Linux installation applies there unchanged: the same compiler, the same Python, the same TeX Live, the same runtime.env. So this page is short. It gets you to an Ubuntu prompt, sends you to the Linux page, and then says what is specific to living in WSL: where files belong, how to look at the output from Windows, and how the Windows editors reach the Linux side. The steps were followed on a Windows 11 machine with WSL 2.7 and the Ubuntu it installs today, 26.04.

The commands are Linux programs, run from the Ubuntu prompt; there is no native Windows build. The other way to have Klammertext on Windows is the prebuilt container images, which this page covers at the end, since Docker runs inside WSL as it runs on Linux.

Getting Linux

In a PowerShell window:

wsl --install

This turns on the subsystem, installs the WSL layer and the current Ubuntu, and may ask you to restart Windows; do that before going on. Then open a terminal and type wsl (or start "Ubuntu" from the Start menu). The first start asks for a Linux username and a password; these are separate from your Windows account. Ubuntu may also ask whether to send platform metrics; you can say no. You are then at a bash prompt in your Linux home directory, and wsl -l -v in PowerShell shows Ubuntu as version 2.

Two things worth knowing about the Ubuntu you now have: sudo works with the password you just chose, and the machine's Windows Path is appended to the Linux PATH, so Windows programs can be run from the Linux prompt by name (explorer.exe, code). That is convenient below and harmless otherwise; a Windows Python or TeX Live on the machine is not picked up by Linux, since Linux does not resolve .exe names.

Installing Klammertext

Follow linux_source_install.md at the Ubuntu prompt, from its first line. Everything on it applies: the packages by apt-get, the clone, the line in ~/.bashrc that sources runtime.env, the build, TeX Live by the bundled script, the verification. Nothing on that page is different inside WSL. On the machine this page was written on, the build took under a minute and TeX Live nine, and the engine's test suite passed as it does on Linux.

Keep the clone and your documents in the Linux file system, under your Linux home, not under /mnt/c. The Windows drives are mounted there and work, but every file operation crosses between the two systems, and a build or a PDF run on /mnt/c is several times slower.

Seeing the output from Windows

WSL has no browser or PDF viewer of its own, and it needs none. Windows sees the Linux file system as a network path, \\wsl.localhost\Ubuntu\, and Windows programs can open files there. From the Linux prompt, after ktext hello.kt -t html and ktext hello.kt -t pdf:

# at the Ubuntu prompt (type wsl in PowerShell to get there), not in PowerShell
explorer.exe "$(wslpath -w hello/index.html)"
explorer.exe "$(wslpath -w hello.pdf)"

wslpath -w turns a Linux path into the Windows form of the same file, and explorer.exe opens it with whatever Windows opens that kind of file with: your browser, your PDF viewer. The first time, Windows may ask which application to use. explorer.exe . opens the current Linux directory in Explorer, and from the Windows side the same files are in Explorer under "Linux" in the sidebar. (explorer.exe reports exit status 1 even when it succeeds; a script that needs a true status can use powershell.exe -NoProfile -Command "Start-Process \"$(wslpath -w hello.pdf)\"" instead.)

Editors

The Windows editors reach the Linux side, and the Linux editors are simply there.

Visual Studio Code, the case this page was written for. Install VS Code on Windows and its "WSL" extension (Microsoft's ms-vscode-remote.remote-wsl). Then, at the Linux prompt, in the directory you want to work in:

code .

The first time, this installs VS Code's Linux-side server into your Linux home and opens a VS Code window on Windows connected to it. The Klammertext extension is installed on that Linux side, once, from the package built in the clone:

cd ~/klammertext/doc/edit/vscode && ./make_vsix.sh && code --install-extension klammertext.vsix

Run from the Linux prompt, code --install-extension installs to the WSL side, where the extension then starts the Klammertext language server with the Linux python3; everything in doc/edit/vscode/README.md applies as on Linux. (Extensions installed on the Windows side of VS Code are a separate list and do not run in WSL windows.)

Emacs and Vim are Linux programs: sudo apt-get install emacs or vim, then the Emacs and Vim packages under doc/edit/ as on Linux.

Sublime Text and Notepad++ on Windows open the Linux files through \\wsl.localhost\Ubuntu\..., with their Klammertext packages (doc/edit/sublime/, doc/edit/notepadpp/) installed on the Windows side. The packages are self-contained: they highlight, and their commands -- matching delimiters, reindentation, table alignment, the delimiter check -- are Python programs that never run Klammertext itself, so the Linux side is not involved. Sublime Text runs them in its own interpreter. Notepad++'s Run commands, and the optional language server for Sublime Text, start python, which means a Python for Windows from python.org on the Path.

The container route

If you would rather not build anything, the prebuilt Klammertext images run inside WSL exactly as linux_container_install.md describes, since the Ubuntu WSL installs today runs systemd and therefore Docker's service: follow that page at the Ubuntu prompt, from apt-get install docker.io on. That was done on the machine this page was written on: the image, 2.4 GB with its TeX Live, pulled in about a minute, and its ktext made the page's web page and PDF, owned by the Linux user. Docker Desktop for Windows is the other way to run the same images; its engine is WSL 2 as well, and it has its own licence terms for larger companies.

Troubleshooting

wsl --install says virtualization is not enabled. WSL 2 needs the CPU's virtualization support turned on in the machine's firmware settings; the name varies (Intel VT-x, AMD-V, SVM). Turn it on and run the command again.

code . says the command is not found. VS Code's bin directory is put on the Windows Path by its installer; open a new WSL terminal after installing VS Code, so the Linux PATH picks it up.

A build or a PDF run is slow. The clone or the document is under /mnt/c. Move it under your Linux home.

The Ubuntu window asks for a username again. The distribution was reset or reinstalled; the setup creates a fresh Linux home, and Klammertext must be installed again inside it.