Andrew Kesterson
5695061130
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>
62 lines
2.8 KiB
Markdown
62 lines
2.8 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. See [TODO.md](../TODO.md).
|