g15keyboard/packaging/NOTES.md

Debian 13 packaging

Running

Use a regular, initialized Git clone on Linux with Docker Engine. Create an empty output directory with mktemp -d, then run bash packaging/run.sh /absolute/path/to/output. No host package installation, API keys or .env are needed. Build scripts install packages and require a disposable root container; do not run them in the hardware-enabled devcontainer. G15_BUILD_IMAGE optionally changes the shared image tag.

run.sh builds packaging/Dockerfile, mounts only Git metadata, the five submodules and packaging/ read-only, then runs build and lifecycle tests. A second fresh container mounts only artifacts and rebuild.sh, proving that the source packages do not need this repository. All working sources are in container temporary directories. Outputs and logs should remain outside the checkout. Linked Git worktrees with external gitdirs are not supported by the allowlisted mount layout. No container receives USB, uinput or a Docker socket.

Sources, patches and versions

Order: libg15, libg15render, g15daemon, g15macro, g15stats. Each stage installs its own runtime and development packages before the next stage resolves build dependencies. The base image does not supply distro G15 development packages. Each of these five build submodules must match its indexed gitlink and be clean. Stats uses its committed modern Debian packaging without an outer overlay; the image includes its libgtop2-dev build dependency. Git archives export immutable HEADs, not working-tree contents. No checkout, patching, committing, ref updates or pushing occurs in submodules.

Orig tarballs contain the complete committed upstream tree without debian/; tracked generated Autotools inputs are preserved rather than guessed away. No Git metadata, untracked objects or local build state is exported. Debian quilt patches stay unapplied in orig tarballs and are applied by dpkg-source. The existing libusb-1.0 port and daemon buffer-overflow fix are retained.

overlays/v1/ is the explicit local compatibility layer, applied only in temporary copies. It backports daemon -14.1's t64 transition from -14, adds G110 systemd hotplug activation, and replaces macro's historical compat-5 CDBS packaging with debhelper 13. Macro receives only two upstream build fixes: remove bare -I and make an implicit int parameter explicit. All changes are included in the Debian tarballs; macro C/build changes are quilt patches. The source packages carry debian/README.local-build and original attribution.

The daemon control file and SONAME override are compared against the official g15daemon=1.9.5.3-14.1 source obtained through authenticated APT indexes, before changing the local Maintainer. This preserves architecture-dependent ${t64:Provides}, Replaces: libg15daemon-client1 and versioned Breaks. Runtime package filenames/manpages are renamed, without changing SONAME. The inherited dh_installsystemd --no-start remains in force.

Versions use <upstream>+g15.git<12-character-commit>-1. Macro's upstream version is 1.0.5 (configure.ac), not the historical Debian changelog's 1.0.3. Tests require versions above every available trixie candidate, including binNMUs. There are no trixie macro or stats candidates: both are tested as fresh installations, not falsely reported as a distro upgrade. Increment the local Debian revision when changing overlays for an already-published source commit. Git hashes are identifiers, not monotonically increasing versions between local releases.

Orig tar ordering, ownership, timestamps and changelog dates are deterministic from the source commit; SOURCE_DATE_EPOCH is set. .buildinfo records installed dependencies. Debian mirrors and the trixie image intentionally float, so this is repeatable source export and standalone rebuilding, NOT a claim of bit-for-bit binary reproducibility. Keep complete released artifacts. No signing is performed.

Outputs and gates

Nine packages: libg15-1, libg15-dev, libg15render1, libg15render-dev, g15daemon, libg15daemon-client1t64, libg15daemon-client-dev, g15macro, g15stats; plus six debug-symbol packages on amd64. Each of the five sources has a .dsc, orig tarball, Debian tarball, .buildinfo and .changes. SUBMODULES records pins and SHA256SUMS covers all artifacts. The outer Git ZIP is not a substitute.

Tests check exact package names, candidate ordering, checksums, Lintian errors, clean installs, distro upgrades, all three libraries' exported symbols and SONAMEs, executable linking, development headers/linking, t64 fields, service and udev installation, macro help/version and purge cleanup. Source rebuilds install newly rebuilt dependencies, not binaries from the first build.

Gitea CI (.gitea/workflows/debian.yml) builds on every push to main and manual dispatch, using an ubuntu-latest runner with local Docker Engine. The runner must expose the same workspace paths to Docker for read-only mounts. It uploads debian13-amd64 artifacts using the Gitea-compatible v3 protocol; download the artifact from the successful run and check SHA256SUMS. Gitea does not run the GitHub CLI release job or publish release assets. GitHub CI uses recursive checkout on main pushes, relevant PRs, manual dispatch and published releases. Build permissions are read-only; a separate write-permission job downloads the verified artifact and checks checksums before uploading release assets. All actions are commit-pinned. Existing assets are not overwritten. Lint failures, build failures and source rebuild failures block publication.

Safety and validation limits

Development-container configuration is checked separately with bash .devcontainer/test.sh using local Docker, the Dev Containers CLI and host Node.js (see README.md). It starts the real container, inspects exact USB mappings against host sysfs and checks isolation, then exercises CLI exec without keyboard I/O or driver changes. Package CI syntax-checks this script but does not run it; package gates do not imply devcontainer or keyboard functional validation.

Risk: high (legacy native code and distro replacement). Macro has preexisting memory initialization, recording bounds, configuration-index and string-copy defects. These are explicitly outside this build-compatibility change; compiler warnings are not suppressed. Do not run macro as root or load untrusted config. Its historical Debian archive import did not verify the descriptor signature; that provenance limitation remains in debian/README.source.

Hardware operation, X11 recording/playback, hotplug under booted systemd, 32-bit t64 ABI behavior and actual GitHub publishing are not covered by local package tests. No runtime-safety or security certification is claimed. Passing packaging gates does not resolve those upstream security concerns.