Andrew Kesterson
125eeb2109
Closes what was left of TODO.md sections 1, 2 and 3, and rewrites that
file to hold outstanding items only.
The API break gets a minor bump, because pre-1.0 the soname carries
MAJOR.MINOR and 0.1 and 0.2 are therefore different ABIs. Five
signatures changed and the ato* contract with them; UPGRADING.md is new
and lists every one, with the before/after for the cases the compiler
cannot warn about.
Section 3.1 is finished: reallocarray with the multiplication checked,
aligned_alloc and posix_memalign, asprintf/vasprintf, scanf/vscanf.
Four functions on that list are deliberately absent rather than missing
-- sprintf, strtok, setbuf and perror -- and TODO.md now says which and
why, so nobody adds them thinking they were forgotten.
Section 1.9, the cross-cutting tests:
tests/test_pool.c drives every failure path AKERR_MAX_ARRAY_ERROR
+ 10 times and checks the pool after each round,
because a wrapper that leaks a slot fails a
hundred calls later in unrelated code. It also
asserts that each error names the function and
file it was raised from, which is what catches a
FAIL that migrates into a helper during a
refactor: status right, message right, origin
quietly lying.
tests/negative/ two sources that must FAIL to compile, built with
-Werror and registered WILL_FAIL. AKERR_NOIGNORE
and the format attributes are enforced by the
compiler and by nothing else; drop either and
every ordinary test still passes.
Thread safety is answered rather than tested: the library is not
thread-safe and cannot be made so from here, because libakerror's error
pool is an unlocked process-global array. README.md says so plainly and
TODO.md carries it as the item blocking any future pthread wrappers.
Doxygen is configured and gated. All 147 public functions have @brief,
a @param each, @throws per status and @return; EXTRACT_ALL is off and
WARN_NO_PARAMDOC on, so `cmake --build build --target docs` fails on an
undocumented entity. It ran to 0 warnings. The Doxyfile carries no
version -- cmake/RunDoxygen.cmake feeds PROJECT_NUMBER in from
project(), so that stays the one place a version is written.
CI now builds against the submodule it pins instead of also installing
libakerror@main and never linking it, adds -Werror, and gains a
sanitizer job. The pre-push hook matches, and runs the docs check too.
Coverage: 99.5% of lines (1643/1651), 100% of functions (147/147). The
eight uncovered lines are each uncovered on purpose and TODO.md says
which and why.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
6.0 KiB
Repository Guidelines
Project Structure & Module Organization
libakstdlib is a C shared library that wraps libc calls and data structures in
libakerror error contexts.
Public API declarations live in include/akstdlib.h, which is also where the
Doxygen documentation lives -- the header is the contract, the sources carry the
reasoning. The implementation is split by domain:
| File | Covers |
|---|---|
src/stdlib.c |
memory, formatted output, string-to-number, realpath, djb2, and the list/tree traversal entry points |
src/string.c |
the string.h surface |
src/stream.c |
stdio.h beyond open/read/write/close |
src/collections.c |
list and tree operations, hash map, string buffer, FNV-1a |
src/aksl_internal.h |
shared internals; not installed, not public |
Tests are one-file CTest executables under tests/test_<name>.c, with shared
helpers in tests/aksl_capture.h. tests/negative/ holds sources that must
fail to compile -- see the testing section below. 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, and cmake --build build --target docs to regenerate the API
documentation -- that one fails if any public function, parameter or return value
is undocumented, so it is a check as well as a generator.
.githooks/pre-push runs the default build, the sanitizer build and the
documentation check before a push; enable it with
git config core.hooksPath .githooks. 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.
Four conventions hold across the whole library, and a new wrapper that breaks one of them is wrong even if it compiles and passes:
- A NULL out-param is a caller error, not "don't care".
- Finding nothing is success -- searching functions write NULL or zero and return NULL.
- Truncation is a failure. Take the destination's size, raise AKERR_OUTOFBOUNDS, and write nothing rather than a prefix.
- Clear
errnobefore the wrapped call and read it back throughAKSL_ERRNO_OR, so no error can carry status 0 -- which every downstreamDETECTreads as success.
Every new public function needs a Doxygen block on its declaration with
@brief, a @param per parameter, a @throws per status it can raise, and
@return. The docs target fails otherwise.
The build is -Wall -Wextra and CI adds -Werror. -Wpedantic is deliberately
off: libakerror's FAIL_* macros trip "ISO C99 requires at least one argument
for the ..." on their own expansion, not on anything at the call site.
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. Both of the
latter are currently empty -- all six confirmed defects are fixed -- but the
mechanism stays for the next one.
tests/negative/ holds sources that must fail to compile. Each is an
EXCLUDE_FROM_ALL target built with -Werror and registered as a WILL_FAIL
CTest entry, so the test passes only when the compile fails. They cover the two
guarantees the compiler enforces and nothing else does: AKERR_NOIGNORE and the
format attributes. Drop either in a refactor and every ordinary test still
passes.
Coverage is 99.5% of lines and 100% of functions across all four sources; CI
gates 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.