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/, 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.

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.