ADR-0017: Target code uses a named subset of the standard library¶
- Status: Accepted
- Date: 2026-11-06
Context¶
The layers page and ADR-0010 call the headers a driver may include "the freestanding subset". They are not: in
C++20, <array>, <span>, <optional>, <cstring>, <cmath> and <algorithm> are hosted headers, available
on every embedded toolchain we use but not freestanding by the standard's definition. A rule named after a
standard term it contradicts invites argument about which list applies, and no tool can check "freestanding-friendly".
Decision¶
- The term is the target library subset: the standard headers code that runs on a microcontroller may use. It is an allow-list, not a description.
- Drivers may include exactly the headers in the Driver row of the include table on the Layers page
(
<cstdint>,<cstddef>,<array>,<algorithm>,<type_traits>,<concepts>,<limits>,<cmath>,<cstring>,<span>,<utility>,<optional>,<bit>), plus<cstdarg>for the optionalLoghook. - Other target code (kb-core, HALs, firmware) may also include
<atomic>,<chrono>(types and arithmetic; clocks come fromkb::rtos),<string_view>,<variant>,<tuple>,<iterator>,<numeric>,<new>(placement new only) and<cstdio>forsnprintfinto a caller's buffer. - No target code includes a header that allocates, throws or needs an operating system:
<string>,<vector>,<map>,<set>, the<unordered_*>and<list>/<deque>containers,<memory>,<functional>,<iostream>and the other stream headers,<thread>,<mutex>,<condition_variable>,<future>,<regex>,<filesystem>,<locale>,<exception>,<stdexcept>,<typeinfo>,<any>. - Algorithms that may allocate (
std::stable_sort,std::stable_partition,std::inplace_merge) are not used. - Host-only tests and tools are exempt.
The include-allowlist/driver and include-allowlist/target checks test each translation unit against these
lists.
Consequences¶
- The layers page and ADR-0010 say "target library subset" instead of "freestanding".
- Adding a header to the subset is a change to this record and to the include table.