CloudNebulaProject/wayray
1
0
Fork 0
mirror of https://github.com/CloudNebulaProject/wayray.git synced 2026-04-10 21:20:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
wayray/vm
History
Till Wegmueller 547d62ca1e Fix VM setup: add X11 fallback, libxkbcommon-x11 
- Add libxkbcommon-x11-0, xorg, xinit, openbox, xterm packages
- Document X11 as primary path (virgl EGL broken under UTM)
- Keep Sway as Option B for non-virtualized environments
2026-04-07 14:31:12 +02:00
..
README.md Fix VM setup: add X11 fallback, libxkbcommon-x11 2026-04-07 14:31:12 +02:00
setup.sh Fix VM setup: add X11 fallback, libxkbcommon-x11 2026-04-07 14:31:12 +02:00

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