docs/building.md

# Building libakerror

The ordinary build is an out-of-tree CMake build, described in
[the README](../README.md#installation). 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](thread-safety.md#building-single-threaded). |
| `AKERR_USE_STDLIB` | `ON` | Link against the C standard library. See [Dependencies](#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](../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
1. Templates `include/akerror.tmpl.h` into `include/akerror.h` to set the `AKERR_LAST_ERRNO_VALUE` equal to the highest integer defined by `errno`
2. 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](thread-safety.md)). 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. See [TODO.md](../TODO.md).
Split the README reference material into docs/ 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> 2026-08-01 16:56:07 -04:00			`# Building libakerror`

			`The ordinary build is an out-of-tree CMake build, described in`
			`[the README](../README.md#installation). 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](thread-safety.md#building-single-threaded). \|
			\| `AKERR_USE_STDLIB` \| `ON` \| Link against the C standard library. See [Dependencies](#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](../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
			1. Templates `include/akerror.tmpl.h` into `include/akerror.h` to set the `AKERR_LAST_ERRNO_VALUE` equal to the highest integer defined by `errno`
			2. 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](thread-safety.md)). 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. See [TODO.md](../TODO.md).`