Build and CMake¶
How a repository builds, installs and is consumed.
| Rule | Level | Applies to | Verified |
|---|---|---|---|
| KB-BLD-001 The installed package works with find_package | must | driver, library, template | checked |
| KB-BLD-002 No file(GLOB) for library sources | must | driver, library, hal, template | checked |
| KB-BLD-003 The root CMakeLists.txt is also the ESP-IDF component | must | driver, library, template | planned |
| KB-BLD-004 One build-settings file holds the version, target name and source list | must | driver, library, template | planned |
| KB-BLD-005 Every copy of the version derives from or is tested against the build settings | must | driver, library, template | planned |
| KB-BLD-006 The same <chip>::<chip> target through add_subdirectory and find_package | must | driver, library, template | checked |
| KB-BLD-007 Install rules install every header the public API reaches | must | driver, library, template | checked |
KB-BLD-008 Standard options <CHIP>_BUILD_TESTS and <CHIP>_ENABLE_WARNINGS, both off by default |
must | driver, template | planned |
| KB-BLD-009 Compile flags and definitions are set per target, never globally | must | driver, library, hal, firmware, template | planned |
| KB-BLD-010 CMake configures without developer warnings | must | driver, library, hal, firmware, template | planned |
| KB-BLD-011 Header-only libraries are INTERFACE targets; compiled ones are STATIC | should | driver, library, template | review |
| KB-BLD-012 The root CMakeLists.txt declares the org's CMake minimum, 3.16 | should | driver, library, template | review |
| KB-BLD-013 Kconfig lives in _config/Kconfig and defines every CONFIG_ value the code reads | must | driver, library, template | checked |
| KB-BLD-014 The exported target itself builds warning-free with the org flag set | must | driver, library, hal, template | planned |
| KB-BLD-015 Supported compilers and toolchains are pinned and listed | must | driver, library, hal, firmware, template | planned |
| KB-BLD-016 Release builds are reproducible | should | library, hal, firmware (high level and above) | planned |
| KB-BLD-017 Image size and stack usage stay within recorded budgets | must | driver, library, hal, firmware (high level and above) | planned |
| KB-BLD-018 Firmware reports its version and the exact source of every pinned component | must | firmware | planned |
| KB-BLD-019 ESP-IDF builds set a 1 kHz FreeRTOS tick in sdkconfig.defaults | must | driver, hal, firmware, template | planned |
| KB-BLD-020 kb-core parts are separate targets with distinct include roots | must | library | planned |
| KB-BLD-021 Each build selects exactly one MCU family and one RTOS backend | must | library | planned |
| KB-BLD-022 Enabling an MCU-bound driver for the wrong MCU fails at configure time | must | library | planned |
| KB-BLD-023 kb-core options use the KB_ scheme and default to the smallest build | must | library | planned |
| KB-BLD-024 Enabling a module enables what it depends on, never the reverse | should | library | planned |
| KB-BLD-025 kb-core links each driver's target and never copies its file lists | must | library | review |
| KB-BLD-026 ESP-IDF REQUIRES follow the enabled options | should | library, hal | review |
| KB-BLD-027 Configure prints a summary of what is built | should | library, hal | review |
| KB-BLD-028 Keep CMake plain and linear | guide | driver, library, hal, firmware, template | none |
| KB-BLD-029 Depend on as little as possible | guide | driver, library, hal | none |
KB-BLD-001: The installed package works with find_package¶
MUST · driver, library, template · since 1.0
A library or driver installs a CMake package (<name>Config.cmake with an exported <name>::<name> target) that a
separate project finds with find_package and links; CI builds such a consumer.
Verified by:
cmake-consumer(implemented): the installed package is found and linked by a separate CMake project (find_package)
Explained in: standards/driver.md
KB-BLD-002: No file(GLOB) for library sources¶
MUST · driver, library, hal, template · since 1.0
Library targets list their sources explicitly; file(GLOB) is not used for sources or headers.
Why: A glob hides an added or removed file from review and from the build system's dependency tracking.
Verified by:
forbidden-patterns/cmake-glob(implemented): a source scan for a construct the handbook bans; the parameter names the pattern set
KB-BLD-003: The root CMakeLists.txt is also the ESP-IDF component¶
MUST · driver, library, template · since 1.0
Under ESP_PLATFORM the root CMakeLists.txt registers the repository as an ESP-IDF component and returns before
project(); there is no separate wrapper component. examples/esp32/ reaches it through EXTRA_COMPONENT_DIRS
pointing at the repository root, and kb-core maps its CONFIG_KB_* values onto its CMake options in that one place.
Why: One CMake entry point for every build system means the ESP-IDF build cannot drift from the host and find_package builds.
Verified by:
esp-idf-examples(planned): every app in examples/esp32 builds with the pinned ESP-IDF, using the repository root as its component (runs today in driver-template esp32-examples-build-ci.yml through ci-tools ru-build)- review: The root CMakeLists.txt is the ESP-IDF component; no wrapper component or extra CMake entry point.
See also: ADR-0011
Explained in: standards/driver.md
KB-BLD-004: One build-settings file holds the version, target name and source list¶
MUST · driver, library, template · since 1.0
cmake/<chip>_build_settings.cmake (cmake/kb_build_settings.cmake for kb-core, one version for all its parts) is the
only place the version, the target name, the options and the source list are written. It is guarded with
include_guard(GLOBAL), and the variables it sets carry the unbranded <CHIP>_ prefix.
Why: A value written twice is eventually written differently.
Verified by:
version-copies(planned): project(), the package version, the generated version header, Doxyfile PROJECT_NUMBER, driver.yml and the version getter all equal the version in the build settings (driver-template version ctests, less driver.yml)- review: Version, target name, options and sources are set only in the build-settings file.
See also: ADR-0012; ADR-0013; IEC 62304:2006+A1:2015 8.1.1 (configuration item identification)
Explained in: standards/driver.md
KB-BLD-005: Every copy of the version derives from or is tested against the build settings¶
MUST · driver, library, template · since 1.0
project(), the package version file, the generated <chip>_version.h (<CHIP>_VERSION_*), Doxyfile PROJECT_NUMBER,
driver.yml and GetDriverVersion() either derive from the build settings or are compared with them by a test. A
release changes the version in the build settings and the test proves the copies agree.
Verified by:
version-copies(planned): project(), the package version, the generated version header, Doxyfile PROJECT_NUMBER, driver.yml and the version getter all equal the version in the build settings (driver-template version ctests, less driver.yml)- review: A release pull request bumps the version only in the build settings and the version tests pass.
See also: IEC 62304:2006+A1:2015 8.1.1
KB-BLD-006: The same <chip>::<chip> target through add_subdirectory and find_package¶
MUST · driver, library, template · since 1.0
The library target has the alias <chip>::<chip> and EXPORT_NAME <chip>, so a consumer writes the same
target_link_libraries line whether it uses add_subdirectory() or the installed package. Targets carry no
organisation prefix.
Why: Submodule consumers and package consumers then differ only in how they find the code, never in what they link.
Verified by:
cmake-consumer(implemented): the installed package is found and linked by a separate CMake project (find_package)host-tests(implemented): the unit tests build and pass on the host with gcc and clang
See also: ADR-0012
Explained in: standards/driver.md
KB-BLD-007: Install rules install every header the public API reaches¶
MUST · driver, library, template · since 1.0
cmake --install installs every header the umbrella header includes, every .ipp, the generated version header and the
package configuration and version files, keeping the relative layout the includes rely on.
Verified by:
cmake-consumer(implemented): the installed package is found and linked by a separate CMake project (find_package)
KB-BLD-008: Standard options <CHIP>_BUILD_TESTS and <CHIP>_ENABLE_WARNINGS, both off by default¶
MUST · driver, template · since 1.0
The root CMakeLists.txt offers <CHIP>_BUILD_TESTS and <CHIP>_ENABLE_WARNINGS, both OFF by default, so a consumer
builds neither the tests nor the warning set unless it asks.
Verified by:
cmake-configure/standard-options(planned): a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-toggles- review: The two options exist with the standard names and default OFF.
Explained in: standards/driver.md
KB-BLD-009: Compile flags and definitions are set per target, never globally¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
CMake files set flags, definitions and include paths with target_* commands. add_compile_options, add_definitions,
include_directories and writes to CMAKE_CXX_FLAGS are not used.
Why: A global flag leaks into every consumer's build and into code it was never reviewed against.
Verified by:
forbidden-patterns/cmake-global-flags(planned): a source scan for a construct the handbook bans; the parameter names the pattern set
KB-BLD-010: CMake configures without developer warnings¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
The project configures cleanly with -Werror=dev --warn-uninitialized, for the host build and for every option
combination CI exercises.
Verified by:
cmake-configure/dev-warnings(planned): a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-toggles
KB-BLD-011: Header-only libraries are INTERFACE targets; compiled ones are STATIC¶
SHOULD · driver, library, template · since 1.0
A library with no sources is an INTERFACE target and one with sources is STATIC. Switching between the two changes
only the source list in the build settings.
Verified by:
- review: The target type matches whether the build settings list sources.
KB-BLD-012: The root CMakeLists.txt declares the org's CMake minimum, 3.16¶
SHOULD · driver, library, template · since 1.0
The root CMakeLists.txt starts with cmake_minimum_required(VERSION 3.16); a repository raises it only with a reason
in the pull request.
Why: ESP-IDF 5 and the vendor toolchains in use all ship CMake 3.16 or newer; asking for more locks some out.
Verified by:
- review: cmake_minimum_required is 3.16, or the pull request says why it is higher.
KB-BLD-013: Kconfig lives in _config/Kconfig and defines every CONFIG_ value the code reads¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, template · since 1.0 · enforced from 2027-03-01
A component with ESP-IDF options ships _config/Kconfig, registered through KCONFIG in the root CMakeLists.txt. Code
reads no CONFIG_* symbol that this file (or ESP-IDF itself) does not define, and compiles with every such value unset.
Why: A CONFIG_ name with no Kconfig behind it is silently never set, and its feature is silently off.
Verified by:
kconfig-symbols(planned): every CONFIG_ symbol the sources read is defined in _config/Kconfig or by ESP-IDFhost-tests(implemented): the unit tests build and pass on the host with gcc and clang
KB-BLD-014: The exported target itself builds warning-free with the org flag set¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, template · since 1.0 · enforced from 2027-03-01
CI compiles the library's own sources and every public header with <CHIP>_ENABLE_WARNINGS=ON, the org warning set,
-fno-exceptions -fno-rtti and -Werror, not only the test targets that include them.
Why: Today the flags reach a compiled library's sources only through the tests, so a STATIC target can ship code the warning set never saw.
Verified by:
exported-target-flags(planned): the library target's own sources and every public header compile with <CHIP>_ENABLE_WARNINGS=ON, the org warning set and -Werrorexceptions-rtti-off(planned): the exported library target compiles with -fno-exceptions -fno-rtti, not only the tests
KB-BLD-015: Supported compilers and toolchains are pinned and listed¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
The repository lists the compilers it supports (host gcc and clang, arm-none-eabi-gcc, the ESP-IDF release) with exact versions, and CI builds with exactly those versions. Changing one is a pull request of its own.
Why: An unpinned toolchain changes the warnings, the code generated and the static-analysis findings without any commit to blame; clang-tidy 18 and 20 already disagree on the same code.
Verified by:
toolchain-pins(planned): the repository lists exact versions of every supported compiler and ESP-IDF, and every CI build uses exactly those versions
See also: IEC 62304:2006+A1:2015 8.1.2 (SOUP identification, for the toolchain)
KB-BLD-016: Release builds are reproducible¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · library, hal, firmware (high level and above) · since 1.0 · enforced from 2027-03-01
Building the same tag twice with the pinned toolchain gives byte-identical artefacts: no __DATE__ or __TIME__, build
paths stripped with -ffile-prefix-map, and timestamps taken from SOURCE_DATE_EPOCH.
Why: An evidence package is only worth something if anyone can rebuild the binary it describes.
Verified by:
reproducible-build(planned): two clean builds of the same commit in different directories produce byte-identical artefacts
See also: IEC 62304:2006+A1:2015 8.1.1
KB-BLD-017: Image size and stack usage stay within recorded budgets¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware (high level and above) · since 1.0 · enforced from 2027-03-01
Firmware and example images are built with -fstack-usage. The repository records a flash, RAM and per-task stack
budget, and CI fails when a build exceeds one or a function's stack use is unbounded.
Why: Stack overflow on a microcontroller corrupts memory silently; a budget turns it into a build failure.
Verified by:
size-budget(planned): flash and RAM use of each built image stays within the budget recorded in the repositorystack-usage(planned): the target build with -fstack-usage reports every task entry and ISR within the stack budget in the repository's budget file; unbounded (dynamic) frames fail
See also: NASA/JPL Power of Ten Rule 1 (no recursion, so stack use is bounded)
KB-BLD-018: Firmware reports its version and the exact source of every pinned component¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · firmware · since 1.0 · enforced from 2027-03-01
Firmware embeds a header generated by CMake with its own version, the release train and the tag and commit SHA of every pinned submodule, and reports them at start-up and on request. No version is hard-coded.
Verified by:
provenance-header(planned): the firmware's generated provenance header names its version, release train and the tag and SHA of every submodule, matching .gitmodules and git describe
See also: ADR-0007; IEC 62304:2006+A1:2015 8.1.3 (identify the system configuration)
Explained in: standards/product.md
KB-BLD-019: ESP-IDF builds set a 1 kHz FreeRTOS tick in sdkconfig.defaults¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, hal, firmware, template · since 1.0 · enforced from 2027-03-01
Every ESP-IDF project, including driver examples, sets CONFIG_FREERTOS_HZ=1000 in sdkconfig.defaults. ThreadX builds
should set TX_TIMER_TICKS_PER_SECOND to 1000.
Verified by:
sdkconfig-defaults/freertos-hz(planned): sdkconfig.defaults of every ESP-IDF project sets the named value (freertos-hz is CONFIG_FREERTOS_HZ=1000)
Explained in: standards/threading-and-timing.md
KB-BLD-020: kb-core parts are separate targets with distinct include roots¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library · since 1.0 · enforced from 2027-03-01
kb-core builds kb::utils, kb::rtos, kb::interfaces and kb::handlers as separate targets, each with one include
root reached as "kb/<part>/<Header>.h"; no two parts install the same path. Each part is usable through
add_subdirectory() and through its installed package.
Verified by:
cmake-configure/kb-core-targets(planned): a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-togglesinstalled-header-collisions(planned): the install trees of the kb-core packages contain no path twice
See also: ADR-0013
Explained in: standards/library.md
KB-BLD-021: Each build selects exactly one MCU family and one RTOS backend¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library · since 1.0 · enforced from 2027-03-01
KB_MCU (ESP32, STM32, HOST or NONE) and KB_RTOS (FREERTOS, THREADX or NONE) each select exactly one backend and
define exactly one macro for it. KB_MCU=NONE builds the MCU-independent base only and KB_MCU=HOST is the test
backend; the API is the same on every backend.
Verified by:
cmake-configure/backend-selection(planned): a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-toggles
Explained in: standards/library.md
KB-BLD-022: Enabling an MCU-bound driver for the wrong MCU fails at configure time¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library · since 1.0 · enforced from 2027-03-01
Drivers bound to an MCU family or peripheral are listed in KB_MCU_GATES, generated from catalog/compat.yml and never
edited by hand. Enabling one for another MCU stops the CMake configure step with a message naming the gate. A kb-core
release regenerates the table and checks it agrees with compat.yml.
Verified by:
cmake-configure/mcu-gates(planned): a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-toggles- review: compat.yml was regenerated for the release and the gate table matches it.
Explained in: standards/layers.md
KB-BLD-023: kb-core options use the KB_ scheme and default to the smallest build¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library · since 1.0 · enforced from 2027-03-01
kb-core's options are KB_MCU, KB_RTOS, KB_ENABLE_<CHIP>, KB_ENABLE_<FEATURE> and KB_BUILD_TESTS. Each enable
option has an explicit default, OFF unless the pull request justifies otherwise, so an unconfigured build is the base
only. KB_ENABLE_<CHIP> is the only switch that compiles a handler.
Verified by:
cmake-configure/option-defaults(planned): a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-toggles
See also: ADR-0013
Explained in: standards/library.md
KB-BLD-024: Enabling a module enables what it depends on, never the reverse¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · library · since 1.0 · enforced from 2027-03-01
Turning on one option also turns on the modules it needs: a driver enables the interfaces it uses, and an interface never enables a driver. Every option configures and builds when it is the only one switched on.
Verified by:
cmake-configure/single-toggles(planned): a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-toggles
Explained in: standards/layers.md
KB-BLD-025: kb-core links each driver's target and never copies its file lists¶
MUST · library · since 1.0
kb-core consumes a driver by linking <chip>::<chip> from its pinned submodule. kb_build_settings.cmake holds the
version, options, targets and gate table, and no driver source or include path.
Why: A copied file list breaks the day the driver adds a file, and bypasses the driver's own flags.
Verified by:
- review: kb-core CMake names no file or include directory inside a driver submodule.
Explained in: standards/library.md
KB-BLD-026: ESP-IDF REQUIRES follow the enabled options¶
SHOULD · library, hal · since 1.0
Under ESP-IDF the component's REQUIRES list is built from the enabled options, without duplicates, so a disabled
module pulls in no component. A component that exists only in some ESP-IDF releases is checked for and reported, not
assumed.
Verified by:
- review: Each REQUIRES entry is added by the option that needs it.
KB-BLD-027: Configure prints a summary of what is built¶
SHOULD · library, hal · since 1.0
A library or HAL with options prints one configuration summary at the end of configure: MCU, RTOS, enabled drivers and features, and their count.
Why: A CI log then says what was actually built without anyone reproducing the configure step.
Verified by:
- review: The configure log shows the summary block.
KB-BLD-028: Keep CMake plain and linear¶
GUIDE · driver, library, hal, firmware, template · since 1.0
Build settings read top to bottom as a list of settings: no logic hidden in helper functions, paths derived from
CMAKE_CURRENT_LIST_DIR and overridable as cache variables where a consumer may need to.
KB-BLD-029: Depend on as little as possible¶
GUIDE · driver, library, hal · since 1.0
Add a dependency only when it removes more than it costs, keep the dependency list of a published component accurate, and prefer a compatible change to a breaking one.