The guide for the one command: docs/trying-it.md says what a machine needs to
run the demo guest, with the lines of .wslconfig and of the NixOS-WSL
configuration for Windows 11, how to check it with `run-kde --doctor`, what the
command does and shows, the key bindings to try, how the GPU path is chosen, how
to open Windows' own RDP client, how long the first run takes (measured on a
machine with 32 cores and an empty store, by number of cores, with an estimate
for a WSL 2 machine and its caveats), how to start again, how to work on
komorebi in the guest, and what to do when something is wrong, by symptom. It
ends with what was run and what was not: nothing has been run on WSL 2 yet. The
README has a section and a link, and the user guide index a line.
DESIGN.md has four entries. Two record what I decided and want: the QEMU window
first and RDP second, and the GPU wherever the host has one. Two say that a
reason was not written down, for QEMU with KVM and not Hyper-V and for sharing
the password by a directory, and what is known that bears on each; the password
entry also says why a password is made for each user. PLATFORM.md has a section
for WSL 2 with what the command expects, a table of the probe results still to
be recorded (KVM, display, GPU, RDP, resources, virtiofs), and what is known of
virtiofsd without WSL 2.
Starting the demo guest by hand takes a build, a state directory, a password, a
key, the sizes of the machine and the right arguments for its display, and a
mistake shows up as an error from QEMU a minute later. `run-kde` does all of it:
`nix run .#run-kde` (or `just run-kde`) checks the machine, builds the guest
when its runner is not in the store, with the build log shown, makes the state
directory with a sparse disk, a random RDP password and an ssh key (all mode
0600, none of it in the Nix store), and starts the runner with KVM, the memory
and cores the machine has, the repository at /repo, and the state directory at
/run/run-kde. It prints a banner with the RDP address and password, the ssh
command, how to quit, and which graphics mode it chose and why.
`--doctor` prints every prerequisite as a tick, a cross or a warning with the
exact fix: WSL 2 or not, KVM and its group, nested virtualization, virtiofs (a
virtiofsd started as the user with the options of the guest's runner must serve
a directory, since the guest mounts its /nix/store through one; /dev/fuse is
only a warning), memory, disk, WSLg, Windows interop, the GPU and the OpenGL of
the host, and the lines of .wslconfig. It exits with 1 when something is a
cross, which includes a missing KVM unless `--tcg` allows software emulation.
The GPU is used when the display is a window, the host has a GPU device and its
OpenGL is not llvmpipe, and `--gpu on|off` overrides it; on WSL 2, `--rdp` opens
mstsc with a credential that lasts as long as the run.
The script reads the machine through variables, so `--dry-run` and `--doctor`
can be tested against machines that a check makes up: `run-kde-dry-run` and
`run-kde-doctor` compare their output with the texts in nix/tests/run-kde, and
the package, which shellchecks the script when it is built, is a check too.
A person who wants to see komorebi tile windows should not have to configure a
machine first. `run-kde-x86_64` and `run-kde-aarch64` are the session guest with
a demo on it: the NixOS module configures komorebi from a typed `config` (eight
workspaces, borders, animation) and the sample skhd bindings, and at login the
guest opens two Konsole windows, Kate and Dolphin, which komorebi tiles, and a
cheat sheet window that it leaves alone, with the key bindings, `komorebic`
commands to try, what KWin draws with, and the output of `komorebic check`.
The closure is the same for everyone. No password or key is in it: the host
shares a directory, which the guest mounts at /run/run-kde, and a unit copies
the RDP password and the ssh public key from it, since the files can belong to a
user of the host who is not the guest user. krdp.nix reads the password from the
file that `komorebi.krdp.passwordFile` names when it exists. The display device,
the port forwards, the memory and whether to insist on KVM are left to the
environment of the runner, so that one closure and one disk run with a software
virtio-vga or with a virtio-vga-gl that renders on the host GPU. The module is a
separate file that does not import plasma-vm.nix, so that a VM suite can put it
on the session node.
plasma-guests-eval asserts the same of the demo guests.
The Plasma guests were made for an Apple silicon Mac only: the flake fixed the
guest to aarch64-linux and the host of QEMU to the Mac. `mkPlasmaGuest` now
takes the system of the guest and the packages of the machine that runs QEMU,
and the flake has the two QEMU guests for a Linux machine with KVM as well:
plasma-vm-x86_64 and plasma-vm-session-x86_64, and the same pair for aarch64
(plasma-vm-aarch64, plasma-vm-session-aarch64). The three guests of a Mac keep
their names and are built from the same instructions.
An x86_64 machine has a VGA that QEMU adds unless it is told not to, which would
be a second display next to the virtio-gpu that KWin draws on. An x86_64 guest
therefore gets virtio-vga, a virtio-gpu that is also the VGA, and `-vga none`;
an aarch64 guest has no VGA and keeps virtio-gpu-pci.
plasma-guests-eval evaluates every guest and asserts what each is for: the
architecture of the guest, the system of its host, KVM or HVF, and one display
device. docs/dev/utm.md says which guest is for which host and how to build and
run one on a Linux machine; the README and CONTRIBUTING say that there are
guests for both.
The VM tests boot a machine, run a scenario and power it off. Trying a change by
hand needs a Plasma session that stays up, and on a Mac, one that renders on its
GPU.
nix/dev/plasma-vm.nix is a guest for QEMU on an Apple silicon Mac, headless or
with a Plasma session that logs in by itself, and nix/dev/plasma-utm.nix is that
session as a disk image for UTM, whose QEMU renders on the Mac's GPU. They are
nixosConfigurations of the flake, and install komorebi with services.komorebi
from the flake's packages. They carry no key, password or configuration of
anyone's: the console logs in by itself, ssh takes the keys a user puts in the
guest, and the RDP password is a file in the guest. plasma-guests-eval evaluates
the three on every system.
nix/dev/krdp.nix runs KRDP in the session, and the slow suite vm-rdp runs the
same unit in the session node: it waits for a password and listens once it has
one, FreeRDP's client is let in with the password and not with another, and the
picture the client gets on an X server of its own is the display. FreeRDP
decodes KRDP's H.264 with OpenH264 and shows nothing, so the guests' client is
built without it and decodes with FFmpeg. Keys over RDP stay unverified, since
no client can script them against KRDP; PLATFORM.md says so and what the suite
checks.
docs/dev/utm.md says how to build and run the guests, and what a builder has to
be.
LGUG2Z