Problem
For developers who maintain a Linux distribution, the desktop itself was the last black box. How does a window actually get drawn? How does input reach an app? How does a compositor talk to the kernel's DRM subsystem?
The community wanted to answer those questions in Rust by writing a compositor from scratch on Smithay and to build it the way they build everything else: modularly, testably, and shaped by the community's own keybindings and theme.
Goals
Compositor Core
A Smithay-based compositor binary with auto-selecting Winit (nested) and DRM (real session) backends.
Modular Workspace
Five crates compositor, window, config, IPC, launcher so each concern is independently testable.
Configuration
TOML config with keybindings and theme, shipped with a default config users can copy.
Testability
QEMU VM scripts, cargo test, and strict clippy (-D warnings) keep experimental code honest.
Architecture
┌──────────────────────────────────────────────────────────────────────────┐ │ CODEVERSE COMPOSITOR │ ├──────────────────────────────────────────────────────────────────────────┤ │ Workspace crates → Backends → Config │ │ ┌────────────────────┐→ ┌───────────────────┐→ ┌──────────────────────┐ │ │ │compositor bin │→ │Winit (nested) │→ │config.toml │ │ │ │window/layout │→ │DRM (TTY) │→ │keybindings │ │ │ │config + IPC │→ │libinput · libseat │→ │theme │ │ │ │launcher (.desktop) │→ │libdrm · GBM/EGL │→ │default config │ │ │ └────────────────────┘→ └───────────────────┘→ └──────────────────────┘ │ │ qemu-test.sh · deploy-to-vm.sh · cargo test --workspace │ └──────────────────────────────────────────────────────────────────────────┘
The project is a Rust workspace where every responsibility is its own crate. codeverse-compositor hosts the binary and Smithay event loop; codeverse-window owns layouts and the workspace tree; codeverse-config parses TOML into keybindings and themes; codeverse-ipc defines the inter-process protocol; and codeverse-launcher discovers applications from .desktop files. At runtime the binary auto-selects its backend Winit for nested sessions inside an existing desktop, DRM for a real TTY session.
Core Compositor
Smithay event loop, rendering, and output handling live in the binary crate; debug with RUST_LOG=info.
Window Management
codeverse-window implements layouts and a workspace tree, separating the policy (where windows go) from the protocol (how they're shown).
Config & IPC
codeverse-config parses ~/.config/codeverse-compositor/config.toml for keybindings and theme; codeverse-ipc types the control channel.
Launcher & Testing
codeverse-launcher parses .desktop entries for app discovery; qemu-test.sh and deploy-to-vm.sh validate real sessions in a VM.
Key Features
Dual Backends
Run nested inside any desktop (Winit) for development, or on a clean TTY (DRM) for a real compositing session auto-selected.
TOML Configuration
Keybindings and theme are plain TOML with a shipped default config, so the compositor adapts to the community's workflow.
Workspace Tree
codeverse-window manages workspaces and layouts as a tree, keeping tiling behavior explicit and extensible.
VM Test Harness
qemu-test.sh boots a Linux ISO with the compositor in a shared folder, and deploy-to-vm.sh pushes builds into a running VM.
Tech Stack
Rust (edition 2021)
Memory-safe systems language for DRM and input handling.
Smithay
The Wayland compositor toolkit the project builds on.
libinput · libseat
Input handling and seat/session management.
libdrm · GBM/EGL
Kernel DRM access and GPU buffer management for rendering.
TOML
Human-friendly configuration format for keybindings and themes.
Results
CodeVerse Compositor is the org's frontier systems project. The crate split means contributors can land meaningful work a config parser, a launcher, an IPC type without touching the compositor core, which makes a notoriously intimidating codebase approachable. The QEMU harness means each milestone is verifiable without burning hardware.
Challenges & Trade-offs
Challenge
Smithay and the DRM stack need system libraries whose package names vary wildly between distros.
Solution
The README lists the exact libraries (libxkbcommon, libinput, libseat, libdrm + GBM/Mesa/EGL) with a note to install -dev/-devel headers on build errors.
Challenge
DRM sessions require device permissions, seats, and groups that differ per machine.
Solution
Nested Winit mode is the recommended starting point; DRM notes cover video/input groups and seat setup, with a qemu-test.sh path for safe iteration.
Challenge
A compositor's correctness is hard to verify without a real session.
Solution
QEMU scripts boot a live ISO with the binary shared into the VM, and deploy-to-vm.sh pushes iterations into a running test session.
Implementation Highlights
Crate-Split Architecture
Five crates keep compositor internals, config, IPC, and launcher independently testable and approachable.
Nested-First Development
Winit backend means contributors develop and debug inside their existing desktop before ever touching DRM.
Strict Quality Gates
cargo clippy -D warnings and cargo test --workspace are part of the contributor workflow.
Lessons Learned
Compositor engineering demystifies the desktop after DRM and input handling, no systems project feels out of reach.
Nested mode is the right on-ramp: iterate in Winit, then test real sessions in QEMU.
A modular workspace turns a monolith-scale problem into beginner-sized contributions.