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>
83 lines
3.5 KiB
Markdown
83 lines
3.5 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.
|
|
|
|
`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.
|