detached c133d59

docs: add README

commit
c133d5921aba3b2977e1fe704b947536043d8479
author
brice · · 2026-10-01 03:41 UTC
parent
3842d92
signature
GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email
1 file · +130 -0
Split
UnifiedSplit
A README.md +130 -0
@@ -0,0 +1,130 @@
1+# go-wayland-bindings
2+
3+Go bindings for the Wayland protocols, generated from vendored upstream XML.
4+One module is the single source of truth for both sides of the wire:
5+
6+- `client/<pkg>`: client bindings for the pure-Go
7+ [wlturbo](https://github.com/bnema/wlturbo) runtime.
8+- `server/<pkg>`: server bindings for the libwayland-server runtime in
9+ [purego-libwayland](https://github.com/bnema/purego-libwayland).
10+
11+Everything builds with `CGO_ENABLED=0`.
12+
13+## Install
14+
15+```sh
16+go get github.com/bnema/go-wayland-bindings@latest
17+```
18+
19+## Usage
20+
21+Client (the runtime lives in `github.com/bnema/wlturbo`):
22+
23+```go
24+import (
25+ "github.com/bnema/wlturbo/wl"
26+
27+ "github.com/bnema/go-wayland-bindings/client/wayland"
28+)
29+
30+display, err := wl.Connect("")
31+// ...
32+compositor := wayland.NewCompositor(display.Context())
33+err = display.Registry().Bind(name, wayland.CompositorInterface, 1, compositor)
34+```
35+
36+Server (the runtime lives in `github.com/bnema/purego-libwayland/server`):
37+
38+```go
39+import (
40+ "github.com/bnema/purego-libwayland/server"
41+
42+ "github.com/bnema/go-wayland-bindings/server/wayland"
43+)
44+
45+err := wayland.NewCompositorGlobal(display, 6, func(c server.Client, version, id uint32) {
46+ _, _ = wayland.NewCompositor(c, int32(version), id, myCompositorHandler{})
47+})
48+```
49+
50+## Packages
51+
52+A package name derives from the XML file name: drop `.xml`, drop a trailing
53+`-unstable-vN`, then a trailing `-vN`, then remove every `-`. So
54+`xdg-shell.xml` is `xdgshell`, `wlr-layer-shell-unstable-v1.xml` is
55+`wlrlayershell`, and `wayland.xml` is `wayland`. The package has the same name
56+under `client/` and `server/`. When several upstream versions of one protocol
57+exist, the most stable and then highest version is used; there is one major
58+version per protocol.
59+
60+The full list, with upstream source, path, license and interfaces, is in
61+[`spec/manifest.json`](spec/manifest.json).
62+
63+## Custom protocol XML
64+
65+`wlbgen` generates bindings for a private protocol XML. Interfaces it
66+references from the vendored protocols (such as `wl_surface`) are resolved
67+automatically to the matching `client/<pkg>` or `server/<pkg>` package:
68+
69+```sh
70+go run github.com/bnema/go-wayland-bindings/cmd/wlbgen \
71+ -side server -package mything -out mything_generated.go mything.xml
72+```
73+
74+Use `-side client` for client bindings. `-import iface=importpath` overrides
75+the package of one interface (repeatable); an interface that cannot be
76+resolved is an error.
77+
78+## Development
79+
80+Regenerate every binding from `spec/manifest.json`:
81+
82+```sh
83+go generate ./...
84+```
85+
86+Generated output is deterministic: a second run changes nothing. Hand-written
87+files that live next to generated code (for example
88+`client/linuxdmabuf/table.go`) are never touched.
89+
90+Sync the vendored XML with upstream (needs network and `git`):
91+
92+```sh
93+go run ./cmd/wlbsync # update spec/xml and spec/manifest.json
94+go run ./cmd/wlbsync -check # print changed=true|false, write nothing
95+go run ./cmd/wlbsync -notes notes.md
96+```
97+
98+`spec/manifest.json` is written by `wlbsync` and is never edited by hand.
99+
100+## Releases
101+
102+A scheduled workflow syncs upstream every day. When anything changed it
103+regenerates the bindings, runs the checks and publishes a new minor version
104+`v0.X.0` whose release notes list added and removed packages, interface
105+version bumps and breaking changes. A failed run publishes nothing.
106+
107+## Tests
108+
109+```sh
110+env CGO_ENABLED=0 go test ./...
111+go test -race ./... # needs libwayland-server installed
112+```
113+
114+Two environment variables enable tests that are skipped by default:
115+
116+- `WLTURBO_HEADLESS`: path to a headless compositor binary (NeferWL) for the
117+ end-to-end tests in `client/`.
118+- `WLTURBO_LIVE`: set to `1` to run the tests that talk to the compositor of
119+ the current session.
120+
121+## Licenses
122+
123+The code of this repository (generators, tooling, tests) is MIT licensed,
124+copyright go-wayland-bindings contributors; see [`LICENSE`](LICENSE).
125+
126+The vendored XML and the bindings generated from it keep the license of the
127+upstream protocol; each generated file carries the upstream copyright notice.
128+Most protocols are MIT. The `serverdecoration` protocol (KDE
129+`server-decoration.xml`) is LGPL-2.1-or-later; its text is in
130+[`LICENSES/`](LICENSES/LGPL-2.1-or-later.txt).
@@ -0,0 +1,130 @@
1+# go-wayland-bindings
2+
3+Go bindings for the Wayland protocols, generated from vendored upstream XML.
4+One module is the single source of truth for both sides of the wire:
5+
6+- `client/<pkg>`: client bindings for the pure-Go
7+ [wlturbo](https://github.com/bnema/wlturbo) runtime.
8+- `server/<pkg>`: server bindings for the libwayland-server runtime in
9+ [purego-libwayland](https://github.com/bnema/purego-libwayland).
10+
11+Everything builds with `CGO_ENABLED=0`.
12+
13+## Install
14+
15+```sh
16+go get github.com/bnema/go-wayland-bindings@latest
17+```
18+
19+## Usage
20+
21+Client (the runtime lives in `github.com/bnema/wlturbo`):
22+
23+```go
24+import (
25+ "github.com/bnema/wlturbo/wl"
26+
27+ "github.com/bnema/go-wayland-bindings/client/wayland"
28+)
29+
30+display, err := wl.Connect("")
31+// ...
32+compositor := wayland.NewCompositor(display.Context())
33+err = display.Registry().Bind(name, wayland.CompositorInterface, 1, compositor)
34+```
35+
36+Server (the runtime lives in `github.com/bnema/purego-libwayland/server`):
37+
38+```go
39+import (
40+ "github.com/bnema/purego-libwayland/server"
41+
42+ "github.com/bnema/go-wayland-bindings/server/wayland"
43+)
44+
45+err := wayland.NewCompositorGlobal(display, 6, func(c server.Client, version, id uint32) {
46+ _, _ = wayland.NewCompositor(c, int32(version), id, myCompositorHandler{})
47+})
48+```
49+
50+## Packages
51+
52+A package name derives from the XML file name: drop `.xml`, drop a trailing
53+`-unstable-vN`, then a trailing `-vN`, then remove every `-`. So
54+`xdg-shell.xml` is `xdgshell`, `wlr-layer-shell-unstable-v1.xml` is
55+`wlrlayershell`, and `wayland.xml` is `wayland`. The package has the same name
56+under `client/` and `server/`. When several upstream versions of one protocol
57+exist, the most stable and then highest version is used; there is one major
58+version per protocol.
59+
60+The full list, with upstream source, path, license and interfaces, is in
61+[`spec/manifest.json`](spec/manifest.json).
62+
63+## Custom protocol XML
64+
65+`wlbgen` generates bindings for a private protocol XML. Interfaces it
66+references from the vendored protocols (such as `wl_surface`) are resolved
67+automatically to the matching `client/<pkg>` or `server/<pkg>` package:
68+
69+```sh
70+go run github.com/bnema/go-wayland-bindings/cmd/wlbgen \
71+ -side server -package mything -out mything_generated.go mything.xml
72+```
73+
74+Use `-side client` for client bindings. `-import iface=importpath` overrides
75+the package of one interface (repeatable); an interface that cannot be
76+resolved is an error.
77+
78+## Development
79+
80+Regenerate every binding from `spec/manifest.json`:
81+
82+```sh
83+go generate ./...
84+```
85+
86+Generated output is deterministic: a second run changes nothing. Hand-written
87+files that live next to generated code (for example
88+`client/linuxdmabuf/table.go`) are never touched.
89+
90+Sync the vendored XML with upstream (needs network and `git`):
91+
92+```sh
93+go run ./cmd/wlbsync # update spec/xml and spec/manifest.json
94+go run ./cmd/wlbsync -check # print changed=true|false, write nothing
95+go run ./cmd/wlbsync -notes notes.md
96+```
97+
98+`spec/manifest.json` is written by `wlbsync` and is never edited by hand.
99+
100+## Releases
101+
102+A scheduled workflow syncs upstream every day. When anything changed it
103+regenerates the bindings, runs the checks and publishes a new minor version
104+`v0.X.0` whose release notes list added and removed packages, interface
105+version bumps and breaking changes. A failed run publishes nothing.
106+
107+## Tests
108+
109+```sh
110+env CGO_ENABLED=0 go test ./...
111+go test -race ./... # needs libwayland-server installed
112+```
113+
114+Two environment variables enable tests that are skipped by default:
115+
116+- `WLTURBO_HEADLESS`: path to a headless compositor binary (NeferWL) for the
117+ end-to-end tests in `client/`.
118+- `WLTURBO_LIVE`: set to `1` to run the tests that talk to the compositor of
119+ the current session.
120+
121+## Licenses
122+
123+The code of this repository (generators, tooling, tests) is MIT licensed,
124+copyright go-wayland-bindings contributors; see [`LICENSE`](LICENSE).
125+
126+The vendored XML and the bindings generated from it keep the license of the
127+upstream protocol; each generated file carries the upstream copyright notice.
128+Most protocols are MIT. The `serverdecoration` protocol (KDE
129+`server-decoration.xml`) is LGPL-2.1-or-later; its text is in
130+[`LICENSES/`](LICENSES/LGPL-2.1-or-later.txt).

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 1

↑↓ moveenter openesc close