21 lines
2.0 KiB
Markdown
21 lines
2.0 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for agents working in this repo.
|
|
|
|
## Structure
|
|
- Parent repo integrates five submodules built and packaged for Debian 13: `libg15`, `libg15render`, `g15daemon`, `g15macro`, `g15stats`.
|
|
- `packaging/` holds all build/CI logic; `.gitea/workflows/` and `.github/workflows/` both call into the same shared scripts rather than duplicating build logic.
|
|
|
|
## Building
|
|
- `bash packaging/local-build.sh` (also available as the default VS Code build task) builds all five Debian source+binary packages into gitignored `dist/`, and extracts plain executables/shared libraries into gitignored `bin/`.
|
|
- `packaging/build.sh` requires every submodule to be clean (`git status --porcelain --untracked-files=all` empty) and checked out exactly at its parent's pinned gitlink commit — it refuses to build otherwise. Regenerable host build artifacts (autotools `Makefile`, `config.*`, `libtool`, `stamp-h1`, `.deps/`) left over from a manual `./configure && make` are untracked but still count as dirty; remove them (safe, regenerable) rather than committing them.
|
|
- `packaging/run.sh` / `packaging/ci.sh` wrap `build.sh`+`test.sh` in disposable Docker containers for host/CI use; inside this devcontainer (already root, already `/.dockerenv`, already has all packaging tools installed) `build.sh`/`test.sh` can be run directly without nested Docker.
|
|
- See `packaging/NOTES.md` for full packaging/versioning/CI policy details.
|
|
|
|
## Submodule workflow
|
|
- Commit and push submodule changes in the submodule's own repo first, then update and push the parent gitlink pointer — this keeps the parent's gitlink always fetchable.
|
|
- Never blindly `git add -A` a submodule; stage real source/doc changes explicitly and exclude generated build state.
|
|
|
|
## Known technical constraint
|
|
- g15stats renders on a bitmap-only canvas allocation; do not switch it to the ABI-dependent (optionally TTF-enabled) `libg15render` canvas initializer — a smaller bitmap-only allocation plus a larger installed renderer ABI has previously corrupted the heap at startup (`malloc(): invalid size`).
|