Andrew Kesterson
dc1bd0a798
Port the scratch-copy mutation runner used by libakerror and libakstdlib, covering libakgl source files with sampling, thresholds, JUnit reports, and test timeouts. Add a CMake target and documentation, preserve the intentionally failing character test exclusion, and migrate the sprite test to the renderer backend so mutation baselines are green. Co-authored-by: Codex (GPT-5) <noreply@openai.com>
3.2 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.
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.
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.