libakgl/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This is a C library intended to support the development of video games. Public C headers live in include/akgl/; keep declarations there aligned with their implementations in src/. Tests are standalone C programs under tests/, with JSON, image, and map fixtures in tests/assets/. The util/ directory contains the charviewer utility and its sample assets. Third-party and companion libraries are vendored in deps/. Treat build/ and generated akgl.pc files as build outputs rather than hand-maintained source; include/akgl/SDL_GameControllerDB.h is generated too, but is tracked on purpose — see below.

Generated and Vendored Sources

include/akgl/SDL_GameControllerDB.h is generated, and is tracked deliberately

mkcontrollermappings.sh regenerates this header by fetching the community controller database from raw.githubusercontent.com. It is committed to the repository on purpose: it is the offline fallback that keeps the library buildable if upstream is renamed, rate-limited, taken down, or simply unreachable from the build machine. Do not delete it, do not add it to .gitignore, and do not "clean up" the fact that a generated file is tracked.

Working rules:

• Never hand-edit it. It is machine-written; changes belong in mkcontrollermappings.sh.
• Do not commit incidental regeneration churn. The build regenerates the header on every run, and the script stamps $(date) into a comment, so an ordinary build leaves the file modified with nothing of substance changed. Revert that before committing: git checkout -- include/akgl/SDL_GameControllerDB.h.
• Update it as a deliberate, standalone commit when you actually want newer mappings, so the diff is reviewable and bisectable.
• Never commit a copy with AKGL_SDL_GAMECONTROLLER_DB_LEN 0. That is the signature of a failed fetch, not an empty upstream — see the defect note below. Check the constant before staging this file.
• Formatting tooling ignores it: scripts/reindent.sh and the pre-commit hook both skip it.

Known defect (tracked in TODO.md). The safety net is currently self-defeating. mkcontrollermappings.sh has no set -e and does not check curl's exit status, so when the fetch fails it writes a header with AKGL_SDL_GAMECONTROLLER_DB_LEN 0 and an empty array over the good tracked copy, and exits 0. Because CMake re-runs the generator on every build, an offline build silently destroys the very fallback the file exists to provide. Until that is fixed, treat a dirty SDL_GameControllerDB.h after a build as suspect and check the length constant before committing it.

Build, Test, and Development Commands

Configure an out-of-tree development build:

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo

Build all library, utility, and test targets:

cmake --build build --parallel

Run the complete test suite with failure details:

ctest --test-dir build --output-on-failure

Run one test while iterating, for example ctest --test-dir build -R sprite --output-on-failure. The rebuild.sh script also installs into a developer-specific /home/andrew/local prefix and removes existing outputs; prefer the portable commands above unless that exact workflow is intended.

Run only the performance suites with ctest --test-dir build -L perf --output-on-failure, or leave them out of an ordinary run with -LE perf. They take about 30 seconds together, print a table of nanoseconds per operation, and fail only when a measurement exceeds a budget set at roughly ten times the recorded baseline. AKGL_BENCH_SCALE scales every iteration count — AKGL_BENCH_SCALE=0.1 ctest --test-dir build -L perf for a quick look — and below 1.0 the budgets are reported but not enforced. The recorded baseline and what it means are in PERFORMANCE.md.

Check for memory defects with cmake --build build --target memcheck, or scripts/memcheck.sh directly — it takes ctest's selection flags, so scripts/memcheck.sh -R tilemap and scripts/memcheck.sh -LE perf both work. It runs the suites that already exist under valgrind (ctest -T memcheck) with the headless drivers forced, and exits non-zero when valgrind finds a definite leak, an invalid access, or a read of uninitialised memory — which ctest -T memcheck on its own will not do. The whole run takes about thirty seconds because the perf suites scale themselves down under valgrind. Suppressions for third-party findings live in scripts/valgrind.supp; add one only when the finding genuinely cannot be fixed from this repository.

Run mutation testing with cmake --build build --target mutation. For a quick smoke run, use scripts/mutation_test.py --target src/tilemap.c --max-mutants 10; the harness mutates only a scratch copy and excludes the intentionally failing character test.

Generate HTML and Cobertura coverage reports with cmake -S . -B build-coverage -DAKGL_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug, then build and run CTest. Reports are written to build-coverage/coverage/; this mode requires gcovr and GCC or Clang.

Continuous integration

.gitea/workflows/ci.yaml runs four jobs on every push, and each one exists because the others cannot do its work:

Job	Build	What it is for
cmake_build	Debug + AKGL_COVERAGE=ON	The unit suites and the coverage report. The perf suites run here too, at AKGL_BENCH_SCALE=0.02, for path coverage only — a timing taken under gcov is a measurement of gcov.
performance	RelWithDebInfo	ctest -L perf. The only job where budgets are enforced, because tests/benchutil.h enforces them only when compiled optimized at full scale. Keeps the tables as an artifact.
memory_check	RelWithDebInfo	scripts/memcheck.sh, every suite under valgrind. Gates: a definite leak, an invalid access or a branch on uninitialised memory fails the build. Keeps the valgrind logs as an artifact.
mutation_test	Debug	One focused source file, so CI stays bounded.

The character suite is excluded wherever a whole run is selected: it fails deliberately, and pinning current-but-wrong behavior is not what it is for.

Coding Style

The canonical style is Emacs cc-mode stroustrup, with tabs enabled. This is not advisory — new and edited code must match what cc-mode produces, so that reindenting a region never shows up as a diff.

Emacs setup

.dir-locals.el in the repository root already applies the style to every c-mode buffer, so nothing needs configuring by hand:

((c-mode . ((c-file-style . "stroustrup")
            (indent-tabs-mode . t)
            (tab-width . 8)
            (fill-column . 100)
            (require-final-newline . t))))

Interactively: C-x h C-M-\ (mark-whole-buffer + indent-region) reindents the buffer. A correctly formatted file is a fixed point of that operation — reindenting must produce no change.

Reindenting from the command line

scripts/reindent.sh                 # reindent every tracked C source in place
scripts/reindent.sh src/tilemap.c   # reindent only the named files
scripts/reindent.sh --check         # list non-conforming files, change nothing

--check exits 1 when something needs reindenting and 2 if Emacs is missing, so it is usable from CI. The script drives Emacs in batch mode through scripts/reindent.el, which reindents, normalises leading whitespace to the canonical tab/space mix, strips trailing whitespace, and ensures a final newline. include/akgl/SDL_GameControllerDB.h is generated and always skipped.

Note that reindent.el deliberately does not use Emacs' tabify: that function's tabify-regexp is " [ \t]+", which is not anchored to the start of a line, so it rewrites runs of spaces anywhere and destroys the hand-aligned value columns in the bit-flag tables in actor.h and iterator.h. Only leading whitespace is ever rewritten.

The pre-commit hook

scripts/hooks/pre-commit reindents staged C sources before the commit is written. Enable it once per clone:

git config core.hooksPath scripts/hooks

It inspects the staged content rather than the working tree, so what lands in the commit is what was checked. When a file needs reindenting it is fixed in the working tree and re-staged — but only if the index and working tree agree for that file. If they differ, re-staging would sweep unstaged work into the commit, so the hook stops and tells you to reindent and stage it yourself. It steps aside during a merge, and warns rather than blocking if Emacs is unavailable. git commit --no-verify bypasses it.

For reference, cc-mode defines the style as:

("stroustrup"
 (c-basic-offset . 4)
 (c-comment-only-line-offset . 0)
 (c-offsets-alist . ((statement-block-intro . +)
                     (substatement-open      . 0)
                     (substatement-label     . 0)
                     (label                  . 0)
                     (statement-cont         . +))))

Indentation and whitespace

• 4 columns per level (c-basic-offset 4).

• Tabs are 8 columns wide and are used for indentation (indent-tabs-mode t, tab-width 8). Emacs emits the largest possible run of tabs and pads the remainder with spaces, which produces this ladder. Editors that expand tabs, or that assume a 4-column tab, will silently corrupt it:

  Depth	Columns	Bytes
  1	4	4 spaces
  2	8	TAB
  3	12	TAB + 4 spaces
  4	16	TAB TAB
  5	20	TAB TAB + 4 spaces

• No trailing whitespace. Files end with a single newline.

• case labels sit at the same column as their switch (label . 0).

• Continuation lines of a wrapped expression indent one level (statement-cont . +).

The whole tree conforms: scripts/reindent.sh --check is clean, and the pre-commit hook keeps it that way. Convert a file to the canonical style in its own commit, not mixed into a behavioral change.

Braces

• Function bodies open on their own line, in column 0.
• Control statements keep the brace on the same line, one space before it.
• else, else if, and while of a do/while stay on the closing-brace line: } else {, not a bare else on the next line. Note that this is a house convention rather than something cc-mode enforces — the stroustrup style governs indentation only and will not move a brace or an else for you.
• Always brace, even single-statement bodies.

akerr_ErrorContext *akgl_actor_update(akgl_Actor *obj)
{
    if ( obj->curSpriteFrameId == 0 ) {
        obj->curSpriteReversing = false;
    } else if ( obj->parent != NULL ) {
        obj->curSpriteFrameId -= 1;
    } else {
        obj->curSpriteFrameId += 1;
    }
}

Spacing

• Spaces inside control-flow parentheses: if ( x == y ) {, while ( done == false ) {, for ( i = 0; i < len; i++ ) {. This is the dominant existing convention (140 sites to 7) and cc-mode will not add or remove it.

• No space between a function name and its argument list, at both call and definition sites, and no padding inside call parentheses: SDL_Log("x %d", n).

• Binary operators and assignment are surrounded by single spaces; unary operators are not separated from their operand.

• The pointer * binds to the identifier, not the type: char *name, akgl_Actor **dest. Never char* name.

• When a call is too long for one line, put each argument on its own line indented one level past the callee, with the closing ) on its own line. This is the established shape for the FAIL_* and CATCH macros:

  FAIL_ZERO_RETURN(
      errctx,
      SDL_SetPointerProperty(AKGL_REGISTRY_ACTOR, name, (void *)obj),
      AKERR_KEY,
      "Unable to add actor to registry"
      );
  

No repository-wide formatter

There is no clang-format or linter wired into the build, and cc-mode's indentation engine is not exactly reproducible by clang-format. Do not introduce one without discussion, and do not reformat code you are not otherwise changing — unrelated whitespace churn makes review harder and is the reason the style drifted in the first place.

Naming Conventions

• Public functions: akgl_<subsystem>_<verb>, all lower snake_case — akgl_actor_set_character, akgl_heap_next_string. No camelCase, and never embed a type name (akgl_Actor_cmhf_left_on is wrong; it should be akgl_actor_cmhf_left_on).

• Public types: akgl_TypeName — akgl_Actor, akgl_SpriteSheet, akgl_PhysicsBackend. Every type exported from a header takes the prefix. point and RectanglePoints shipped bare until 0.5.0; they are akgl_Point and akgl_RectanglePoints now, and neither is precedent.

• Constants and macros: AKGL_UPPER_SNAKE_CASE. A constant belongs to the subsystem it describes: a character limit is AKGL_CHARACTER_MAX_*, not AKGL_SPRITE_MAX_CHARACTER_*. Name a constant for what its value is — a nanoseconds-per-millisecond scale factor is AKGL_TIME_ONEMS_NS.

• Exported globals take the akgl_ prefix like any other public symbol. Do not add bare names (renderer, camera, window), leading-underscore names (reserved at file scope), or SCREAMING_SNAKE names for mutable objects — AKGL_UPPER_SNAKE_CASE is for constants.

  This one is not cosmetic and there is a scar to prove it. Until 0.5.0 the library exported renderer, and tests/character.c defined a SDL_Renderer *renderer of its own. Both had external linkage and the same spelling, so the executable's definition preempted the shared library's: the library read a SDL_Renderer * through an akgl_RenderBackend *, every texture load in that suite failed, and the suite reported success anyway. A consuming game with a variable called renderer would have hit the same thing with no test to notice.

• static helpers drop the akgl_ prefix, which exists only to avoid external collisions.

• Include guards: _AKGL_<FILE>_H_, matching the file name. Guard names without the project prefix risk colliding with system headers.

• Parameter names must match between the declaration and the definition — Doxygen publishes the header spelling. Conventional names: dest for an output parameter (not dst), self for a backend receiver, obj for the instance being initialized or inspected, e for an incoming error context to be inspected.

• The local error context is named errctx (92 sites to 45). New code uses errctx; convert e when you touch a function for other reasons.

• Header/source pairs are named by feature: include/akgl/sprite.h and src/sprite.c.

Error-Handling Protocol

The akerror control-flow macros have a shape that must be followed exactly, because the failure mode is silent.

• Inside an ATTEMPT block use the _BREAK variants (FAIL_ZERO_BREAK, FAIL_NONZERO_BREAK, FAIL_BREAK) and CATCH. Outside it use the _RETURN variants.
• Never use a *_RETURN macro inside an ATTEMPT block. It returns past the CLEANUP block, so every release, fclose, and free in CLEANUP is skipped. This has already caused a heap-string leak on the success path of akgl_get_json_tilemap_property.
• CLEANUP must precede PROCESS. Transposing them moves the cleanup body into the PROCESS switch, where it runs only when an error context exists.
• CATCH reports failure by breaking, which binds to the innermost enclosing loop or switch. A CATCH written directly inside a while exits the loop rather than the function — put the ATTEMPT block inside the loop.
• Never return from inside a HANDLE block either. FINISH ends with RELEASE_ERROR, so leaving before it means the handled context is never given back to AKERR_ARRAY_ERROR — one leaked slot per call, and the 129th call aborts the process with "Unable to pull an error context from the array!". SUCCEED_RETURN is safe because it releases first; a bare return, or a return f(...) that tail-calls the fallback, is not. Set a flag in the HANDLE block and act on it after FINISH. This has already cost a process-killing leak in akgl_path_relative; see TODO.md, "Performance".
• Validate every pointer parameter before dereferencing it, including the ones a sibling function happens not to check.

API Surface

Every function with external linkage must be declared in a header, and every declaration must have a definition. A non-static function that appears in no header is still in the ABI but is unreachable by callers; a declaration with no definition is a link error for anyone compiling against the header alone. If a function is exposed only so tests can reach it, declare it under the existing "part of the internal API" comment block in the relevant header.

Headers must be self-contained: include what you use, so that a translation unit including a single akgl header compiles without a particular include order. Within the project use the angled form, #include <akgl/sibling.h>.

This is enforced. AKGL_PUBLIC_HEADERS in CMakeLists.txt lists every header installed into include/akgl/, and drives two things from that one list: what install() ships, and a generated translation unit per header — each including exactly that header and nothing before it — linked into the headers suite. A new header is covered by adding it to that list. One header per translation unit is the only shape that proves anything: a second #include after the first proves nothing about the second, because by then the first has dragged its dependencies in.

Declare no-argument functions as (void), not ().

Rules

• Add yourself (agent program name, model name and version) as a co-author on every commit message
• Avoid dynamic memory allocation. Use the akgl_heap_* methods to retrieve necessary objects at runtime, and to release them when done. If the akgl heap facilities don't provide the kind of object needed, create a new heap layer to support that type of object.

Testing Guidelines

Tests use simple executable return codes and are registered through CTest in CMakeLists.txt; there is no declared coverage threshold.

Every suite's main() must call TEST_TRAP_UNHANDLED_ERRORS() immediately after akgl_error_init(). libakerror's default unhandled-error handler ends in exit(errctx->status), exit keeps only the low byte, and libakgl's status band starts at 256 — so a suite that failed with AKGL_ERR_SDL exited 0 and CTest recorded a pass. That is not hypothetical: tests/character.c aborted at its second of four tests on a bad renderer and was green until 0.5.0. The trap in tests/testutil.h collapses any status a byte cannot carry onto 1. Add focused tests as tests/<feature>.c, create a matching test_<feature> target, and register it with add_test. Put reusable fixtures in tests/assets/ and keep paths compatible with tests launched from the build tree. Coverage mode wraps the suite in a CTest fixture so counters are reset before tests and reports are generated afterward.

Performance suites

tests/perf.c (nothing that draws) and tests/perf_render.c (everything that does) are benchmarks, built and registered like any other suite but listed in AKGL_PERF_SUITES so they carry the perf label and a longer timeout. The harness is tests/benchutil.h. Three rules keep the numbers honest, and all three were learned by getting them wrong first:

• Nothing that checks an error goes inside the clock. PASS and CATCH call akerr_valid_error_address, which walks AKERR_ARRAY_ERROR — more work than several of the calls being measured. Use BENCH_LOOP, which stashes the context and stops at the first failure, and hand it to PASS afterwards.
• Flush the renderer before stopping the clock. SDL batches: a draw_* call queues a command and returns. BENCH_FLUSH_STOP in tests/perf_render.c is there because the first version of that suite measured queueing, reported a tilemap frame 250 times faster than it is, and paid the real cost at teardown inside SDL_DestroyTexture.
• A drawing benchmark needs a raw-SDL control that does the same pixel work. Without one there is no way to separate what libakgl costs from what the rasterizer costs, and the answer is not the one you would guess — see PERFORMANCE.md.

Budgets are per-operation ceilings at roughly ten times the recorded baseline; they are enforced only in an optimized build at full scale. When a change moves a number for a good reason, re-record the baseline in PERFORMANCE.md in the same commit and say why it moved.

These two suites are also the memory-check vehicle. tests/benchutil.h detects valgrind from LD_PRELOAD and drops the scale to AKGL_BENCH_VALGRIND_SCALE, so the same binaries walk every path once instead of a hundred thousand times, and the timings a checked run prints are labelled as meaningless. Do not add memory-check suites: a new path worth checking belongs in a benchmark, where it gets both.

Commit & Pull Request Guidelines

Recent commits use concise, imperative summaries such as Fix a scale bug... and often explain related changes in one sentence. Keep each commit scoped and describe user-visible behavior. Pull requests should summarize the change, identify affected modules, list the CMake/CTest commands run, and link relevant issues. Include screenshots only for rendering, map, or charviewer changes.