How smithay/wayland-rs works
Main Components
• Core API Crates:
• wayland-client – Provides client-side connection handling, event queues, and global management.
• wayland-server – Implements the server-side logic for handling connections, dispatching, and socket management.
• wayland-protocols – Centralizes the official protocol extension bindings.
• Auxiliary Crates:
• wayland-egl – Bridges Wayland with OpenGL, used in client-side rendering.
• wayland-cursor – Facilitates loading and managing system cursor images.
• Internal/Tooling Crates:
• wayland-backend – Contains the protocol logic implementation. Note its division into a pure Rust implementation and an FFI-based system backend.
• wayland-scanner – Processes XML protocol descriptions to generate Rust code, crucial for custom protocol extensibility.
• wayland-sys – Provides low-level bindings to C Wayland libraries for interoperability.
• Additional Testing Infrastructure:
• wayland-tests – Contains integration and unit tests to validate client and server behavior.
Relationships and Interactions
• The client- and server-side crates depend on wayland-protocols for the protocol definitions and extensions.
• wayland-scanner feeds generated code into several other crates (especially the backend and protocols libraries) which in turn are consumed by clients and servers.
• Auxiliary crates (wayland-egl and wayland-cursor) are usually used by the client to support rendering and UI elements.
• Tests (located in wayland-tests and specific tests folders) validate the interactions between these components, ensuring that changes in one part of the system (e.g., the backend or protocol definitions) propagate correctly to the public APIs.
Architectural Patterns and Design Principles
• Modularization: Each crate is isolated in functionality and can be understood or even used independently.
• Layered Design: Lower-level bindings (wayland-sys) support middle-layer logic (wayland-backend and wayland-scanner) that underpin the high-level APIs (client, server, and protocols).
• Code Generation: The use of wayland-scanner demonstrates an automated approach to converting XML protocol specifications into Rust code, emphasizing maintainability and extensibility.
• Dual Backend Implementation: In the case of the wayland-backend, the dual approach (native Rust vs. FFI-based) showcases the design flexibility regarding how protocol logic interacts with either pure Rust or external system libraries.