# Smithay — Build Custom Wayland Compositors in Rust

> A Rust library for building custom Wayland compositors. Smithay provides the building blocks for creating compositor implementations, handling Wayland protocol details, input processing, and rendering while letting developers focus on window management logic.

## Install

Save in your project root:

# Smithay — Build Custom Wayland Compositors in Rust

## Quick Use

Add Smithay to your Rust project: `cargo add smithay`. Explore the included `anvil` example compositor in the repository for a working reference implementation.

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-19bf0725
Author: AI Open Source