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.

The core Wayland protocol defines a handful of primitives — surfaces, outputs, seats, and buffers — but nearly everything that a real desktop application or compositor needs lives in protocol extensions. These are additional XML specifications that define supplementary globals and interfaces: window management, screen capture, fractional scaling, color management, clipboard control, and much more. wayland-rs ships a family of crates that provide pre-generated, type-safe Rust bindings for these extensions. Rather than running wayland-scanner yourself, you add the appropriate crate as a dependency, opt into the features you need, and the client-side or server-side types are ready to use. Every protocol module exposes a client sub-module (gated by the client feature) and a server sub-module (gated by the server feature), matching the same pattern used in wayland-client and wayland-server.

​
Protocol crates

wayland-protocols

The official extensions from the wayland-protocols repository. Contains stable, staging, and unstable tiers covering XDG shell, viewporter, presentation-time, Linux DMA-BUF, fractional scale, and more.

wayland-protocols-wlr

Bindings for the wlr-protocols repository maintained by the wlroots project. Includes layer-shell, screencopy, output management, and gamma control.

wayland-protocols-plasma

Bindings for plasma-wayland-protocols, the KDE project’s collection of Plasma-specific extensions such as blur, shadow, DPMS, and screencast.

wayland-protocols-misc

Orphaned or de-facto protocols with no official home — GTK primary selection, virtual keyboard, and input method v2 — that are still widely used in the ecosystem.

wayland-protocols-experimental

Protocols under official evaluation that are not yet recommended for production use: experimental session management, input method, and text input extensions.

Custom protocols

Use wayland-scanner proc-macros to generate bindings from any Wayland XML specification file.

​
Adding a protocol crate to your project

Each crate follows the same convention. Add it to Cargo.toml and select at least one of the client or server features. You typically want wayland-client or wayland-server as a direct dependency too, because the generated types reference their traits. 
[dependencies]
wayland-client = "0.31"
wayland-protocols = { version = "0.32", features = ["client"] }

​
Protocol stability tiers

The wayland-protocols crate organises its contents into three tiers that reflect how mature a protocol specification is. Understanding the differences matters when deciding which protocols to rely on in production code.
Stable protocols have gone through the full wayland-protocols review process and are considered production-ready. Their interfaces will not change in a backward-incompatible way. Examples include xdg-shell, linux-dmabuf, viewporter, presentation-time, and tablet-v2. These are available unconditionally — no Cargo feature flag is required.
# Stable protocols need no extra features
wayland-protocols = { version = "0.32", features = ["client"] }
You can combine feature flags freely. A compositor that needs staging session-lock and legacy unstable pointer-constraints can use features = ["server", "staging", "unstable"] in a single dependency declaration.

​
Module layout inside each crate

Within wayland-protocols, protocols are grouped into four top-level modules:
ModulePurpose
wayland_protocols::xdgWindow management protocols (XDG Shell, XDG Output, XDG Decoration, etc.)
wayland_protocols::wpGeneral-purpose protocols (presentation-time, viewporter, linux-dmabuf, tablet, etc.)
wayland_protocols::extMiscellaneous protocols that don’t fit the other categories (idle-notify, session-lock, etc.)
wayland_protocols::xwaylandProtocols specifically for the XWayland compatibility layer
Each protocol module exposes client and server sub-modules that are conditionally compiled based on the active Cargo features: 
// Client-side XDG shell types
use wayland_protocols::xdg::shell::client::{xdg_wm_base, xdg_surface, xdg_toplevel};

// Server-side XDG shell types (requires the "server" feature)
use wayland_protocols::xdg::shell::server::{xdg_wm_base, xdg_surface, xdg_toplevel};
When both client and server features are enabled — common in compositor codebases — the client and server sub-modules coexist under the same protocol path. Use explicit module paths to avoid ambiguity.

Build docs developers (and LLMs) love

Get started for freeTalk to us