Andrew Kesterson
82c47ed773
New AKSL_COVERAGE option instruments the library and its tests with --coverage -O0 and wires the report into the suite itself, so a plain ctest --test-dir build-coverage both runs the tests and produces coverage. Two CTest entries do the work, held in order by a CTest fixture rather than by declaration order so they also hold under ctest -j: coverage_reset (FIXTURES_SETUP) clears the .gcda counters before any test, since gcov counts are cumulative and would otherwise fold in earlier runs; coverage_report (FIXTURES_CLEANUP) aggregates gcov output afterwards. AKSL_COVERAGE_THRESHOLD / AKSL_COVERAGE_BRANCH_THRESHOLD gate the report, the same regression-ratchet idea as the mutation score. The `coverage` target builds, runs and prints in one step. scripts/coverage.py parses gcov's JSON output, aggregates line, branch and function counts across translation units, and lists every uncovered line and never-called function -- the actionable half, as with surviving mutants. Python stdlib plus gcc's own gcov only: no lcov, gcovr or genhtml. It also writes coverage-summary.txt (CTest hides the output of a passing test) and a Cobertura coverage.xml for CI publishers. Instrumentation is per target, so deps/libakerror stays out of the report. The mutation harness now ignores build*/ and gcov artifacts when copying the tree, so a coverage build does not slow it down. Baseline on src/stdlib.c: 52.0% of lines, 23.6% of branches, 8 of 21 functions. The uncovered functions are the untested wrappers the mutation survivors already point at (printf, ato*, stream, realpath, strhash). Verified: cmake -S . -B build-coverage -DAKSL_COVERAGE=ON cmake --build build-coverage --target coverage # 8/8, report printed ctest --test-dir build-coverage -j8 # fixture order holds cmake -S . -B build-coverage -DAKSL_COVERAGE=ON -DAKSL_COVERAGE_THRESHOLD=60 ctest --test-dir build-coverage --output-on-failure # gate fails as expected ctest --test-dir build --output-on-failure # 6/6, no .gcda emitted ctest --test-dir build-asan --output-on-failure # 6/6 scripts/mutation_test.py --target src/stdlib.c --list # 173 mutants, unchanged Totals match gcov itself: 51.98% of 202 lines, 23.60% of 661 branches. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
`libakstdlib` is a C shared library that wraps libc calls and small data
|
|
structures in `libakerror` error contexts. Public API declarations live in
|
|
`include/akstdlib.h`; implementation lives in `src/stdlib.c`. Tests are
|
|
one-file CTest executables under `tests/test_<name>.c`, with shared test helpers
|
|
in `tests/aksl_capture.h`. CMake package templates are in `cmake/` and
|
|
`akstdlib.pc.in`. The vendored dependency is `deps/libakerror`; update it as a
|
|
submodule rather than editing generated files under `build/`, `build-asan/` or
|
|
`build-coverage/`.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Initialize dependencies before a fresh build:
|
|
|
|
```sh
|
|
git submodule update --init --recursive
|
|
cmake -S . -B build
|
|
cmake --build build
|
|
```
|
|
|
|
Run the normal suite with `ctest --test-dir build --output-on-failure`. Use the
|
|
instrumented build for memory and undefined-behavior checks:
|
|
|
|
```sh
|
|
cmake -S . -B build-asan -DAKSL_SANITIZE=ON
|
|
cmake --build build-asan
|
|
ctest --test-dir build-asan --output-on-failure
|
|
```
|
|
|
|
For coverage, configure a third tree; the report is part of that suite (the
|
|
`coverage_reset` / `coverage_report` CTest entries) and also lands in
|
|
`build-coverage/coverage-summary.txt`:
|
|
|
|
```sh
|
|
cmake -S . -B build-coverage -DAKSL_COVERAGE=ON
|
|
cmake --build build-coverage --target coverage
|
|
```
|
|
|
|
Run `cmake --build build --target mutation` only when you need the slower
|
|
mutation harness. `rebuild.sh` installs to `/home/andrew/local` and removes the
|
|
local build directory, so treat it as a local convenience script.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use C with 4-space indentation; existing files sometimes use tabs for continued
|
|
statements, so match the surrounding block. Public symbols use the `aksl_`
|
|
prefix, structs use `aksl_<Name>`, and tests use `test_<feature>.c` plus static
|
|
`test_<case>` functions. Preserve the `akerr_ErrorContext AKERR_NOIGNORE *`
|
|
return convention and the `PREPARE_ERROR` / `FAIL_*` / `SUCCEED_RETURN` pattern.
|
|
|
|
## Testing Guidelines
|
|
|
|
Add a new test by creating `tests/test_mything.c` and adding `mything` to the
|
|
right list in `CMakeLists.txt`. `AKSL_TESTS` must exit zero.
|
|
`AKSL_WILL_FAIL_TESTS` are deliberate abort/contract tests.
|
|
`AKSL_KNOWN_FAILING_TESTS` assert documented defects from `TODO.md`; when one
|
|
starts unexpectedly passing, move it into `AKSL_TESTS` with the fix.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
Recent commits use short imperative summaries, for example `Add memory wrapper
|
|
tests` and `Make error-status assertions authoritative`. Keep commits focused
|
|
and include tests with behavior changes. Pull requests should describe the
|
|
changed API or behavior, list the CTest/sanitizer/mutation commands run, and
|
|
link the relevant `TODO.md` item or issue when fixing a known defect.
|
|
|
|
## Agent-Specific Instructions
|
|
|
|
Do not modify generated build trees, profiling artifacts, or untracked scratch
|
|
files unless explicitly asked. Prefer small, test-backed changes and update
|
|
`README.md` or `TODO.md` when changing documented workflows or known failures.
|