Andrew Kesterson
07c448508b
Bump deps/libakerror 22 commits to 5ff8790 (1.0.0), which makes the status-name table private, moves consumer status codes to a band starting at AKERR_FIRST_CONSUMER_STATUS, enforces range ownership rather than treating it as advisory, and gives the library an soname. See deps/libakerror/UPGRADING.md. src/stdlib.c needed no changes. This library defines no status codes of its own -- it raises libakerror's AKERR_* codes and propagates errno, both inside libakerror's reserved 0-255 band -- and it never referenced AKERR_MAX_ERR_VALUE, __AKERR_ERROR_NAMES, AKERR_STATUS_RANGE_OK or AKERR_STATUS_NAME_OK. What moved was everything around the code: A -DAKSL_COVERAGE=ON build stopped configuring at all. libakerror namespaces its `mutation` target when embedded but not its `coverage` target, so it collided with ours. Shadow add_custom_target for the duration of the add_subdirectory() call and rename the dependency's to akerror_coverage, alongside the existing add_test shadow. Fix upstream and delete the workaround; recorded in TODO.md. Pin the 1.0.0 floor three ways, since no single one covers every consumption path: an #error in akstdlib.h feature-testing AKERR_FIRST_CONSUMER_STATUS, because libakerror publishes no version macro; Requires: akerror >= 1.0.0 in akstdlib.pc, which also gets consumers -lakerror transitively; and find_dependency(akerror) in akstdlibConfig.cmake. The last was already broken before this bump -- the template still carried its MyLibraryConfig placeholder with the dependency commented out, so any external find_package(akstdlib) failed with a bare "akerror::akerror not found" out of the generated targets file. Branch coverage of src/stdlib.c fell from 51.0% to 44.3% with no source or test change: the 1.0.0 PREPARE_ERROR/FAIL_* macros expand to more branches at every call site, so 337/661 became 481/1087 -- 144 more branches covered, 426 more counted. Line coverage held at 99.0% (200/202) and function coverage at 100% (21/21). Re-ratchet the CI branch gate 45 -> 40 rather than chase branches that belong to libakerror's own suite. tests/test_status_registry.c pins the contract that made the status-code migration a no-op: libakstdlib reserves no consumer range, so an application may allocate from AKERR_FIRST_CONSUMER_STATUS without coordinating with it, and every status this library raises is inside the reserved band with a name actually registered -- an unnamed one degrades to "Unknown Error" in every later stack trace, which nothing else would notice. It exercises the new ownership enforcement too, so the "reserves nothing" assertion cannot pass vacuously. ctest 13/13, ASan+UBSan 13/13, coverage 15/15 at 90/40, mutation 89.6% (155/173, unchanged). Also verified out of tree: the #error fires as the first diagnostic against a stale akerror.h, pkg-config refuses akerror 0.9.0, and an external find_package(akstdlib) consumer builds and runs against a temp-prefix install. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.5 KiB
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:
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:
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:
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.
src/stdlib.c is at 99.0% line coverage and CI gates it at 90 (line) / 40
(branch), so new code needs tests in the same commit. Run
cmake --build build-coverage --target coverage and check the uncovered-line
listing before proposing a change. Tests for behaviour that TODO.md records as
defective belong in AKSL_KNOWN_FAILING_TESTS asserting the correct contract —
do not pin current-but-wrong behaviour in AKSL_TESTS, since that turns the
eventual fix into a test failure.
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.