ack
ee8bcf5300
Assembled from development commit c3c40f6c8fca. Since 830b193: on Windows the
products carry Windows names (ktext.exe, klammertext.dll, document.dll,
reflect.dll) and the console's output code page is UTF-8 for a run; the
editor tooling works on Windows (VS Code, Sublime Text, Vim, with the
interpreter's name chosen by platform) and Notepad++ joins it
(doc/edit/notepadpp: a User Defined Language and two Run-menu commands);
a sixth install page, doc/install/windows_wsl_install.md, for Linux
inside WSL; the Windows page opens with the three routes and gains its
editor section, the PowerShell quoting and Path notes; the Linux page
installs OpenImageIO from the python3-openimageio package and verifies
with kdiag --machine; the README lists all six install pages. Linux and
macOS behaviour is unchanged.
6.6 KiB
Klammertext on Windows through the Windows Subsystem for Linux
This page is for someone who works in Linux by habit and has a Windows
machine to work on. 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.
There are two other ways to have Klammertext on Windows: as native
Windows programs built from source (windows_source_install.md), and
from 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 can open the Linux files
through \\wsl.localhost\Ubuntu\... and highlight them with their
Klammertext packages (doc/edit/sublime/, doc/edit/notepadpp/); their
commands that run the shared core would run the Windows python, so for
those two editors the native Windows installation is the better fit.
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.