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.
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:

1. Executes errno --list and gathers up the output
2. Templates include/akerror.tmpl.h into include/akerror.h to set the AKERR_LAST_ERRNO_VALUE equal to the highest integer defined by errno
3. Generates src/errno.c which contains a function called by akerr_init which initializes all of the status names for the previously defined values of errno.

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:

• memset function
• strncpy function
• strlen function
• strcmp function
• sprintf function
• exit function
• bool type
• NULL type
• INT_MAX constant
• PATH_MAX constant

... 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. That configuration does not currently compile -- bool, PATH_MAX and NULL are used unconditionally but included only under the stdlib branch. See issue #12.