Smithay — Build Custom Wayland Compositors in Rust

Introduction

Smithay is a Rust crate that provides the foundational building blocks for creating Wayland compositors. Rather than being a compositor itself, Smithay is a library that handles the complex Wayland protocol implementation, input device management, and rendering infrastructure so that developers can focus on implementing their desired window management behavior. The project includes Anvil, a reference compositor that demonstrates how to use the library.

What Smithay Does

• Implements Wayland protocol handling including core protocols and common extensions
• Provides backend abstractions for DRM/KMS direct rendering and winit-based windowed sessions
• Manages input devices through libinput integration with configurable event processing
• Offers rendering helpers for OpenGL/EGL and Vulkan-based compositor output
• Handles buffer management, surface composition, and damage tracking for efficient rendering

Architecture Overview

Smithay is structured as a modular Rust library with several key subsystems. The wayland module implements protocol message parsing and dispatch using the wayland-rs bindings. The backend module abstracts hardware access with DRM/KMS for direct display output and winit for development in a window. Input is handled through a libinput abstraction layer. The desktop module provides higher-level window and workspace management primitives. These components are designed to be used independently, allowing compositor authors to pick only what they need.

Self-Hosting & Configuration

• Smithay is a library, not a standalone application — it is used by adding it as a dependency in a Rust project
• The Anvil example compositor can be built and run with cargo run --example anvil for testing
• Backend selection (DRM/KMS or winit) is handled programmatically based on the runtime environment
• Protocol extensions can be enabled or disabled by including or excluding Smithay feature flags in Cargo.toml
• Logging is integrated via the slog or tracing crate for debugging compositor behavior

Key Features

• Written in Rust with memory safety guarantees that prevent common compositor security vulnerabilities
• Modular design allowing developers to use only the components they need
• Includes Anvil, a fully functional reference compositor that serves as both example and testing tool
• Supports both DRM/KMS backend for production use and winit backend for development convenience
• Active maintenance with regular updates tracking new Wayland protocol extensions

Comparison with Similar Tools

• wlroots: C library for Wayland compositors; Smithay provides similar functionality in Rust with memory safety
• libweston: Weston's compositor library in C; Smithay offers more modular and flexible composition
• cosmic-comp: System76's compositor built on Smithay, demonstrating real-world library usage
• Louvre: C++ Wayland library; Smithay leverages Rust's ownership model for safer resource management

FAQ

Q: Is Smithay a compositor I can install and use? A: No, Smithay is a library for building compositors. The included Anvil example is a functional compositor but is intended as a reference, not a production desktop.

Q: What compositors are built with Smithay? A: Notable projects using Smithay include COSMIC (System76's desktop environment compositor) and several community compositor projects.

Q: Do I need to understand Wayland protocols to use Smithay? A: A basic understanding of Wayland concepts helps, but Smithay abstracts much of the protocol complexity. The Anvil example provides a practical starting point.

Q: Does Smithay support XWayland? A: Yes, Smithay includes XWayland integration for running X11 applications within a Smithay-based compositor.

Sources

• Repository: https://github.com/Smithay/smithay
• Documentation: https://smithay.github.io/smithay/