Andrew Kesterson
ff88f48fa2
Instrument libakgl in opt-in coverage builds, use CTest fixtures to reset counters and emit Cobertura XML and detailed HTML reports, and upload those reports from Gitea CI. Document the local coverage workflow for contributors. Co-authored-by: Codex (GPT-5) <noreply@openai.com>
3.6 KiB
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/, generated akgl.pc files, and include/akgl/SDL_GameControllerDB.h as build outputs rather than hand-maintained source.
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 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.
Coding Style & Naming Conventions
Follow the surrounding C style: braces on the next line for function bodies, spaces inside control-flow parentheses, and short, focused functions. Preserve the indentation of the file being edited; older files contain both spaces and tabs. Public symbols use the akgl_ prefix, public types use akgl_TypeName, and constants/macros use AKGL_UPPER_SNAKE_CASE. Name matching header/source pairs by feature, such as include/akgl/sprite.h and src/sprite.c. No repository-wide formatter or linter is configured, so avoid unrelated formatting churn.
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. 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.
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.