docs: add PipeWire generator maintenance workflow

commit: 5ce50261ef917a217551d2947144f7e4f6e005fc
author: brice · 6mo ago · 2026-04-09 07:49 UTC
parent: 96c5c6a
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

4 files · +91 -0

M README.md +7 -0


@@ -25,6 +25,13 @@ Mocks are generated by [mockery](https://github.com/vektra/mockery):
25	25
26	26		mockery
27	27
	28	+	### Maintainer workflow
	29	+
	30	+	Maintainers can refresh the model from local PipeWire and SPA headers with:
	31	+
	32	+	./scripts/sync-headers.sh
	33	+	go generate ./...
	34	+
28	35		## Requirements
29	36
30	37		- Go 1.23+


@@ -25,6 +25,13 @@ Mocks are generated by [mockery](https://github.com/vektra/mockery):
25		25
26	mockery	26		mockery
27		27
		28	+	### Maintainer workflow
		29	+
		30	+	Maintainers can refresh the model from local PipeWire and SPA headers with:
		31	+
		32	+	./scripts/sync-headers.sh
		33	+	go generate ./...
		34	+
28	## Requirements	35		## Requirements
29		36
30	- Go 1.23+	37		- Go 1.23+

A cmd/pipewiregen/README.md +57 -0

@@ -0,0 +1,57 @@
	1	+	# pipewiregen
	2	+
	3	+	The `pipewiregen` tool generates Go bindings for PipeWire and SPA libraries from JSON model files.
	4	+
	5	+	## Usage
	6	+
	7	+	### Generate bindings from checked-in models
	8	+
	9	+	go run ./cmd/pipewiregen
	10	+
	11	+	This reads `gen/pipewire.json` and `gen/spa.json`, then emits:
	12	+	- `internal/capi/*_gen.go` — raw function types and registration helpers
	13	+	- `internal/ports/out/*_gen.go` — outbound port interfaces
	14	+
	15	+	### Sync headers from system includes (maintainers)
	16	+
	17	+	./scripts/sync-headers.sh
	18	+
	19	+	Or run directly:
	20	+
	21	+	go run ./cmd/pipewiregen --sync-headers \
	22	+	--pipewire-include /usr/include/pipewire-0.3 \
	23	+	--spa-include /usr/include/spa-0.2 \
	24	+	--out-dir gen
	25	+
	26	+	## Model format
	27	+
	28	+	The JSON model files follow this structure:
	29	+
	30	+	```json
	31	+	{
	32	+	"libraries": [
	33	+	{"name": "pipewire", "soname": "libpipewire-0.3.so.0"}
	34	+	],
	35	+	"groups": [
	36	+	{"name": "init", "interface": "InitAPI", "package": "out", "symbols": ["pw_init", "pw_deinit"]}
	37	+	],
	38	+	"symbols": [
	39	+	{"name": "pw_init", "library": "pipewire", "group": "init", "signature": "func(argc int32, argv **byte)"}
	40	+	]
	41	+	}
	42	+	```
	43	+
	44	+	- `libraries`: Shared libraries to load
	45	+	- `groups`: Symbol groupings that become Go interfaces
	46	+	- `symbols`: Individual function symbols with their Go signatures
	47	+
	48	+	## Architecture
	49	+
	50	+	The generator follows a pipeline design:
	51	+
	52	+	1. parser: Loads and validates JSON model files
	53	+	2. model: Core data structures for libraries, groups, and symbols
	54	+	3. normalize: PipeWire-specific naming conventions
	55	+	4. emitter: Renders Go code from templates
	56	+
	57	+	See the individual package directories for implementation details.

@@ -0,0 +1,57 @@
	1	+	# pipewiregen
	2	+
	3	+	The `pipewiregen` tool generates Go bindings for PipeWire and SPA libraries from JSON model files.
	4	+
	5	+	## Usage
	6	+
	7	+	### Generate bindings from checked-in models
	8	+
	9	+	go run ./cmd/pipewiregen
	10	+
	11	+	This reads `gen/pipewire.json` and `gen/spa.json`, then emits:
	12	+	- `internal/capi/*_gen.go` — raw function types and registration helpers
	13	+	- `internal/ports/out/*_gen.go` — outbound port interfaces
	14	+
	15	+	### Sync headers from system includes (maintainers)
	16	+
	17	+	./scripts/sync-headers.sh
	18	+
	19	+	Or run directly:
	20	+
	21	+	go run ./cmd/pipewiregen --sync-headers \
	22	+	--pipewire-include /usr/include/pipewire-0.3 \
	23	+	--spa-include /usr/include/spa-0.2 \
	24	+	--out-dir gen
	25	+
	26	+	## Model format
	27	+
	28	+	The JSON model files follow this structure:
	29	+
	30	+	```json
	31	+	{
	32	+	"libraries": [
	33	+	{"name": "pipewire", "soname": "libpipewire-0.3.so.0"}
	34	+	],
	35	+	"groups": [
	36	+	{"name": "init", "interface": "InitAPI", "package": "out", "symbols": ["pw_init", "pw_deinit"]}
	37	+	],
	38	+	"symbols": [
	39	+	{"name": "pw_init", "library": "pipewire", "group": "init", "signature": "func(argc int32, argv **byte)"}
	40	+	]
	41	+	}
	42	+	```
	43	+
	44	+	- `libraries`: Shared libraries to load
	45	+	- `groups`: Symbol groupings that become Go interfaces
	46	+	- `symbols`: Individual function symbols with their Go signatures
	47	+
	48	+	## Architecture
	49	+
	50	+	The generator follows a pipeline design:
	51	+
	52	+	1. parser: Loads and validates JSON model files
	53	+	2. model: Core data structures for libraries, groups, and symbols
	54	+	3. normalize: PipeWire-specific naming conventions
	55	+	4. emitter: Renders Go code from templates
	56	+
	57	+	See the individual package directories for implementation details.

A pipewire/readme_test.go +20 -0

@@ -0,0 +1,20 @@
	1	+	package pipewire
	2	+
	3	+	import (
	4	+	"os"
	5	+	"strings"
	6	+	"testing"
	7	+	)
	8	+
	9	+	func TestReadmeMentionsGenerateAndMockery(t *testing.T) {
	10	+	b, err := os.ReadFile("../README.md")
	11	+	if err != nil {
	12	+	t.Fatalf("ReadFile returned error: %v", err)
	13	+	}
	14	+	text := string(b)
	15	+	for _, needle := range []string{"go generate ./...", "mockery", "gen/pipewire.json"} {
	16	+	if !strings.Contains(text, needle) {
	17	+	t.Fatalf("README missing %q", needle)
	18	+	}
	19	+	}
	20	+	}

@@ -0,0 +1,20 @@
	1	+	package pipewire
	2	+
	3	+	import (
	4	+	"os"
	5	+	"strings"
	6	+	"testing"
	7	+	)
	8	+
	9	+	func TestReadmeMentionsGenerateAndMockery(t *testing.T) {
	10	+	b, err := os.ReadFile("../README.md")
	11	+	if err != nil {
	12	+	t.Fatalf("ReadFile returned error: %v", err)
	13	+	}
	14	+	text := string(b)
	15	+	for _, needle := range []string{"go generate ./...", "mockery", "gen/pipewire.json"} {
	16	+	if !strings.Contains(text, needle) {
	17	+	t.Fatalf("README missing %q", needle)
	18	+	}
	19	+	}
	20	+	}

A scripts/sync-headers.sh +7 -0

@@ -0,0 +1,7 @@
	1	+	#!/usr/bin/env bash
	2	+	set -euo pipefail
	3	+
	4	+	go run ./cmd/pipewiregen --sync-headers \
	5	+	--pipewire-include "${PIPEWIRE_INCLUDE_DIR:-/usr/include/pipewire-0.3}" \
	6	+	--spa-include "${SPA_INCLUDE_DIR:-/usr/include/spa-0.2}" \
	7	+	--out-dir gen

@@ -0,0 +1,7 @@
	1	+	#!/usr/bin/env bash
	2	+	set -euo pipefail
	3	+
	4	+	go run ./cmd/pipewiregen --sync-headers \
	5	+	--pipewire-include "${PIPEWIRE_INCLUDE_DIR:-/usr/include/pipewire-0.3}" \
	6	+	--spa-include "${SPA_INCLUDE_DIR:-/usr/include/spa-0.2}" \
	7	+	--out-dir gen