Phase 0.5: VM Testing Setup — Design Spec

Goal

Create a reproducible Arch Linux aarch64 VM setup for visually testing the WayRay compositor on a MacBook Air M4 via UTM. This lets the developer see wrsrvd rendering Wayland clients in a real graphical session.

Context

Phase 0 built a working Smithay compositor (wrsrvd) that uses the Winit backend. Winit opens a window inside an existing display server (X11 or Wayland). The development host is a headless x86 Linux system with no display — visual testing requires a separate machine with a GPU and display.

The developer's local machine is an Apple Silicon MacBook Air (M4). UTM provides native aarch64 Linux VMs on macOS using Apple's Virtualization.framework.

Architecture

MacBook Air M4 (macOS)
  └── UTM VM (Arch Linux aarch64)
        └── Sway (minimal Wayland compositor / session host)
              └── wrsrvd window (WayRay compositor via Winit backend)
                    └── foot terminal (Wayland client inside wrsrvd)

Sway serves only as the Wayland session host so Winit has a display to open a window in. The wrsrvd window is where the actual compositor output appears. Wayland clients (like foot) connect to wrsrvd's socket and render inside its window.

Deliverables

1. `vm/README.md` — UTM Setup Guide

Short instructions covering:

Download: Arch Linux ARM ISO from archlinux.org
Create VM in UTM:
- Type: Virtualize (Apple Virtualization.framework)
- CPU: 4 cores
- RAM: 8 GB
- Disk: 30 GB
- Display: VirtIO GPU
- Network: Shared/NAT
Boot and install Arch: Use archinstall for a minimal install (no desktop environment)
Run setup script: bash vm/setup.sh
Reboot: VM auto-logs in, starts Sway
Test: How to launch wrsrvd and connect a client

2. `vm/setup.sh` — Provisioning Script

Idempotent script run as a regular user (uses sudo where needed). Steps:

System update
```
sudo pacman -Syu --noconfirm
```
Install packages
- Build tools: base-devel
- Wayland stack: wayland, wayland-protocols, libxkbcommon
- Graphics: mesa (EGL/OpenGL for GlesRenderer)
- Session: sway, seatd, foot
- Tools: git, openssh
Enable services
- sudo systemctl enable --now seatd
- Add user to seat group
Install Rust
- rustup via official installer
- Stable toolchain (must support edition 2024 — Rust 1.85+)
Clone and build WayRay
- git clone <repo-url> into ~/wayray (URL passed as argument or prompted)
- cargo build --workspace
Configure auto-login on TTY1
- systemd getty override for automatic login
- .bash_profile starts Sway on TTY1

Write Sway config

# ~/.config/sway/config
set $mod Mod4
output * bg #333333 solid_color
default_border none
bindsym $mod+Return exec foot
exec foot

Each step checks whether it's already complete before running (idempotent).

3. No additional project code changes

The existing wrsrvd binary works as-is in this setup. No code modifications needed.

VM Specs

Setting	Value	Rationale
Type	Virtualize	Native aarch64 via Apple Virtualization.framework
CPU	4 cores	Rust compilation parallelism
RAM	8 GB	Rust compiler is memory-hungry
Disk	30 GB	Arch + Rust toolchain + cargo cache + Mesa
Display	VirtIO GPU	Required by Sway for GPU context (Mesa virgl driver). If Virtualize mode fails, fall back to UTM's QEMU backend.
Network	Shared/NAT	Pacman, git clone, rustup

Test Flow

Boot VM — auto-login to TTY1 — Sway starts automatically
foot terminal opens (autostarted by Sway config)
Run: cd ~/wayray && cargo run --bin wrsrvd
wrsrvd window opens inside Sway
Note the socket name from the log output
In the foot terminal: WAYLAND_DISPLAY=<socket> foot
A second foot terminal appears inside the wrsrvd window
Verify: typing works, clicking works, rendering is correct

Success Criteria

VM boots to a Sway session without manual intervention
cargo build --workspace succeeds inside the VM
wrsrvd opens a Winit window inside Sway
A Wayland client (foot) renders inside the wrsrvd window
Input (keyboard, mouse) reaches the client through wrsrvd

Out of Scope

Automated screenshot testing or CI integration
x86 VM support (future phase)
Headless/remote testing (Phase 1+)
GPU passthrough or hardware acceleration
illumos VM testing

4.5 KiB Raw Blame History