docs: add README

commit: c133d5921aba3b2977e1fe704b947536043d8479
author: brice · 21d ago · 2026-10-01 03:41 UTC
parent: 3842d92
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +130 -0

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).