libakerror/docs/building.md

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. Must be none when AKERR_USE_STDLIB is OFF — the pthread backend calls into libc, and the configure fails otherwise.
AKERR_USE_STDLIB	ON	Link against the C standard library. See Dependencies for what you must supply instead when this is OFF.
AKERR_RUNTIME_HEADER	(empty)	Mandatory when AKERR_USE_STDLIB is OFF. Header providing exit, memset, snprintf, strcmp, strlen and strncpy; the generated header #errors at compile time if it is unset. Defaults to a thin, libc-backed convenience header (cmake/akerr_default_runtime.h) so this repository's own OFF build and test suite work without a real freestanding runtime — a genuinely freestanding consumer should override it with their own header.
AKERR_MAX_ERROR_FNAME_LENGTH	4096	Bytes reserved for the fname/function fields of akerr_ErrorContext. Defaults to PATH_MAX on Linux/glibc, which keeps sizeof(akerr_ErrorContext) and the soname unchanged; changing it is an ABI break.
AKERR_LAST_ERRNO_VALUE_FALLBACK	133	AKERR_LAST_ERRNO_VALUE to stamp when AKERR_USE_STDLIB is OFF, since that configuration cannot shell out to errno --list. Defaults to 133 (Linux's EHWPOISON).
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.

Behavior change (2.0.2): pool exhaustion inside ENSURE_ERROR_READY (every context-producing macro goes through it) used to call exit(1) directly. It now calls akerr_exit(AKERR_EXIT_STATUS_UNREPRESENTABLE), so a process that runs out of pool slots exits 125 instead of 1. See UPGRADING.md.

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:

1. When AKERR_USE_STDLIB is ON: executes errno --list and gathers up the output. When it is OFF, this is skipped entirely (errno --list needs moreutils and <errno.h>, neither freestanding-safe) and AKERR_LAST_ERRNO_VALUE is taken from the AKERR_LAST_ERRNO_VALUE_FALLBACK cache variable instead.
2. Templates include/akerror.tmpl.h into include/akerror.h to set AKERR_LAST_ERRNO_VALUE, AKERR_THREAD_SAFE, and AKERR_MAX_ERROR_FNAME_LENGTH.
3. Generates src/errno.c, which contains a function called by akerr_init that initializes all of the status names for the previously defined values of errno. Under AKERR_USE_STDLIB=OFF this file is a stub, and CMake does not compile it into the library at all — akerr_init_errno() is never called in that configuration.

Neither generated 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, build with -DAKERR_USE_STDLIB=OFF (which requires -DAKERR_THREADS=none — see the options table above) and supply a header, via the AKERR_RUNTIME_HEADER cache variable, that provides:

• memset function
• strncpy function
• strlen function
• strcmp function
• snprintf function
• exit function
• bool type
• NULL type
• size_t type
• INT_MAX constant

<stdbool.h> and <stddef.h> — which give you bool/NULL/size_t — are included unconditionally by the public header regardless of AKERR_USE_STDLIB, since both are freestanding-safe. AKERR_RUNTIME_HEADER is mandatory in this configuration: the generated header #errors at compile time if it is unset.

... then you can compile it thusly:

cmake -S . -B build -DAKERR_USE_STDLIB=OFF -DAKERR_THREADS=none \
    -DAKERR_RUNTIME_HEADER=/path/to/your/runtime.h
cmake --build build
cmake --install build

If you omit -DAKERR_RUNTIME_HEADER, the build falls back to a convenience header backed by the host's own libc (see the options table above), so the OFF configuration still builds and its test suite still runs on an ordinary hosted machine — useful for exercising the freestanding code paths without a real freestanding runtime, but not what an actually freestanding consumer wants. Supply your own header to get the real thing.