vm: make boot-check work on a QEMU without virglrenderer, and write a real PNG

Two things found by actually running it, which had evidently not happened on this
machine before: QEMU is not in this image and never has been. The vm/ tooling was
written on the old Aurora host, which shipped it, so the gate that SETUP §3 and
DESIGN §9.4 describe as the thing standing between a build and the laptop could
not run at all here. A green build says nothing about whether the next step works.

Installing it is not the whole story either. Homebrew's bottle is built without
virglrenderer, so it offers virtio-vga but not virtio-vga-gl, and the script
failed on the -device line with an error that pointed at nothing useful.

boot-check.sh now checks for qemu up front, and picks the 3D pair when the build
offers it and degrades to 2D with a loud warning when it does not. The fallback
is worth having rather than a hard failure: tuigreet is an fbcon TTY program, so
the whole boot path through greetd is genuinely exercised and the screenshot means
what it says. niri is what is lost — it exits immediately without a render node —
so the warning states plainly that a green 2D run proves the image boots to a
login prompt and nothing more.

Separately, screendump needs an explicit format. Without one it emits a PPM
regardless of the filename, so vm/output/greeter.png has always been a 3.1MB PPM
that no image viewer would open. It is now a 7.1KB PNG.

SETUP §3 gains the prerequisite and a table of what each QEMU actually proves.

Author: mark-iid

SETUP.md

@@ -74,6 +74,26 @@ verification step to remember.
 The laptop is not touched until a VM boots this image to a usable niri session (§9).
 bootc-image-builder is **rootful**, so the disk build needs `sudo`; QEMU boot does not.
 
+**QEMU is a prerequisite and is NOT in this image.** It never has been — the `vm/`
+tooling was written on the old Aurora host, which shipped it, and the gap went
+unnoticed because a green build says nothing about whether the gate that follows it
+can run. Install it before the first VM test on a fresh machine.
+
+Which QEMU you install decides how much of the test you get:
+
+| | greeter check | niri renders |
+|---|---|---|
+| `brew install qemu` | yes | **no** |
+| Fedora `qemu-system-x86-core` + `qemu-device-display-virtio-vga-gl` | yes | yes |
+
+Homebrew's bottle is built without virglrenderer, so it has `virtio-vga` (2D) but no
+`virtio-vga-gl`. `boot-check.sh` detects that, falls back to 2D and says loudly what
+is lost. The fallback is still worth running — tuigreet is an fbcon TTY program and
+needs no compositor, so the whole boot path through greetd is genuinely exercised
+and the screenshot means what it says. What you do **not** get is niri: it exits
+immediately with no render node, so a green 2D run is proof the image boots to a
+login prompt and nothing more. Do not read it as proof of a working desktop.
+
 ```
 bash vm/export-image.sh          # refresh vm/kb3lyb-sway.oci from the CURRENT image (do this first!)
 sudo bash vm/build-qcow2.sh      # build the qcow2 (rootful)
@@ -89,8 +109,10 @@ sudo bash vm/build-qcow2.sh
 bash vm/retest.sh verify
 ```
 
-> QEMU must use `virtio-vga-gl` + `egl-headless` (boot-check.sh does) or niri exits
-> for lack of a GPU render node — a VM artifact, not an image bug.
+> niri needs `virtio-vga-gl` + `egl-headless` to have a GPU render node; without one
+> it exits immediately. That is a VM artifact, not an image bug. `boot-check.sh`
+> picks the 3D pair when the QEMU build offers it and degrades to 2D with a warning
+> when it does not — see the table above for what each mode actually proves.
 
 ---
 

vm/boot-check.sh

@@ -37,6 +37,35 @@ if [ "${1:-}" = "--shutdown" ]; then
 fi
 
 [ -n "$QCOW" ] || { echo "!! no qcow2 in vm/output — run vm/build-qcow2.sh first"; exit 1; }
+
+# QEMU is NOT in this image and never has been — the vm/ tooling was written on the
+# old Aurora host, which shipped it. It is a prerequisite you install yourself; see
+# SETUP §3.
+command -v qemu-system-x86_64 >/dev/null 2>&1 || {
+  echo "!! qemu-system-x86_64 not found. See SETUP §3 — it is not part of this image."
+  exit 1
+}
+
+# virtio-vga-gl needs a QEMU built against virglrenderer, and not every build is.
+# Homebrew's bottle is not: it has virtio-vga (2D) only. Rather than fail on the
+# -device line with an opaque error, degrade deliberately and say what is lost.
+#
+# What survives 2D: the whole boot path through greetd to the tuigreet greeter,
+# which is what the screenshot below asserts — tuigreet is an fbcon TTY program and
+# needs no compositor. What does NOT: niri itself, which exits immediately with no
+# renderer, so the "log in over VNC and watch it render" step is unavailable.
+if qemu-system-x86_64 -device help 2>/dev/null | grep -q '"virtio-vga-gl"'; then
+  VGA_DEVICE=virtio-vga-gl
+  DISPLAY_BACKEND=egl-headless
+else
+  VGA_DEVICE=virtio-vga
+  DISPLAY_BACKEND=none
+  echo "!! This QEMU has no virtio-vga-gl (built without virglrenderer)."
+  echo "!! Falling back to 2D. The greeter check below is still valid; niri will NOT"
+  echo "!! render, so do not read a successful run as proof of a working desktop."
+  echo "!! For the full check install Fedora's qemu-device-display-virtio-vga-gl."
+fi
+
 rm -f "$QMP"
 
 echo ">>> Booting $QCOW (KVM, VNC 127.0.0.1:590${VNC_DISPLAY}, ssh localhost:${SSH_PORT})"
@@ -54,7 +83,7 @@ rm -f vm/serial.sock
 qemu-system-x86_64 \
   -machine q35,accel=kvm -cpu host -m 4096 -smp 4 \
   -drive file="$QCOW",if=virtio,format=qcow2 \
-  -device virtio-vga-gl -display egl-headless -vnc 127.0.0.1:${VNC_DISPLAY} \
+  -device "$VGA_DEVICE" -display "$DISPLAY_BACKEND" -vnc 127.0.0.1:${VNC_DISPLAY} \
   -netdev user,id=n0,hostfwd=tcp:127.0.0.1:${SSH_PORT}-:22 -device virtio-net,netdev=n0 \
   -device virtio-rng-pci \
   -qmp unix:"$QMP",server,nowait \
@@ -65,7 +94,9 @@ echo ">>> QEMU pid $(cat "$PIDF"). Waiting 75s for boot + niri session..."
 sleep 75
 
 echo ">>> Capturing framebuffer screenshot -> $SHOT"
-qmp "{\"execute\":\"screendump\",\"arguments\":{\"filename\":\"$PWD/$SHOT\"}}"
+# format is REQUIRED. Without it screendump emits a PPM regardless of the file
+# extension, so $SHOT was a PPM called .png that no image viewer would open.
+qmp "{\"execute\":\"screendump\",\"arguments\":{\"filename\":\"$PWD/$SHOT\",\"format\":\"png\"}}"
 sleep 2
 ls -lh "$SHOT" 2>&1