g15keyboard/README.md

# G15 tools: Debian 13 development and packages

This outer repository builds and packages five pinned Git submodules: `libg15`,
`libg15render`, `g15daemon`, `g15macro`, and `g15stats`.
Initialize a fresh clone with
`git submodule update --init --recursive`. Builds reject missing, dirty, or
misaligned submodules; they export committed, unpatched Debian sources and
never modify submodule working trees or refs.

## Build and verify release packages

Create an empty directory outside the checkout (for example with `mktemp -d`)
and run `bash packaging/run.sh /absolute/path/to/that-directory`.
The runner uses disposable Debian 13 Docker containers to build all five
projects in dependency order, install their own development packages before
downstream builds, test distro replacement, and rebuild all five source packages
without the checkout mounted. It mounts only an allowlist of build inputs;
`.vscode` is not exposed to release build containers.

Outputs include nine binary packages, debug symbols, five standalone Debian
source packages, build metadata, submodule provenance and checksums. See
`packaging/NOTES.md` for versions, overlays, QA and release behavior. The old
outer `git archive` ZIP is not a source distribution: it omits submodule content.
Use the verified Debian source artifacts instead.

Gitea Actions builds all five projects on pushes to `main` and manual dispatch.
Successful runs provide the `debian13-amd64` artifact, including binaries,
standalone sources and `SHA256SUMS`. An `ubuntu-latest` runner with Docker
access is required; copy-based CI also supports sibling Docker daemons.
See `packaging/NOTES.md`.

**Safety limitation:** legacy macro memory/configuration handling has known
preexisting defects. Compatibility overlays do not repair the macro engine.
Do not run it as root or use untrusted configuration. Build and install tests
are not hardware or security certification; see `packaging/overlays/v1/README.md`.

## Recommended: Debian 13 container and packages

Use local Linux Docker Engine with Compose and the Dev Containers CLI (or
VS Code's Reopen in Container). From the repository root, run
`devcontainer up --workspace-folder .`, then
`devcontainer exec --workspace-folder . bash`.
The container reuses `packaging/Dockerfile` (Debian 13/trixie), with GCC,
Make, Autotools, Debian packaging tools, libusb-1.0, FreeType and XTest headers.
The image does not preinstall distro G15 development libraries: package builds
install the versions built from the submodules. Its normal packaging command
is replaced with `sleep infinity`.
No host package installation is needed beyond your existing container tooling.

For distributable packages, follow `packaging/NOTES.md`
using its disposable build container, not the development shell: the packaging
scripts install their outputs.

Initialization regenerates ignored `.devcontainer/compose.usb.yaml`, including
only existing exact USB character nodes for Logitech `046d` keyboards
`c222`, `c225`, `c227`, `c22b`, `c22d`, `c22e`. No keyboard is required for
build-only use. Speakers and gamepanels are excluded. Remote SSH/TCP Docker
endpoints and Docker Desktop are rejected; use a native local Linux daemon
whose USB paths match this host (do not use a forwarded Unix socket).
After reconnecting a keyboard, recreate the container with
`devcontainer up --workspace-folder . --remove-existing-container` to refresh
device mappings. A device disappearing during startup may require retrying.

There are no whole-USB mounts, wildcard device rules, privileged mode, Docker
socket mounts, or host networking. `/dev/uinput` is deliberately omitted:
host input injection does not work by default. If needed, manually configure
only that device and host permissions after reviewing the security implications.
Rootless Docker/device permissions may further limit hardware access. Building
and container checks do not establish keyboard functionality; do not run a
second daemon against a keyboard already owned by a host service.

Run `bash .devcontainer/test.sh` with local Linux Docker Engine, Compose,
the installed Dev Containers CLI and host Node.js. It runs real CLI `up` and
`exec` with the absolute checkout path, then checks `docker inspect` against
the current host sysfs allowlist and rejects unexpected devices, mounts,
device cgroup overrides, privileged mode and host networking. It also checks
that `/dev/uinput` is absent. No keyboard is required; an empty allowlist must
produce no device mappings. The container is left running for development.
If USB devices changed, recreate the container as described above and rerun.
These configuration checks perform no keyboard I/O, USB driver changes or
keyboard functional validation. See `packaging/NOTES.md` for release test
coverage and safety limitations.