wayray/vm/README.md

WayRay VM Testing Setup

Visual testing environment for the WayRay compositor using an Arch Linux aarch64 VM on macOS Apple Silicon via UTM.

Prerequisites

• MacBook with Apple Silicon (M1/M2/M3/M4)
• UTM installed (free download from website)

Create the VM

1. Download the Arch Linux ARM ISO

Go to https://archlinux.org/download/ and download the latest aarch64 ISO image.

2. Create a new VM in UTM

1. Open UTM, click Create a New Virtual Machine
2. Select Virtualize
3. Select Linux
4. Browse to the downloaded ISO
5. Configure hardware:
   • CPU: 4 cores
   • RAM: 8192 MB (8 GB)
6. Configure storage:
   • Disk size: 30 GB
7. Give it a name (e.g., "WayRay Dev")
8. Click Save

The VM defaults to VirtIO display and shared networking, which is what we need.

3. Install Arch Linux

1. Boot the VM from the ISO
2. Run archinstall
3. Recommended settings:
   • Mirrors: Select your region
   • Disk configuration: Use entire disk, ext4
   • Bootloader: systemd-boot
   • Profile: Minimal
   • User: Create a user with sudo privileges
   • Network: NetworkManager
4. Complete the installation and reboot
5. Remove the ISO from the VM's CD drive in UTM settings

4. Run the setup script

Boot into the installed system and log in, then:

# Install git first (needed to clone the repo)
sudo pacman -S git --noconfirm

# Clone WayRay and run the setup script
git clone <your-wayray-repo-url> ~/wayray
bash ~/wayray/vm/setup.sh

# Reboot to apply auto-login and start Sway
sudo reboot

Note: the script skips cloning if ~/wayray already exists, so passing the repo URL to setup.sh is only needed if you haven't cloned yet.

Testing the Compositor

After reboot, the VM auto-logs in and starts Sway. A foot terminal opens automatically.

# Build and run the compositor
cd ~/wayray
cargo run --bin wrsrvd

The wrsrvd window opens inside Sway. Note the Wayland socket name from the log output (e.g., wayland-1).

Open another terminal with Super+Return, then:

# Launch a client inside the compositor
WAYLAND_DISPLAY=wayland-1 foot

A foot terminal should appear inside the wrsrvd window. You can:

• Type in it (keyboard input works)
• Click on it (pointer input works)
• See it render (compositor rendering works)

Keyboard Shortcuts (Sway)

Shortcut	Action
Super+Return	Open a new terminal
Super+Shift+Q	Close focused window
Super+Shift+E	Exit Sway

Troubleshooting

Sway fails to start

If Sway fails with a GPU error, the VirtIO GPU may not be working with Apple Virtualization.framework. Try switching UTM to QEMU backend:

1. Shut down the VM
2. In UTM, edit the VM settings
3. Under System, uncheck "Use Apple Virtualization"
4. Under Display, ensure VirtIO GPU is selected
5. Boot again

Black screen after reboot

The auto-login or Sway autostart may have failed. Switch to TTY2 with Ctrl+Alt+F2, log in, and check:

# Check if seatd is running
systemctl status seatd

# Check if user is in seat group
groups

# Try starting Sway manually
sway

Build fails

# Make sure Rust is up to date
rustup update

# Check Rust version (need 1.85+ for edition 2024)
rustc --version

# Retry
cargo build --workspace