Contributing to zig-wayland-native #

Issues and pull requests go to the Tangled mirror, https://tangled.org/jcollie.dev/zig-wayland-native.

Setting up #

Everything the project needs — Zig 0.17, reuse, and the headless compositors the examples are tested against — comes from the Nix flake:

$ nix develop

Without Nix, you need Zig 0.17.0 or later, and weston and sway for tools/headless.sh. The Zig build fetches its own dependencies, including the wayland and wayland-protocols releases; nothing is read from the system.

Before sending a change #

CI runs all of these, and a change should pass them:

$ reuse lint
$ zig fmt --check .
$ zig build test --summary all
$ zig build check
$ ./tools/headless.sh

• zig build check compiles what the tests do not: the examples and the documentation server.
• tools/headless.sh runs the examples against a headless weston, and the dma-buf and explicit sync stages too where /dev/udmabuf and a render node are available. It says so when it skips a stage.

Where things live #

• src/scanner reads protocol XML and renders Zig bindings; tools/scanner.zig is the command the build runs.
• src/protocol is the wire protocol with no I/O. Anything that can be tested with byte slices is tested here.
• src/client is the socket, and is Linux-only.
• src/present is buffers and presentation, built against the consumer's bindings by addPresent in build.zig.
• tests/ holds the suites that drive the generated bindings and play the compositor over a socketpair; tests/fake.zig is that compositor.
• examples/ are the programs zig build run-<name> runs.

Conventions #

• Treat the compositor's input as hostile. Check every length against what arrived before using it, and fail the session with an error on malformed input, never with a panic.
• Be explicit about who owns a file descriptor. If a change moves who closes a descriptor, the doc comments have to say so.
• Put the explanation in doc comments. The API documentation is generated from them (zig build docs, and zig build docs-serve to read it).
• Keep REUSE compliance. Every new file carries an SPDX header, or an entry in REUSE.toml if it cannot hold one. The code is under the MIT license.