# 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).