build(examples): add examples-check target and README usage sketch

commit: 49445e1865af0ee10b7ce272a3c8d9cdd838bed6
author: brice · 21d ago · 2026-10-01 19:13 UTC
parent: 543bef2
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +25 -1

M Makefile +3 -1

@@ -1,4 +1,4 @@
1		-	.PHONY: build clean-build test vet race mocks mocks-check fakes-check perf-check check
	1	+	.PHONY: build clean-build test vet race mocks mocks-check fakes-check perf-check check examples-check
2	2
3	3		build:
4	4		CGO_ENABLED=0 go build ./...

@@ -20,5 +20,7 @@ fakes-check:
20	20		[ $$rc -eq 1 ] \|\| { [ $$rc -eq 0 ] && printf '%s\n' 'handwritten test double: generate with Mockery v3' >&2; exit 1; }
21	21		perf-check:
22	22		CGO_ENABLED=0 go test -run 'TestAlloc' -count=1 ./...
	23	+	examples-check:
	24	+	cd examples && CGO_ENABLED=0 go build ./... && CGO_ENABLED=0 go vet ./...
23	25		check: build clean-build vet test fakes-check perf-check
24	26		CGO_ENABLED=0 staticcheck ./...

-.PHONY: build clean-build test vet race mocks mocks-check fakes-check perf-check check
+.PHONY: build clean-build test vet race mocks mocks-check fakes-check perf-check check examples-check
 build:
 	CGO_ENABLED=0 go build ./...
 	[ $$rc -eq 1 ] || { [ $$rc -eq 0 ] && printf '%s\n' 'handwritten test double: generate with Mockery v3' >&2; exit 1; }
 perf-check:
 	CGO_ENABLED=0 go test -run 'TestAlloc' -count=1 ./...
+examples-check:
+	cd examples && CGO_ENABLED=0 go build ./... && CGO_ENABLED=0 go vet ./...
 check: build clean-build vet test fakes-check perf-check
 	CGO_ENABLED=0 staticcheck ./...

M README.md +22 -0


@@ -11,6 +11,28 @@ A Wayland client toolkit library for Go: connection, outputs, surface roles, sea
11	11		- A compositor advertising `zwp_linux_dmabuf_v1` (v4) and `wp_linux_drm_syncobj_manager_v1`.
12	12		- `libxkbcommon` at runtime for keyboard input.
13	13
	14	+	## Usage
	15	+
	16	+	The library does not render. The `examples` module pairs it with [NeferGUI](https://github.com/bnema/nefergui) (a pure graphics library with no Wayland code); the two never import each other, and the examples copy plain fields between them. The loop runs on one owner goroutine:
	17	+
	18	+	```go
	19	+	conn, _ := neferclient.Connect(ctx, "")
	20	+	surf, _ := conn.NewLayerSurface(neferclient.LayerConfig{Level: neferclient.LayerTop, Width: 240, Height: 90})
	21	+	for {
	22	+	select {
	23	+	case <-conn.Wake():
	24	+	conn.Dispatch(handler) // Configure, FeedbackDone, Frame, Pointer, Key, FDReady...
	25	+	}
	26	+	// render with NeferGUI, then:
	27	+	// surf.ImportBuffer / surf.ImportTimeline / surf.Present
	28	+	}
	29	+	```
	30	+
	31	+	- [`examples/layer`](examples/layer): a layer surface with a counter button.
	32	+	- [`examples/lock`](examples/lock): a session lock with a masked password field. It is a demo and authenticates nothing; read its header before running it.
	33	+
	34	+	Run them against a compositor with `cd examples && go run ./layer`. `make examples-check` builds and vets them; the headless test needs a NeferWL binary: `NEFERCLIENT_HEADLESS=/usr/sbin/neferwl go test ./... -run Headless`.
	35	+
14	36		## License
15	37
16	38		MIT


@@ -11,6 +11,28 @@ A Wayland client toolkit library for Go: connection, outputs, surface roles, sea
11	- A compositor advertising `zwp_linux_dmabuf_v1` (v4) and `wp_linux_drm_syncobj_manager_v1`.	11		- A compositor advertising `zwp_linux_dmabuf_v1` (v4) and `wp_linux_drm_syncobj_manager_v1`.
12	- `libxkbcommon` at runtime for keyboard input.	12		- `libxkbcommon` at runtime for keyboard input.
13		13
		14	+	## Usage
		15	+
		16	+	The library does not render. The `examples` module pairs it with [NeferGUI](https://github.com/bnema/nefergui) (a pure graphics library with no Wayland code); the two never import each other, and the examples copy plain fields between them. The loop runs on one owner goroutine:
		17	+
		18	+	```go
		19	+	conn, _ := neferclient.Connect(ctx, "")
		20	+	surf, _ := conn.NewLayerSurface(neferclient.LayerConfig{Level: neferclient.LayerTop, Width: 240, Height: 90})
		21	+	for {
		22	+	select {
		23	+	case <-conn.Wake():
		24	+	conn.Dispatch(handler) // Configure, FeedbackDone, Frame, Pointer, Key, FDReady...
		25	+	}
		26	+	// render with NeferGUI, then:
		27	+	// surf.ImportBuffer / surf.ImportTimeline / surf.Present
		28	+	}
		29	+	```
		30	+
		31	+	- [`examples/layer`](examples/layer): a layer surface with a counter button.
		32	+	- [`examples/lock`](examples/lock): a session lock with a masked password field. It is a demo and authenticates nothing; read its header before running it.
		33	+
		34	+	Run them against a compositor with `cd examples && go run ./layer`. `make examples-check` builds and vets them; the headless test needs a NeferWL binary: `NEFERCLIENT_HEADLESS=/usr/sbin/neferwl go test ./... -run Headless`.
		35	+
14	## License	36		## License
15		37
16	MIT	38		MIT