Tachikoma
11cc5578fe
docs/building.md sent a reader to TODO.md for what a stdlib replacement must provide; the AKERR_USE_STDLIB=OFF build does not compile at all, which is issue #12, so it says that instead. Found while sweeping the consumer repositories: the handler macros trip -Wimplicit-fallthrough, which is why libakgl cannot adopt -Wextra. That was recorded only in libakgl and is now issue #18 -- the fourth defect in this library found written down in a consumer rather than here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# 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. That configuration does not currently compile -- `bool`, `PATH_MAX` and `NULL`
|
|
are used unconditionally but included only under the stdlib branch. See
|
|
[issue #12](https://source.starfort.tech/andrew/libakerror/issues/12).
|