Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/smithay/wayland-rs/llms.txt

Use this file to discover all available pages before exploring further.

wayland-rs is a workspace of Rust crates that implement the Wayland display protocol for both clients (applications) and servers (compositors). The suite spans from raw FFI bindings to a high-level, type-safe API generated directly from Wayland XML protocol specifications.

Client Quickstart

Connect to a Wayland server and handle events in minutes with wayland-client.

Server Quickstart

Build a Wayland compositor using wayland-server with typed dispatch.

Architecture Overview

Understand the crate stack from raw FFI up to high-level protocol types.

Protocol Extensions

Use XDG Shell, wlroots, Plasma, and custom protocol extensions.

​
What’s in the workspace

wayland-rs hosts 12 crates, organized into three layers:

wayland-client

High-level client-side API: Connection, EventQueue, Dispatch.

wayland-server

High-level server-side API: Display, GlobalDispatch, Resource.

wayland-protocols

Pre-generated bindings for all official Wayland protocol extensions.

wayland-backend

Low-level protocol logic with pure-Rust and system backends.

wayland-scanner

Proc-macros that generate Rust code from XML protocol specs.

wayland-cursor

Load cursor images from system XCursor themes.

​
Getting started

1

Add the crates you need

Add wayland-client or wayland-server to your Cargo.toml depending on whether you are writing a client application or a compositor.
Cargo.toml
[dependencies]
wayland-client = "0.31"
wayland-protocols = { version = "0.32", features = ["client"] }
2

Connect to a Wayland server (client side)

Use Connection::connect_to_env() to open a connection using the environment’s socket path, then create an EventQueue to drive dispatch.
use wayland_client::{Connection, protocol::wl_registry};
let conn = Connection::connect_to_env().unwrap();
let mut eq = conn.new_event_queue();
3

Implement Dispatch for your state

Your application state implements Dispatch<Object, UserData> for every Wayland object it handles. The library routes incoming events to the right implementation automatically.
4

Run the event loop

Call event_queue.blocking_dispatch(&mut state) (or integrate with an async runtime / calloop) to process events until your application exits.

​
Requirements

wayland-rs requires Rust 1.86 or later. If you enable the system feature to link against installed libwayland libraries, version 1.15 or later of the wayland system libraries is required.

​
Community & support

Join the Matrix chatroom at #wayland-rs:matrix.org for questions and discussion.

Build docs developers (and LLMs) love

Get started for freeTalk to us