F Prime CMake 构建系统全景指南cmake/目录公共 API、文件布局与扩展约定【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprimeF PrimeF´是一个面向飞行软件与嵌入式系统的组件化框架其构建系统的全部核心逻辑集中在仓库根目录的cmake/目录中它将 FPP 模型自动生成autocode为 C 源码并把模块、单元测试与部署deployment组装成可执行目标。本文以 cmake/AGENTS.md 为骨架结合 cmake/API.cmake、cmake/options.cmake、cmake/autocoder/autocoder.cmake 等源码与测试系统讲解该构建系统的公共接口、目录职责、关键选项与扩展规范。读完本文你将掌握如何在一个 F Prime 项目中正确注册模块/库/可执行文件/部署/单元测试理解FPRIME_*选项的语义与默认值并能在不破坏构建系统的前提下添加平台、工具链、选项与自定义构建阶段。一、cmake/目录在 F Prime 中的角色F Prime 的构建体系与普通 CMake 工程的一个关键差异是它存在一个autocoding自动代码生成阶段。开发者在.fpp/.fppi模型文件中声明端口、组件、拓扑构建系统在编译前把这些模型翻译成 C 源码再连同手写实现一起编译链接。cmake/目录正是这一机制的实现载体——它定义了一套基于 CMake 的 DSL负责把 FPP 模型自动生成autocoding为 C 代码组装模块components/ports、单元测试UT与部署deployment解析项目settings.ini、平台定义与交叉编译工具链提供build、ut、install、dictionary、sbom、version等构建目标。AGENTS.md 明确指出cmake/API.cmake是唯一的外部接口。任何项目或模块的CMakeLists.txt所调用的函数都在该文件中定义每个函数上方都有内联文档。完整的手册文档位于 docs/user-manual/build-system/其中 cmake-api.md 讲解公共 APIcmake-implementations.md 讲解内部实现建议从这两篇开始阅读。二、公共 APIregister_fprime_*函数族cmake/API.cmake中定义的函数构成 F Prime 构建系统的对外契约。AGENTS.md 给出的速查表如下它是理解整个构建系统的入口函数用途register_fprime_module注册一个模块组件/端口库使其获得 autocoding 能力。register_fprime_library注册一个不需要 autocoding 的普通库。register_fprime_executable注册一个可执行文件。register_fprime_deployment注册一个部署拓扑加二进制。register_fprime_ut注册模块的单元测试。register_fprime_config注册一个配置模块。add_fprime_subdirectory向构建添加一个目录替代add_subdirectory。register_fprime_implementation、register_os_implementation为抽象接口提供实现Os/大量使用。register_fprime_target、register_fprime_ut_target、register_fprime_build_autocoder添加自定义构建阶段或自动编码器。register_fprime_module在源码中只是register_fprime_library的向后兼容别名cmake/API.cmake#L227-L229历史变量SOURCE_FILES、MOD_DEPS等虽然仍受支持但官方建议改用指令式参数。所有register_fprime_*函数register_fprime_library/executable/deployment/ut/config共享同一套调用格式支持以下指令SOURCES源文件列表AUTOCODER_INPUTS需要交给自动编码器处理的模型文件.fpp等DEPENDS链接依赖库、-l参数HEADERS头文件列表LINK_DEPENDS额外文件如链接脚本.ld当其变化时触发重编译。以register_fprime_library为例cmake/API.cmake#L178-L195register_fprime_library( MyFprimeModule SOURCES source1.cpp source2.cpp AUTOCODER_INPUTS model.fpp DEPENDS -lm HEADERS module.h LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/extra_file.ld )register_fprime_executable与register_fprime_deployment的格式完全相同区别在于register_fprime_executable底层委托add_executable且不再支持EXECUTABLE_NAME变量传入会触发致命错误见 cmake/API.cmake#L288-L290register_fprime_deployment注册的是拓扑二进制整体支持在依赖树范围内运行 targets例如对一个部署用到的所有组件跑一遍单元测试在未设置FPRIME_CURRENT_MODULE时回退到PROJECT_NAMEcmake/API.cmake#L355-L364。register_fprime_ut只在启用测试时创建目标当BUILD_TESTING为 OFF 时函数直接返回、不生成任何目标cmake/API.cmake#L543-L552这保证了正式部署构建不会携带测试目标。2.1 配置模块与覆盖机制register_fprime_config额外支持CONFIGURATION_OVERRIDES指令用于覆盖此前配置模块默认配置、库配置提供的同名配置文件例如覆盖FpConfig.fpp、FpConfig.hppcmake/API.cmake#L411-L425register_fprime_config( MyFprimeConfig SOURCES config.cpp AUTOCODER_INPUTS config.fpp HEADERS config.hpp CONFIGURATION_OVERRIDES FpConfig.fpp FpConfig.hpp )其内部实现值得注意cmake/API.cmake#L450-L507配置模块以STATIC 库形式构建提供SOURCES/AUTOCODER_INPUTS时自动追加STATIC以便与Fw_Types等基础库之间建立相互依赖而不受库类型限制所有配置源SOURCES/HEADERS/AUTOCODER_INPUTS会被拷贝进构建缓存再参与编译覆盖文件按 CMakeLists.txt 树中的检测顺序生效platform → fprime config → library → project覆盖文件会被拷入被覆盖模块原始构建位置从而保留原始构建模块的设置当标记BASE_CONFIG时配置模块被链接进全局接口目标整个构建系统的所有模块都能访问该配置。仓库 cmake/test/data/TestConfigDeployment 就是针对该机制的完整测试样例其override/project/下同时放置了FpConfig.fpp、DpCfg.hpp等覆盖文件与settings.ini。2.2 实现implementation机制register_fprime_implementation用于声明某个实现库实现了某个接口IMPLEMENTS指令结果总是 OBJECT 库以确保在链接期按预期覆盖cmake/API.cmake#L680-L729register_fprime_implementation( MyImplementation IMPLEMENTS SomeImplementationInterface SOURCES source1.cpp source2.cpp AUTOCODER_INPUTS model.fpp HEADERS module.h )IMPLEMENTS必须且只能传一个接口名否则触发致命错误同一模块的实现声明前后不得变更。register_os_implementation则是Os/目录用来注册操作系统层实现的便捷封装File;Directory;FileSystem这类命名列表 后缀如Posix。2.3 目录添加与构建图add_fprime_subdirectory替代原生add_subdirectory核心价值在于两点cmake/API.cmake#L92-L150自动化binary_dir参数F Prime 子目录有特定的二进制根以避免冲突并保证标准的#include路径以仓库根为起点构建图构造所有被add_fprime_subdirectory引入的目录共同构成超图super-graphCMake 的依赖系统会从该超图中剪裁出每个可执行/模块/库实际需要的子图。因此把一个暂未使用的子目录加进来并不会导致多余编译但任何代码都必须出现在这个超图中才能被构建。2.4 自定义目标与自动编码器注册register_fprime_target允许用户把自定义构建阶段注册进系统传入一个 CMake 文件路径或 include 路径该文件必须定义add_global_target、add_module_target、add_deployment_target三个函数cmake/API.cmake#L578-L593。register_fprime_ut_target与其行为一致但仅在BUILD_TESTINGON时生效。register_fprime_build_autocoder则注册自定义自动编码器被注册的 CMake 文件必须满足三个条件cmake/API.cmake#L639-L656在文件作用域调用autocoder_setup_for_individual_sources()或autocoder_setup_for_multiple_sources()实现autocoder 名_is_supported(AC_POSSIBLE_INPUT_FILE)返回该自动编码器是否处理给定输入文件实现autocoder 名_setup_autocode(AC_INPUT_FILE)完成实际的代码生成。cmake/autocoder/下的fpp.cmake、fpp_ut.cmake正是以该协议接入的标准 FPP 自动编码器。三、文件布局cmake/内部各文件职责AGENTS.md 给出了一张哪里放什么的完整地图是进入源码前的最佳索引路径内容API.cmake公共 API见上文。FPrime.cmake、FPrime-Code.cmake、FPrimeConfig.cmake项目 include 以搭建构建的入口点。options.cmake全部FPRIME_*构建选项与路径FPRIME_ENABLE_*、sanitizers、BUILD_TESTING、框架与库位置。新增选项前先看这里。module.cmake、global_interface.cmake、flags.cmake、utilities.cmake内部实现模块、接口与编译标志如何组装。settings.cmake、settings/解析项目settings.ini。target/构建目标与阶段build、ut、install、dictionary、sbom、version外加sub-build/与tools/。autocoder/FPP 自动编码器集成fpp.cmake、fpp_ut.cmake、autocoder.cmake与辅助scripts/。platform/平台定义Linux.cmake、Darwin.cmake、unix/及新建平台的platform.cmake.template。toolchain/交叉编译工具链arm-*-linux、aarch64-*、raspberrypi及toolchain.cmake.template。config_assembler.cmake组装构建所用的配置头文件。sanitizers.cmake单元测试的 Address/Leak/UB/Thread sanitizer 接线。sub-build/用于 setup 与工具工作的嵌套 CMake 调用。test/构建系统自身的测试。docs/sdd.md构建系统的设计文档。这些文件在仓库中均可一一对应找到入口点在 cmake/FPrime.cmake、cmake/FPrime-Code.cmake、cmake/FPrimeConfig.cmake内部实现在 cmake/module.cmake、cmake/global_interface.cmake、cmake/flags.cmake、cmake/utilities.cmake配置解析在 cmake/settings.cmake 与 cmake/settings/ini.cmake。target/目录下实际包含dictionary.cmake生成命令字典、ut.cmake单元测试运行、install.cmake/fprime_install.cmake安装、sbom.cmake软件物料清单、version.cmake版本信息、refresh_cache.cmake与target.cmake目标基础设施以及tools/下的property_writer.py、arguments-from-file.py、redirector.py、cat.py等辅助脚本。构建系统自身的测试位于 cmake/test其中src/下按功能拆分为test_basic.py、test_config.py、test_autocoder.py、test_implementation.py、test_target_triple.py等 Python 测试data/下则是一系列可独立配置的测试工程如TestDeployment、TestConfigDeployment、TestFlagsProject。四、FPRIME_*构建选项详解cmake/options.cmake集中定义了全部构建选项。其文件头明确指出绝大多数用户无需显式指定任何选项即可构建 F Prime只有当需要非标准构建行为时才用-DOPTIONVALUE通常为ON/OFF传入。以下选项与默认值均直接取自源码cmake/options.cmake选项默认值作用CMAKE_DEBUG_OUTPUTOFF输出 F Prime CMake 集成层的调试信息便于排查构建问题不影响 CMake 自身。FPRIME_CMAKE_QUIETOFF关闭模块注册、目标注册、自动编码器注册等状态消息不影响错误/警告消息。FPRIME_USE_STUBBED_DRIVERS由平台文件决定ON 时使用Drv包中的桩驱动serial 与 ipv4 驱动除外仅接受 ON/OFF/不设置。FPRIME_USE_BAREMETAL_SCHEDULER由平台文件决定ON 时使用裸机调度器单上下文循环调度活动组件用于无 OS 系统或在 PC 上验证单线程执行。FPRIME_ENABLE_FRAMEWORK_UTSON是否把框架自身的单元测试加入目标列表不影响项目自己的 UT。FPRIME_ENABLE_AUTOCODER_UTSOFF在框架 UT 基础上是否启用自动编码器工具的 UT验证工具运行而非产品代码正确性。FPRIME_ENABLE_UT_COVERAGEON是否计算单元测试覆盖率关闭可提升 UT 性能并移除覆盖率目标。FPRIME_ENABLE_DIRECT_PORT_CALLSOFFON 时拓扑端口连接改用直接函数调用会禁用 UT因为 UT 不支持直接端口调用OFF 时通过函数指针调用。FPRIME_ENABLE_TEXT_LOGGERSON是否把ActiveTextLogger/PassiveConsoleTextLogger组件纳入构建关闭后可同时取消FW_ENABLE_TEXT_LOGGING以节省空间开启时若FW_ENABLE_TEXT_LOGGING0会构建失败。FPRIME_ENABLE_JSON_MODEL_GENERATIONOFFON 时对所有模块运行fpp-to-json生成 JSON 模型可能需要 Java 及 FPP 的 jar 版本。FPRIME_SKIP_TOOLS_VERSION_CHECKOFF跳过 F Prime 工具版本检查高级选项供维护自定义工具变体时使用不匹配将不再被报告。FPRIME_CHECK_FRAMEWORK_VERSIONOFF仅供内部使用在打 tag 时校验框架版本已更新。FPRIME_INSTALL_STATIC_LIBRARIESON是否把静态库安装到 build-artifacts共享库安装始终开启。FPRIME_INSTALL_DEST${PROJECT_SOURCE_DIR}/build-artifactsfprime_install.cmake在环境未设置DESTDIR时使用的默认安装目录。另有与路径相关的FPRIME_LIBRARY_LOCATIONS、FPRIME_FRAMEWORK_LOCATIONS以及标准 CMake 的BUILD_TESTING、CMAKE_TOOLCHAIN_FILE默认使用本机构建等。工具链文件放在框架或库的cmake/toolchain/目录例如-DCMAKE_TOOLCHAIN_FILE/path/to/cmake/toolchain/arm-hf-linux.cmake。五、扩展约定平台、工具链、选项与构建阶段AGENTS.md 明确了四类扩展必须遵循的规范这是为 F Prime 做贡献或定制时的红线新增平台或工具链复制对应的.template文件cmake/platform/platform.cmake.template、cmake/toolchain/toolchain.cmake.template作为起点而不是照抄已有定义并遵循 cmake-platforms.md 或 cmake-toolchains.md。仓库已有arm-hf-linux、arm-sf-linux、aarch64-linux、aarch64-clang-linux、raspberrypi等工具链定义可作参考。新增选项必须在 cmake/options.cmake 中用option()或set(... CACHE ...)声明并在 settings.md 中与其他FPRIME_*设置一同记录。注意选项校验模式如FPRIME_USE_STUBBED_DRIVERS仅接受 ON/OFF/不设置否则message(FATAL_ERROR)。新增构建阶段在cmake/target/下实现并通过register_fprime_target注册参见 cmake-targets.md。自定义目标文件必须提供add_global_target、add_module_target、add_deployment_target三个函数。通用守则在子构建sub-build上下文中不适合执行的代码使用skip_on_sub_build()宏提前返回其通过检查FPRIME_IS_SUB_BUILD实现见 cmake/API.cmake#L33-L37只支持部分平台/工具链/特性的模块使用restrict_platforms()宏其接受平台名如Linux、Darwin、具体工具链名如aarch64-linux或特性集如SOCKETS会检查FPRIME_HAS_SOCKETSPosix对应旧式FPRIME_USE_POSIX。当平台不受支持时模块会被记录进RESTRICTED_TARGETS全局属性并从当前CMakeLists.txt提前返回cmake/API.cmake#L59-L90自动生成的代码永远存放在构建缓存build-fprime-*/中它们是构建产物不得手工编辑或提交到版本库。六、Autocoding 的底层运转从模型到编译源理解自动编码器如何被驱动能帮你正确编写AUTOCODER_INPUTS与自定义自动编码器。cmake/autocoder/autocoder.cmake 提供了两层调度run_ac_setL28-L80对一组自动编码器做串行调度把上一个自动编码器生成的AUTOCODER_GENERATED_AUTOCODER_INPUTS追加为下一个的输入从而支持链式代码生成run_acL92-L120单个自动编码器的执行单元。它对源文件做规范化与过滤通过输入哈希string(SHA1 ...)判断输入集是否变化未变化则复用上次结果、跳过执行执行后把生成文件、新增依赖写入目标的AC_GENERATED、SOURCES、LINK_LIBRARIES等属性。值得注意的细节生成文件必须被 CMake 标记为GENERATEDrun_ac_set末尾会断言这一点L67-L72同时构建结束时_validate_all_autocoder_inputs_handled会校验每个用户提供的AUTOCODER_INPUT至少被一个自动编码器消费避免模型文件被静默忽略。七、修改公共 API 的配套要求AGENTS.md 强调修改cmake/API.cmake时必须同步更新函数上方的内联文档与 cmake-api.md。这是因为该文件既是实现又是文档二者脱节会直接破坏面向 Agent/开发者的唯一入口这一设计前提。同理新增选项要同步 settings.md新增平台/工具链要同步对应指南新增构建阶段要同步 cmake-targets.md。八、进一步阅读构建系统入门01-cmake-intro.md公共 API 手册cmake-api.md内部实现剖析cmake-implementations.md平台与工具链cmake-platforms.md、cmake-toolchains.md自定义目标cmake-targets.md单元测试构建cmake-uts.md设置项手册settings.md构建系统设计文档cmake/docs/sdd.md真实模块的CMakeLists.txt范例可参考 Drv/LinuxGpioDriver/CMakeLists.txt 与 Fw/Buffer/CMakeLists.txt 等框架内模块。F Prime CMake 文件组织关系总而言之cmake/目录是 F Prime 构建体系的单一事实来源API.cmake定义了对外契约options.cmake与settings/定义了配置空间target/、autocoder/、platform/、toolchain/分别承载构建阶段、代码生成、平台与交叉编译能力。无论你是要为 F Prime 新增一个组件、接入一块新硬件还是想深入定制构建流程先读懂 AGENTS.md 这份导航图再按图索骥进入对应源码与手册就能快速找到正确的扩展点。【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考