Skill: F Prime CMake Build System
F Prime wraps CMake in an API layer so that modules declare sources and
autocoder inputs and get autocoding, dictionaries, unit tests, and
install rules for free. Canonical references:
Follow those for full syntax and examples; this skill adds orientation,
decision criteria, and the failure modes that are easy to get wrong.
1 — Where things live under cmake/
| Path |
Contents |
API.cmake |
The public register_fprime_* / add_fprime_subdirectory API |
module.cmake, config_assembler.cmake |
Internal module and configuration processing |
target/ |
Built-in targets: build, ut, dictionary, install, sbom, version |
target/sub-build/ |
Targets run in sub-builds (fpp_locs, fpp_depend, module_info) |
autocoder/ |
Autocoder integration (fpp.cmake, fpp_ut.cmake) |
platform/ |
${FPRIME_PLATFORM}.cmake platform files (Linux, Darwin, templates) |
toolchain/ |
Cross-compile toolchain files |
settings/, options.cmake, flags.cmake, sanitizers.cmake |
Build settings, options, compile flags |
test/ |
pytest suite for the build system itself |
Change the narrowest layer that solves the problem: a module's own
CMakeLists.txt first, then a platform/toolchain file, and only then
cmake/ internals (which affect every project using F Prime).
2 — Which registration call
| Task |
Call |
| Component, port, or plain library module |
register_fprime_module |
| Deployment producing an F Prime binary |
register_fprime_deployment |
| Non-deployment executable / tool |
register_fprime_executable |
| Unit test |
register_fprime_ut (see fprime-unit-testing) |
| Configuration or platform config module |
register_fprime_config |
Implementation of a swappable package (e.g. Os_File) |
register_fprime_module + IMPLEMENTS; register_os_implementation for OSAL packages |
Custom build target (<target> + <MODULE>_<target>) |
register_fprime_target / register_fprime_ut_target |
Common directives: SOURCES, AUTOCODER_INPUTS, HEADERS, DEPENDS,
REQUIRES_IMPLEMENTATIONS, CHOOSES_IMPLEMENTATIONS. A new module
directory must also be pulled in with add_fprime_subdirectory from
the including CMakeLists.txt.
Guides: customization / custom targets,
implementations,
platforms,
toolchains,
settings.ini,
external libraries,
OSAL implementation.
3 — Failure modes
- Stale cache: a build cache can go out of date in many ways —
edited
settings.ini, a new CMakeLists.txt or FPP file, a moved
module, a switched toolchain. Symptoms are confusing missing-target,
missing-autocode, or stale-dependency errors rather than compiler
errors. Fix with fprime-util generate -f (--ut for the unit-test
cache), which purges and regenerates the build cache.
- Unresolved implementation: every platform must
CHOOSES_IMPLEMENTATIONS
for every package a module REQUIRES_IMPLEMENTATIONS; a missing
choice surfaces as a link error, not a CMake error. Use the _Stub
implementation when a platform lacks the capability; override per
deployment, executable, or UT only.
- Sub-build assumptions: code that must not run during the
fpp_locs/fpp_depend sub-builds needs skip_on_sub_build();
platform-specific modules need restrict_platforms(...).
- Hardcoded host paths or tool locations in a toolchain belong in
an
environment_file, not in committed CMake.
- Bypassing the API (raw
add_library/target_link_libraries for
an F Prime module) loses autocoding, dictionary, and UT integration.
1---2name: fprime-cmake-build-system3description: Work with F Prime's custom CMake layer: the `register_fprime_*` API, build targets, toolchains and platform files, implementation selection, configuration modules, sub-builds, and `settings.ini`. Use when adding or wiring a module into a build, adding a custom build target, porting to a new platform or toolchain, choosing or defining an Os implementation, or diagnosing generate/build failures that are not compiler errors.4---56# Skill: F Prime CMake Build System78F Prime wraps CMake in an API layer so that modules declare sources and9autocoder inputs and get autocoding, dictionaries, unit tests, and10install rules for free. Canonical references:1112- [Build system user manual](../../../docs/user-manual/build-system/01-cmake-intro.md)13- API and options reference — generated from the docblocks in14 [`API.cmake`](../../../cmake/API.cmake) and15 [`options.cmake`](../../../cmake/options.cmake); read those files16 directly, they are the source of truth17- [Build system SDD](../../../cmake/docs/sdd.md) (requirements, ops concepts)1819Follow those for full syntax and examples; this skill adds orientation,20decision criteria, and the failure modes that are easy to get wrong.2122---2324## 1 — Where things live under `cmake/`2526| Path | Contents |27|---|---|28| `API.cmake` | The public `register_fprime_*` / `add_fprime_subdirectory` API |29| `module.cmake`, `config_assembler.cmake` | Internal module and configuration processing |30| `target/` | Built-in targets: `build`, `ut`, `dictionary`, `install`, `sbom`, `version` |31| `target/sub-build/` | Targets run in sub-builds (`fpp_locs`, `fpp_depend`, `module_info`) |32| `autocoder/` | Autocoder integration (`fpp.cmake`, `fpp_ut.cmake`) |33| `platform/` | `${FPRIME_PLATFORM}.cmake` platform files (Linux, Darwin, templates) |34| `toolchain/` | Cross-compile toolchain files |35| `settings/`, `options.cmake`, `flags.cmake`, `sanitizers.cmake` | Build settings, options, compile flags |36| `test/` | pytest suite for the build system itself |3738Change the *narrowest* layer that solves the problem: a module's own39`CMakeLists.txt` first, then a platform/toolchain file, and only then40`cmake/` internals (which affect every project using F Prime).4142---4344## 2 — Which registration call4546| Task | Call |47|---|---|48| Component, port, or plain library module | `register_fprime_module` |49| Deployment producing an F Prime binary | `register_fprime_deployment` |50| Non-deployment executable / tool | `register_fprime_executable` |51| Unit test | `register_fprime_ut` (see `fprime-unit-testing`) |52| Configuration or platform config module | `register_fprime_config` |53| Implementation of a swappable package (e.g. `Os_File`) | `register_fprime_module` + `IMPLEMENTS`; `register_os_implementation` for OSAL packages |54| Custom build target (`<target>` + `<MODULE>_<target>`) | `register_fprime_target` / `register_fprime_ut_target` |5556Common directives: `SOURCES`, `AUTOCODER_INPUTS`, `HEADERS`, `DEPENDS`,57`REQUIRES_IMPLEMENTATIONS`, `CHOOSES_IMPLEMENTATIONS`. A new module58directory must also be pulled in with `add_fprime_subdirectory` from59the including `CMakeLists.txt`.6061Guides: [customization / custom targets](../../../docs/user-manual/build-system/cmake-customization.md),62[implementations](../../../docs/user-manual/build-system/cmake-implementations.md),63[platforms](../../../docs/user-manual/build-system/cmake-platforms.md),64[toolchains](../../../docs/user-manual/build-system/cmake-toolchains.md),65[settings.ini](../../../docs/user-manual/build-system/settings.md),66[external libraries](../../../docs/how-to/integrate/integrate-external-libraries.md),67[OSAL implementation](../../../docs/how-to/integrate/implement-osal.md).6869---7071## 3 — Failure modes7273- **Stale cache**: a build cache can go out of date in many ways —74 edited `settings.ini`, a new `CMakeLists.txt` or FPP file, a moved75 module, a switched toolchain. Symptoms are confusing missing-target,76 missing-autocode, or stale-dependency errors rather than compiler77 errors. Fix with `fprime-util generate -f` (`--ut` for the unit-test78 cache), which purges and regenerates the build cache.79- **Unresolved implementation**: every platform must `CHOOSES_IMPLEMENTATIONS`80 for every package a module `REQUIRES_IMPLEMENTATIONS`; a missing81 choice surfaces as a link error, not a CMake error. Use the `_Stub`82 implementation when a platform lacks the capability; override per83 deployment, executable, or UT only.84- **Sub-build assumptions**: code that must not run during the85 `fpp_locs`/`fpp_depend` sub-builds needs `skip_on_sub_build()`;86 platform-specific modules need `restrict_platforms(...)`.87- **Hardcoded host paths or tool locations** in a toolchain belong in88 an `environment_file`, not in committed CMake.89- **Bypassing the API** (raw `add_library`/`target_link_libraries` for90 an F Prime module) loses autocoding, dictionary, and UT integration.
nasa