Andrew Kesterson
9f0034a56e
scripts/coverage.py configures an instrumented build tree (-DAKERR_COVERAGE=ON), runs the CTest suite in it, and reports merged gcov line/branch/function coverage per library source. Like the mutation harness it has no third-party dependencies and supports --threshold and --junit; thresholds gate each file as well as the total so the generated status-name table cannot mask a regression in src/error.c. Only the library is instrumented. The public header's macros cannot be measured this way -- GCC attributes an expanded macro to its call site, so header logic would report as lines of the test that used it -- which is what mutation testing against include/akerror.tmpl.h is for. Coverage flags are applied per target rather than globally, so they do not leak into the exported/installed target interface. Current numbers for src/error.c are 94.0% line and 59.5% branch; the CI gate is set to 90/50 to keep headroom, matching the convention used for the mutation score threshold. Tests run: ctest (23/23), cmake --build build --target coverage, threshold gate verified failing at --threshold 99, cmake --install checked for flag leakage, out-of-tree --build-dir checked. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
This is a small C library built with CMake. Core implementation lives in
|
|
`src/error.c`. The public header is generated at build time from
|
|
`include/akerror.tmpl.h` by `scripts/generrno.sh`, which also generates
|
|
`src/errno.c` under the build directory. CMake package and pkg-config templates
|
|
are in `cmake/` and `akerror.pc.in`. Tests are one-file C programs in `tests/`;
|
|
shared test helpers live beside them, such as `tests/err_capture.h`.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Use an out-of-tree build:
|
|
|
|
```sh
|
|
cmake -S . -B build
|
|
cmake --build build
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
`cmake -S . -B build` configures the build and generates `akerror.h`.
|
|
`cmake --build build` compiles `libakerror` and test executables. `ctest`
|
|
runs the registered unit tests. To emit CI-style results, use:
|
|
|
|
```sh
|
|
ctest --test-dir build --output-on-failure --output-junit "$(pwd)/ctest-junit.xml"
|
|
```
|
|
|
|
Mutation testing is available through:
|
|
|
|
```sh
|
|
cmake --build build --target mutation
|
|
scripts/mutation_test.py --target src/error.c --threshold 65
|
|
```
|
|
|
|
Code coverage is available through:
|
|
|
|
```sh
|
|
cmake --build build --target coverage
|
|
scripts/coverage.py --threshold 90 --branch-threshold 50
|
|
```
|
|
|
|
`scripts/coverage.py` configures its own instrumented build tree (default
|
|
`build/coverage`, `-DAKERR_COVERAGE=ON`), runs the CTest suite there, and
|
|
reports gcov line/branch coverage per library source. Thresholds gate each
|
|
file as well as the total. Coverage measures `src/error.c` and the generated
|
|
`src/errno.c` only; the public header's macros expand at their call sites, so
|
|
mutation testing is what checks those.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use C99-compatible C and follow the surrounding style. Functions and types use
|
|
the `akerr_` prefix; macros and constants use `AKERR_` or all-caps macro names
|
|
such as `PREPARE_ERROR`. Keep generated-code changes in templates or generator
|
|
scripts, not in build outputs. Preserve concise comments for invariants,
|
|
macro constraints, and non-obvious error lifecycle behavior.
|
|
|
|
## Testing Guidelines
|
|
|
|
Add tests as `tests/err_<behavior>.c`. Register each new test in the
|
|
`AKERR_TESTS` list in `CMakeLists.txt`; tests that intentionally abort must
|
|
also be listed in `AKERR_WILL_FAIL_TESTS`. Prefer focused executable tests that
|
|
return zero on success and use existing helpers such as `AKERR_CHECK`. Run the
|
|
CTest suite before submitting changes, and run mutation testing and coverage
|
|
when changing core control-flow, reference counting, stack-trace, or handler
|
|
behavior.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
Recent commits use short, imperative, sentence-case subjects, for example
|
|
`Fix refcount leak and stack-trace buffer overflow`. Keep commits focused and
|
|
describe the observable behavior changed. Pull requests should include a brief
|
|
summary, tests run, and any compatibility impact for public macros, generated
|
|
headers, installation paths, or CMake/pkg-config consumers.
|
|
|
|
## Agent-Specific Instructions
|
|
|
|
Do not overwrite uncommitted user changes. Avoid editing generated files in
|
|
`build/`; update `include/akerror.tmpl.h`, `src/error.c`, CMake files, tests,
|
|
or scripts instead.
|