wayray/vm/README.md

WayRay VM Testing Setup

Visual testing environment for the WayRay compositor using an Ubuntu 22.04 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. Get the Ubuntu 22.04 image from the UTM Gallery

1. Open UTM
2. Click + to create a new VM
3. Select Browse UTM Gallery...
4. Find and download Ubuntu 22.04
5. The VM is pre-configured with reasonable defaults

2. Adjust VM settings (optional)

The gallery image works out of the box, but for faster Rust compilation:

1. Select the VM in UTM, click the settings icon
2. Under System:
   • CPU: 4 cores (or more)
   • RAM: 8192 MB (8 GB)

3. Boot and run the setup script

1. Start the VM and log in (gallery image credentials are shown in UTM)
2. Open a terminal and run:

# Clone WayRay and run the setup script
git clone https://github.com/CloudNebulaProject/wayray.git ~/wayray
bash ~/wayray/vm/setup.sh

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

The setup script installs all dependencies (Wayland libs, Mesa, X11, Rust), builds WayRay, and configures auto-login.

Testing the Compositor

The Winit backend can run under either X11 or Wayland. Under UTM, X11 is more reliable — virgl's EGL surface handling has issues with Sway/Wayland in virtualized environments.

Option A: X11 (recommended for UTM)

Start an X session:

startx openbox-session

Then from a TTY (Ctrl+Alt+F2) or an xterm in the Openbox session:

export DISPLAY=:0
cd ~/wayray
cargo run --bin wrsrvd

The wrsrvd window opens inside X11. Note the Wayland socket name from the log output (e.g., wayland-2). In another xterm:

WAYLAND_DISPLAY=wayland-2 xterm

An xterm should appear inside the wrsrvd window.

Option B: Sway (if GPU supports it)

If you have a working Wayland-capable GPU (e.g., bare metal or a VM with good virgl support):

sway

Then in the foot terminal:

cd ~/wayray
cargo run --bin wrsrvd

Open another terminal with Super+Return, then:

WAYLAND_DISPLAY=wayland-2 foot

What to verify

• A client window appears inside the wrsrvd compositor window
• Typing works (keyboard input reaches the client)
• Clicking works (pointer input reaches the client)
• The window renders correctly (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

Openbox: Right-click the desktop for a menu.

Troubleshooting

EGL errors under Sway (BAD_SURFACE, BadAlloc)

This is a known issue with virgl + UTM. Use the X11 path instead (Option A above).

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

Missing libraries

If cargo build or cargo run fails with missing libraries:

sudo apt-get install -y libwayland-dev libegl1-mesa-dev libgles2-mesa-dev \
    libxkbcommon-dev libxkbcommon-x11-0