153 lines
6.6 KiB
Markdown
153 lines
6.6 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
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`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|