wayland-scanner

wayland-scanner
Name	wayland-scanner
Developer	Wayland project, freedesktop.org
Released	2010s
Operating system	Linux, BSD
License	MIT License

wayland-scanner

wayland-scanner is a build-time code generator used by the Wayland project to convert XML protocol descriptions into C header and source artifacts. It is distributed with the Wayland reference libraries and is commonly packaged by freedesktop.org-related distributions such as Debian, Ubuntu, Fedora, and Arch Linux. The tool assists developers building compositors like Weston, Sway, and Mutter by producing stubs that integrate with compositor internals and client libraries such as libwayland-client and libwayland-server.

Overview

wayland-scanner reads XML files that describe message-based interfaces and protocols and produces C code and headers that implement the marshaling and unmarshaling logic required by the Wayland IPC. The generated output targets the C runtime conventions used by the reference libraries, enabling compositors like Weston, KWin, and toolkits such as GTK, Qt and EFL to interoperate. The scanner is part of the Wayland toolchain alongside utilities like wayland-protocols.

History and development

Development of wayland-scanner occurred alongside the early growth of Wayland in the 2010s, driven by contributors from projects including Red Hat, Intel, Collabora, and Suse. Early implementations were refined as compositors such as Weston and toolkits like GTK and Qt adopted Wayland. The project evolved through collaboration on freedesktop.org mailing lists and repositories hosted by organizations such as GitLab and GitHub, incorporating changes driven by implementers from GNOME, KDE, and independent developers. Releases and patches have been discussed at conferences including X.Org Developer Conference and FOSDEM.

Architecture and functionality

wayland-scanner operates as a command-line program that parses XML protocol definitions conforming to the Wayland protocol schema and emits C code templates implementing message serialization, deserialization, versioning checks, and interface descriptors. The generated code integrates with libwayland-client and libwayland-server runtime structures used by compositors like Weston and window managers such as Sway. The scanner supports multiple output modes producing header files for client stubs, server dispatch tables, and debugging helpers used by projects like Mesa and compositors implementing EGL or Vulkan backends. It encodes interface names, event enums, and request signatures into strongly typed C APIs that reduce boilerplate in toolkits like GTK and Qt.

Usage and command-line options

Developers invoke wayland-scanner during build steps for compositors and libraries, commonly from build systems such as CMake, Meson, and GNU Make. Typical modes include "client-header", "server-header", and "code" outputs that produce files consumed by libwayland-client, libwayland-server, and build artifacts used by Weston and Mutter. Options control namespace prefixes, emit licenses, and enable generation of debug wrappers used in development by projects like GNOME and distribution packages in Debian. Integration examples appear in buildscripts from Sway, compositors in KDE, and utility libraries in Freedesktop.org-hosted modules.

Integration with Wayland ecosystem

wayland-scanner is tightly coupled with the Wayland ecosystem: protocol XML files from wayland-protocols are canonical inputs that describe interfaces for features such as input, shell surfaces, and data transfer used across GNOME, KDE, and independent compositors. Generated artifacts are consumed by toolkits like GTK, Qt, EFL, compositors like Weston and KWin, and utilities in Mesa and libinput. Distributions package wayland-scanner alongside libwayland-client and libwayland-server so that downstream projects including Sway and Mutter can include generated bindings in their builds.

Implementation and source code

The implementation is written in C and lives in the Wayland source repositories managed on platforms used by contributors from Red Hat, Intel, and Collabora. The codebase includes an XML parser tailored to the Wayland protocol schema and templates for generating C code that matches libwayland-client and libwayland-server expectations. Contributors submit patches via GitLab/GitHub merge requests and discuss design on freedesktop.org mailing lists and issue trackers used by the Wayland community. Tests and examples often reference compositors such as Weston and display server integrations used by GNOME and KDE.

Limitations and compatibility

wayland-scanner targets C bindings for the reference Wayland libraries and does not directly generate bindings for high-level languages; projects like Python, Rust, and Go often rely on wrappers maintained by separate communities such as PyPI, crates.io, and Go Modules. Compatibility depends on adherence to the canonical XML schema found in wayland-protocols; nonstandard extensions require manual adaptation. The scanner's generated code assumes the conventions of libwayland-client and libwayland-server and may need adjustments for alternative runtimes or experimental compositors that diverge from reference semantics used by Weston, Sway, and Mutter.

Category:Wayland