83 lines
4.7 KiB
Markdown
83 lines
4.7 KiB
Markdown
# 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.
|