Andrew Kesterson
5695061130
The README was 794 lines: the summary, the design rationale, the whole macro reference, the threading contract, the build internals and the exit-status specification in one file. It is now 178 lines -- summary, installation, quickstart, and an index -- and the reference material lives in docs/, one file per topic: architecture, usage, status-codes, uncaught-errors, exit-status, thread-safety, building. The prose moved as written. Inbound references followed it: UPGRADING.md, TODO.md, include/akerror.tmpl.h and tests/err_threads_handoff.c now name the docs/ file that owns the text they cite, and AGENTS.md says where new documentation goes so the README does not grow back. Five factual errors fixed in the moved text: - Both NULL-pointer examples inverted their test. FAIL_ZERO_* fails when the expression is zero, so `(somePointer == NULL)` failed on a *valid* pointer. They now read `(somePointer != NULL)`. - AKERROR_NOIGNORE, four times including the #define, is AKERR_NOIGNORE. - FINISH_NORExbTURN is FINISH_NORETURN. - "functiions" is "functions". - The architecture link pointed at include/akerror.h, which is generated and not in the tree; it points at include/akerror.tmpl.h. The quickstart is new text. It compiles under -Wall -Wextra -Werror and was run through all three of its paths: handled usage error exits 0, unhandled IO error prints a trace and exits with the status, success exits 0. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.8 KiB
Building libakerror
The ordinary build is an out-of-tree CMake build, described in the README. This file covers what the build generates for you, what it links against, and the configure options that change either of those.
Configure options
| Option | Default | What it does |
|---|---|---|
AKERR_THREADS |
auto |
Threading backend: auto, pthread, or none. auto takes POSIX threads and fails the configure if it cannot find them. See Building single threaded. |
AKERR_USE_STDLIB |
ON |
Link against the C standard library. See Dependencies for what you must supply instead when this is OFF. |
AKERR_STATUS_NAME_SLOTS |
4096 |
Slots in the status-name table; 75% of it is usable. |
AKERR_MAX_RESERVED_STATUS_RANGES |
64 |
How many status ranges may be reserved in one process. |
AKERR_SANITIZE |
(empty) | Sanitizer list applied to the library and the tests, e.g. thread or address,undefined. |
AKERR_COVERAGE |
OFF |
Instrument the library with gcov counters. |
The two capacity options are applied PRIVATE: the tables live entirely in
src/error.c, so raising them never changes anything a consumer can see. See
UPGRADING.md for what happens when you exhaust them.
Templating and autogenerated code
The build process relies upon scripts/generrno.sh which performs the following:
- Executes
errno --listand gathers up the output - Templates
include/akerror.tmpl.hintoinclude/akerror.hto set theAKERR_LAST_ERRNO_VALUEequal to the highest integer defined byerrno - Generates
src/errno.cwhich contains a function called byakerr_initwhich initializes all of the status names for the previously defined values oferrno.
Neither output is meant to be edited. Change the template or the generator.
Dependencies
This library depends upon stdlib, and upon POSIX threads unless it is built
with -DAKERR_THREADS=none (see Thread safety). If you don't want to link against stdlib, you must modify the library code to include headers and link against a library that provides the following:
memsetfunctionstrncpyfunctionstrlenfunctionstrcmpfunctionsprintffunctionexitfunctionbooltypeNULLtypeINT_MAXconstantPATH_MAXconstant
... then you can compile it thusly:
cmake -S . -B build -DAKERR_USE_STDLIB=OFF
cmake --build build
cmake --install build
Known defect: that configuration does not currently compile. bool,
PATH_MAX and NULL are used unconditionally but only included under the
stdlib branch, so the header's includes need untangling before
-DAKERR_USE_STDLIB=OFF builds. The list above still states what a replacement
must provide. See TODO.md.