Andrew Kesterson
756933c600
src/error.c now scores 81.2%: 238 of 293 mutants killed, 204 by a failing test, 24 by failing to compile, and 10 by hanging the suite -- deleting akerr_mutex_init() or the akerr_initializing re-entry guard deadlocks the first test, which is the right answer for a broken lock. Lock deletions are the one survivor category where surviving does not mean harmless, so measure it rather than assume: rebuilt, the surviving "delete the pool lock" mutant fails tests/err_threads_pool.c in 4 of 10 runs and fails under scripts/thread_test.sh in 5 of 5, with no false positive on the unmutated library. The property assertions alone are a coin flip on a missing lock; the sanitizer run is what holds that line. The harness builds mutants with default CMake options and so never sees it -- TODO item 8. Also warn that a sanitized test binary run by hand does not inherit the halt_on_error CTest gives it, and will print a race and still exit 0. That is how the 5-of-5 above first read as 2 of 5. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
5.8 KiB
Repository Guidelines
Project Structure & Module Organization
This is a small C library built with CMake. Core implementation lives in
src/error.c. src/lock.h is private: it selects the threading backend
(pthread or none) and is not installed. 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 and stamps in whether the
build is thread safe. 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 and tests/err_threads.h.
Build, Test, and Development Commands
Use an out-of-tree build:
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:
ctest --test-dir build --output-on-failure --output-junit "$(pwd)/ctest-junit.xml"
The suite includes thread tests. The run that proves there is no data race under them is ThreadSanitizer:
scripts/thread_test.sh
which configures build/tsan with -DAKERR_SANITIZE=thread, builds the library
and the tests with it, and runs CTest with ASLR disabled (TSan aborts with an
"unexpected memory mapping" on kernels with vm.mmap_rnd_bits above 28).
AKERR_SANITIZE takes any sanitizer list, so -DAKERR_SANITIZE=address,undefined
works the same way. CTest gives each test halt_on_error=1, so a report fails
the test rather than being printed and passed over — running a sanitized test
binary by hand does not inherit that. Set it yourself
(TSAN_OPTIONS=halt_on_error=1 ./build/tsan/test_err_threads_pool) or the
binary can print a race and still exit 0.
Mutation testing is available through:
cmake --build build --target mutation
scripts/mutation_test.py --target src/error.c --threshold 65
Code coverage is available through:
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 the library's own sources only --
src/error.c, src/lock.h and the generated src/errno.c; the public header's
macros expand at their call sites, so mutation testing is what checks those.
To build without threads (no locking, no thread-local storage, thread tests not
registered), configure with -DAKERR_THREADS=none. auto is the default and
fails the configure rather than falling back.
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.
Locking. One recursive lock (akerr_state_lock, see src/lock.h) covers
both the error pool and the status registry. A function named *_locked is
called with that lock already held; a function without the suffix takes it.
Never take it in a body written with the FAIL_*_RETURN macros — those return
from the middle of the function and would skip the unlock. Split it instead: the
locked body does the work, and a thin wrapper takes the lock, calls it, and
releases it on the single return path. Do not call consumer code
(akerr_log_method, akerr_handler_unhandled_error) while holding it.
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.
Tests that drive the library from several threads go in the AKERR_THREAD_SAFE
branch of the AKERR_TESTS list — an -DAKERR_THREADS=none build has no
threading to test — and use tests/err_threads.h, which runs a body on
AKERR_TEST_THREADS threads that meet at a barrier first.
Count failures per thread with AKERR_TCHECK rather than returning early: a
thread that abandons its work leaves the others holding pool slots and turns one
failure into a cascade. Anything the test shares between its own threads must go
through __atomic builtins — a race in the test is still a race, and
ThreadSanitizer cannot tell you whose it is. The capturing logger in
err_capture.h is single-threaded (shared buffer, shared length); use
akerr_thread_logger instead. Run scripts/thread_test.sh when changing
anything that touches the pool, the registry, initialization, or the lock.
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.