README.md (3354B)
1 # zig-wayland 2 3 Zig 0.14 bindings and protocol scanner for libwayland. 4 5 The main repository is on [codeberg](https://codeberg.org/ifreund/zig-wayland), 6 which is where the issue tracker may be found and where contributions are accepted. 7 8 Read-only mirrors exist on [sourcehut](https://git.sr.ht/~ifreund/zig-wayland) 9 and [github](https://github.com/ifreund/zig-wayland). 10 11 ## Usage 12 13 A `Scanner` interface is provided which you may integrate with your `build.zig`: 14 15 ```zig 16 const std = @import("std"); 17 const Build = std.Build; 18 19 const Scanner = @import("wayland").Scanner; 20 21 pub fn build(b: *Build) !void { 22 const target = b.standardTargetOptions(.{}); 23 const optimize = b.standardOptimizeOption(.{}); 24 25 const scanner = Scanner.create(b, .{}); 26 27 const wayland = b.createModule(.{ .root_source_file = scanner.result }); 28 29 scanner.addSystemProtocol("stable/xdg-shell/xdg-shell.xml"); 30 scanner.addSystemProtocol("staging/ext-session-lock/ext-session-lock-v1.xml"); 31 scanner.addCustomProtocol(b.path("protocol/private_foobar.xml")); 32 33 // Pass the maximum version implemented by your wayland server or client. 34 // Requests, events, enums, etc. from newer versions will not be generated, 35 // ensuring forwards compatibility with newer protocol xml. 36 // This will also generate code for interfaces created using the provided 37 // global interface, in this example wl_keyboard, wl_pointer, xdg_surface, 38 // xdg_toplevel, etc. would be generated as well. 39 scanner.generate("wl_seat", 4); 40 scanner.generate("xdg_wm_base", 3); 41 scanner.generate("ext_session_lock_manager_v1", 1); 42 scanner.generate("private_foobar_manager", 1); 43 44 const exe = b.addExecutable(.{ 45 .name = "foobar", 46 .root_source_file = .{ .path = "foobar.zig" }, 47 .target = target, 48 .optimize = optimize, 49 }); 50 51 exe.root_module.addImport("wayland", wayland); 52 exe.linkLibC(); 53 exe.linkSystemLibrary("wayland-client"); 54 55 b.installArtifact(exe); 56 } 57 ``` 58 59 Then, you may import the provided module in your project: 60 61 ```zig 62 const wayland = @import("wayland"); 63 const wl = wayland.client.wl; 64 ``` 65 66 There is an example project using zig-wayland here in the 67 [example/hello](./example/hello) directory of this repository. 68 69 Note that zig-wayland does not currently do extensive verification of Wayland 70 protocol xml or provide good error messages if protocol xml is invalid. It is 71 recommend to use `wayland-scanner --strict` to debug protocol xml instead. 72 73 ## Versioning 74 75 For now, zig-wayland versions are of the form `0.major.patch`. A major version 76 bump indicates a zig-wayland release that breaks API or requires a newer Zig 77 version to build. A patch version bump indicates a zig-wayland release that is 78 fully backwards compatible. 79 80 For unreleased versions, the `-dev` suffix is used (e.g. `0.1.0-dev`). 81 82 The version of zig-wayland currently has no direct relation to the upstream 83 libwayland version supported. 84 85 Breaking changes in zig-wayland's API will be necessary until a stable Zig 1.0 86 version is released, at which point I plan to switch to a new versioning scheme 87 and start the version numbers with `1` instead of `0`. 88 89 ## License 90 91 zig-wayland is released under the MIT (expat) license. 92 93 The contents of the hello-zig-wayland directory are not part of zig-wayland and are released under the Zero Clause BSD license.