# 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 Docker Engine access.
`ci.sh` copies only the build-input allowlist into disposable containers instead
of bind-mounting runner paths, supporting containerized runners with sibling
Docker daemons. The standalone rebuild receives only artifacts and its script.
Containers are removed on exit; their exit codes are explicitly checked.
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.