Momentum-Firmware 构建工具 fbt 完全指南从工具链自举到固件发布【免费下载链接】Momentum-Firmware Feature-rich, stable and customizable Flipper Firmware项目地址: https://gitcode.com/GitHub_Trending/mo/Momentum-FirmwarefbtFlipper Build Tool是 Momentum-Firmware 项目所有固件相关命令与实用工具的入口内部封装了 SCons 构建系统用于编译固件、构建外部应用.fap、生成更新包、烧录调试与代码风格检查等全部开发流程。本文以 documentation/fbt.md 为主线结合仓库内fbt、fbt.cmd、SConstruct、fbt_options.py、site_scons/commandline.scons等源码系统讲解环境准备、工具链自举机制、目标命令、命令行参数与配置体系帮助读者从零掌握该固件的完整构建与调试方法。fbt 是什么固件构建入口与 SCons 包装fbt 是固件相关命令和工具的入口点在固件项目根目录下通过./fbt调用内部本质上是 scons 构建系统的一个包装器。入口脚本Unix/Linux/macOS 下为仓库根目录的 fbtWindows 下为 fbt.cmd。执行链路fbt脚本先加载工具链环境脚本scripts/toolchain/fbtenv.sh然后执行git submodule update --init --recursive同步子模块最后以python3 -m SCons --warntarget-not-built启动 SCons未设置FBT_VERBOSE时附加-Q静默参数。构建逻辑的顶层编排位于 SConstruct所有命令行选项与配置变量的定义位于 site_scons/commandline.scons。轻量替代方案如果不需要 fbt 的全部功能例如不需要构建整个固件只想构建和调试单个应用可以使用ufbtPython 包ufbt它面向单应用开发场景。环境要求与工具链自举仅需 git使用 fbt 的唯一前提是系统中安装了git。fbt 默认会自动下载并解压预编译工具链并仅为自身修改环境变量不会污染系统的全局PATH。fbt 环境壳fbt shell如果希望在 fbt 之外使用工具链自带的工具可以打开一个环境配置好的fbt shellWindows直接运行scripts/toolchain/fbtenv.cmdLinux 与 macOS在新 shell 中执行source scripts/toolchain/fbtenv.sh也可以在任意 shell 中执行. ./fbt -s env注意保留开头的点号。从 SConstruct 源码可以看到fbt env目标实际输出fbtenv.sh脚本路径供当前 shell source。以 scripts/toolchain/fbtenv.sh 为例环境脚本的核心行为包括根据uname判断内核类型仅支持 linux 与 darwinMinGW shell 需改用fbt.cmd计算工具链安装目录toolchain/arch-sys调用curl或wget下载gcc-arm-none-eabi-12.3-arch-sys-flipper-版本号.tar.gz解压后通过toolchain/current符号链接指向当前版本检查目录内VERSION文件与期望的FBT_TOOLCHAIN_VERSION当前仓库为39是否一致不一致则自动触发工具链升级将SSL_CERT_FILE、REQUESTS_CA_BUNDLE指向工具链自带的 certifi 证书设置PYTHONNOUSERSITE1并清空PYTHONPATH、PYTHONHOMELinux 下额外设置TERMINFO_DIRS最后把toolchain/current/bin追加到PATH并在提示符前加[fbt]标记--restore参数可恢复原环境。Windows 下 scripts/toolchain/fbtenv.cmd 的职责类似通过 PowerShell 脚本下载x86_64-windows工具链设置PYTHONHOME、PATH并把提示符改为(fbt)。环境变量开关变量作用备注FBT_NOENV1跳过工具链与环境配置要求所有工具已在系统PATH中Windows 不可用FBT_TOOLCHAIN_PATH指定工具链解压目录默认解压到仓库根目录toolchain子目录FBT_VERBOSE1输出 fbt 与工具链管理脚本的额外调试信息同时会去掉 SCons 的-Q静默参数打印完整编译命令FBT_NO_SYNC1跳过启动时的git submodule update --initWindows 用set FBT_NO_SYNC1*nix 用$ FBT_NO_SYNC1 ./fbt ...FBT_GIT_SUBMODULE_SHALLOW1以--depth 1浅克隆子模块加快同步见 fbt 脚本实现fbt 每次启动都会执行git submodule update --init除非设置FBT_NO_SYNC1Windows 在运行 fbt 的 shell 中执行set FBT_NO_SYNC1*nix 使用$ FBT_NO_SYNC1 ./fbt ...。从 fbt 源码可见子模块同步会按CPU 核心数 × 2的线程数并行执行且要求仓库必须通过git clone克隆存在.git目录否则直接报错退出。控制 fbt 基础行为的变量不止这些更多细节可阅读fbt与fbtenv脚本源码。调用 fbt目标与配置调用 fbt 时直接在其后指定配置选项与要构建的目标例如./fbt COMPACT1 DEBUG0 VERBOSE1 updater_package copro_dist执行清理类似make clean时为目标添加-c选项。fbt 会跟踪内部依赖关系因此只需要构建最高层的目标所有依赖项都会自动保持最新。构建产物目录与 built/latestfbt 在build下分别用独立子目录构建 updater 与 firmware目录名取决于优化设置COMPACT与DEBUG选项。为方便 IDE 集成最近一次构建的变体目录总是被链接为built/latest该目录中还会生成compile_commands.json供 IDE 实现代码补全。注意firmware.scons 源码显示built/latest符号链接与编译数据库只在重新构建固件本身时更新。运行其他任务例如为不同 debug/release 配置或不同硬件目标烧录固件、构建更新包不会把built/latest指向该配置。VS Code 集成fbt 内置了 VS Code 的基础开发环境配置./fbt vscode_dist该命令会把初始环境配置复制到.vscode目录之后在 VS Code 中通过 File Open Folder 选择固件根目录即可使用。从 SConstruct 可以看到vscode_dist目标还会同时生成固件的compile_commands.json即FW_CDB并会把.vscode/example下的 JSON 模板渲染后安装到.vscode。切换语言服务器使用./fbt vscode_dist LANG_SERVERlanguage-server可以选用默认的 VS Code C/C 语言服务器cpptools或clangd。LANG_SERVER的可选值定义在 site_scons/commandline.scons。推荐插件首次启动会提示安装推荐插件清单见.vscode/extensions.json由vscode_dist部署。构建任务基本构建任务在 CtrlShiftB 菜单中调用。调试探针支持以下受支持的调试器带原厂固件的 Wi-Fi DevboardblackmagicST-Link 及兼容设备J-Link仅 VS Code 中用于烧录与调试其工具不在工具链中需自行下载并加入系统PATH。没有受支持探针时可以通过 USB 安装方式把固件刷入 Flipper。FBT 目标详解高层目标日常最常用目标作用fw_dist构建固件并发布到dist目录未指定其他目标时的默认目标见 SConstructfap_dist构建外部插件并发布到dist目录updater_package/updater_minpackage构建自更新包最小版只含固件 DFU 文件完整版还包含无线电栈与 SD 卡资源copro_dist打包 Core2 FUSstack 二进制供 qFlipper 使用flash通过 SWD 接口烧录已连接的设备探针自动检测可用SWD_TRANSPORT...覆盖多探针时用SWD_TRANSPORT_SERIAL...指定序列号flash_usb/flash_usb_full构建更新包并通过 USB 上传安装到设备分别对应updater_minpackage/updater_packagedebug构建并烧录固件然后以加载了固件.elf的方式附加 GDBdebug_other/debug_other_blackmagic不加载任何.elf直接附加 GDB可在 GDB 中用add-symbol-file手动添加外部.elfupdater_debug以加载 updater 的.elf的方式附加 GDBdevboard_flash更新 Wi-Fi Devboard 固件支持ARGS...传递额外参数如ARGS-c devblackmagic使用 Blackmagic 探针Wi-Fi Devboard调试固件openocd仅启动 OpenOCD可用ARGS...传额外参数get_blackmagic以 GDB remote 格式输出 blackmagic 地址便于 IDE 集成get_stlink输出已连接 STLink 探针的序列号用于SWD_TRANSPORT_SERIAL...lint/format按.clang-format规范对 C 源码执行 clang-format 检查/格式化支持ARGS...lint_py/format_py用 black 对 Python 源码、构建系统文件与应用清单执行检查/格式化支持ARGS...lint_img/format_img检查并格式化图片资源强制色深、剥离元数据lint_all/format_all运行全部 linter 与 formatterfirmware_pvs为固件生成 PVS Studio 报告要求 PVS Studio 在系统PATH中doxygen生成固件 Doxygen 文档doxy目标还会打开浏览器查看cli通过 USB 启动 Flipper CLI 会话这些目标在 SConstruct 中有明确的实现对应例如lint/format调用scripts/lint.pylint_py/format_py调用python3 -m blacklint_img/format_img调用scripts/imglint.pycli调用scripts/serial_cli.pydevboard_flash调用scripts/wifi_board.pyfirmware_pvs经由firmware.scons中的PVSCheck/PVSReport生成报告。固件目标faps— 以 .fap 形式构建所有外部与插件应用。fbt 还为每个应用定义了独立目标。例如appidsnake_game的应用目标名为fap_snake_game等 — 按应用 ID 构建单个.fapfap_snake_game_list等 — 生成该应用.fap的源码 汇编清单。结合--extra-ext-apps见下节可强制把额外应用加入外部构建。flash/firmware_flash— 通过 SWD 把当前版本烧录到已连接设备。jflash— 使用 J-Link 探针JFlash烧录当前版本要求 JFlash 可执行文件在$PATH中。firmware_all/updater_all— 构建基础二进制集合。firmware_list/updater_list— 生成源码 汇编清单。firmware_cdb/updater_cdb— 生成compilation_database.json供外部工具与 IDE 使用无需实际构建固件即可生成。资源目标resources— 构建资源及其清单文件其中dolphin_ext处理用于 SD 卡的 dolphin 动画。icons— 从 PNG 资源生成.c.h图标代码。proto— 从.proto源生成.pb.c.pb.h。proto_ver— 生成包含 protobuf 版本号的.h。dolphin_internal/dolphin_blocking— 为对应 dolphin 资源生成.c.h。命令行参数fbt 支持以下命令行参数定义于 site_scons/commandline.scons参数作用--options optionfile.py默认fbt_options.py加载包含多个配置值的文件--extra-int-appsapp1,app2,appN强制所列应用以 internal 方式随firmware目标构建--extra-ext-appsapp1,app2,appN强制所列应用以 external 方式随firmware_extapps目标构建--extra-defineA --extra-defineBC额外全局宏定义原样传给 C/C 编译器可多次指定--proxy-envVAR1,VAR2追加暴露给 fbt 子进程的环境变量。默认 fbt 会净化执行环境不转发所有继承的环境变量始终被转发的变量清单见site_scons/environ.scons引用的FORWARDED_ENV_VARIABLES定义于 scripts/fbt/util.py包含DIST_SUFFIX、HOME、TMP、CCACHE_DISABLE、TERM、FBT_TOOLCHAIN_PATH、UFBT_HOME等此外--with-updater选项用于显式启用 updater 相关目标的完整环境SConstruct 会据此初始化 updater 工程并注册updater_package、flash_usb等目标。配置系统与 fbt_options.py默认配置变量定义在根目录 fbt_options.py 中命令行中的值优先级高于配置文件。也可以创建fbt_options_local.py它在加载默认选项文件时被求值见 fbt_options.py 的exec(compile(...))逻辑从而在不修改默认配置的情况下持久覆盖默认选项。可用./fbt -h查看全部可用选项。关键配置变量以下变量定义于 site_scons/commandline.scons其默认值可在fbt_options.py中覆盖变量说明默认值本仓库COMPACT按体积优化布尔1fbt_options.pyDEBUG调试构建布尔0LIB_DEBUG库的调试构建FalseVERBOSE打印完整命令FalseFORCE强制目标动作FalseTARGET_HW硬件目标可选7/187DIST_SUFFIXdist 目标二进制后缀由 git 自动推导见下文UPDATE_VERSION_STRINGupdater 包版本串${DIST_SUFFIX}COPRO_CUBE_VERSION/COPRO_CUBE_DIRCube 版本与目录1.20.0/lib/stm32wb_coproCOPRO_STACK_BINCore2 无线电栈文件stm32wb5x_BLE_Stack_light_fw.binCOPRO_STACK_TYPE栈类型可选ble_full/ble_light/ble_basicble_light文档注释ble_full可能放不进 debug 构建COPRO_STACK_ADDRCore2 固件地址0表示由脚本自动计算0x0COPRO_OB_DATAOB 参考数据路径scripts/ob.dataCOPRO_DISCLAIMER传递给打包脚本、确认危险操作的值空SVD_FILESVD 文件路径${FBT_DEBUG_DIR}/STM32WB55_CM4.svdOPENOCD_OPTS传给 OpenOCD 的选项见 fbt_options.pycmsis-dap SWD stm32wbx.cfg RTOS autoBLACKMAGICblackmagic 探针位置auto表示自动查找autoSWD_TRANSPORTSWD 适配器类型可选auto/cmsis-dap/stlink/blackmagic_usb/blackmagic_wifiautoSWD_TRANSPORT_SERIALSWD 适配器序列号autoFLIP_PORT连接多个 Flipper 时指定端口autoUPDATE_SPLASH更新包安装后播放的幻灯片目录update_defaultLOADER_AUTOSTART开机自动启动的应用名空FIRMWARE_ORIGIN固件来源标识会生成FW_ORIGIN_originC 宏MomentumFIRMWARE_APPS/FIRMWARE_APP_SET固件应用集配置与选择见下文SKIP_EXTERNAL跳过外部应用除非显式选中FalseEXTRA_EXT_APPS无论其他配置都包含的 appid 列表[]APPDIRS搜索固件组件与外部应用的目录列表applications、applications/services、applications/main等FBT_TOOLCHAIN_VERSIONS白名单内的工具链版本( 12.3., 13.2.)LANG_SERVERvscode_dist使用的语言服务器clangdSTRICT_FAP_IMPORT_CHECK对.fap启用严格导入检查TrueARGS传递给支持它的脚本的额外参数空DIST_SUFFIX在 fbt_options.py 中由 git 自动推导若当前提交是 tag则使用 tag 名形如mntm-(版本)否则使用mntm-(分支)-(提交前8位)。环境变量DIST_SUFFIX优先级更高见 site_scons/environ.scons便于 CI 统一命名。固件应用集Firmware application set通过修改固件构建中要包含的应用列表可以创建定制固件构建。应用预设由FIRMWARE_APPS选项配置它是map(configuration_name → application_list)结构用FIRMWARE_APP_SET指定要使用的集合名称。例如构建带单元测试的固件镜像./fbt FIRMWARE_APP_SETunit_tests本仓库 fbt_options.py 预置了三个集合defaultbasic_servicesmain_appssystem_appssettings_apps默认值对应FIRMWARE_APP_SET defaultunit_tests在 default 基础上追加unit_testsunit_tests_min最小测试集合basic_services、updater_app、radio_device_cc1101_ext、unit_tests、js_app、infrared、archive。底层实现中firmware.scons 会根据选中的集合追加FW_CFG_${FIRMWARE_APP_SET}宏定义且以unit_tests开头的集合会自动设置SKIP_EXTERNALTrue随后生成applications/applications.c注册所选应用并让该文件依赖各application.fam清单集合变化时自动重建。源码视角fbt 的构建流水线从 SConstruct 可以还原 fbt 的完整执行流程加载site_scons/commandline.scons定义的命令行选项与配置变量fbt_variables校验 Python 版本不低于 3.8加载 site_scons/environ.scons 构建基础环境coreenv引入crossccarm-none-eabi-前缀交叉编译器、python3、ccache等工具并按FORWARDED_ENV_VARIABLES加--proxy-env白名单转发宿主环境变量默认并行数设为 CPU 核心数克隆出distenv注册fbt_dist、fbt_debugopts、openocd、blackmagic、jflash、doxygen等工具并添加firmware工程检测到--with-updater或目标名包含updater/flash_usb时再添加updater工程updater 使用RAM_EXECTrue与FURI_RAM_EXEC宏注册各类 phony 目标flash、debug、lint、cli、vscode_dist等并把默认目标设为fw_distfirmware.scons 在子进程中完成具体编译按TARGET_HW配置硬件目标、遍历APPDIRS加载各应用目录的application.fam清单、按COMPACT开启-flto固件 DFU 空间紧张时的链接期优化、产出.elf/.hex/.bin/.dfu与compile_commands.json。典型工作流速查完整发布构建./fbt fw_dist fap_dist默认目标即fw_dist。生成自更新包./fbt updater_package含无线电栈与 SD 卡资源或./fbt updater_minpackage仅 DFU。SWD 烧录./fbt flash多探针时加SWD_TRANSPORT_SERIAL...J-Link 用户用./fbt jflash。USB 更新./fbt flash_usb最小包或./fbt flash_usb_full完整包。调试./fbt debug构建烧录GDBBlackmagic 探针用./fbt blackmagicWi-Fi Devboard 先./fbt devboard_flash更新。代码规范./fbt lint_all/./fbt format_all或按语言拆分lint/lint_py/lint_img。文档生成./fbt doxygen生成文档./fbt doxy并打开浏览器查看。查看帮助./fbt -h列出全部可用选项fbt_options.py 顶部注释也提示了配置变量的查看方式。需要说明的是本文描述的默认值、目标与参数均以当前仓库的实际源码为准不同硬件目标TARGET_HW7/18与不同优化组合下build目录命名、可用栈类型与二进制体积表现会有所差异实际使用时请以./fbt -h与构建日志为准。【免费下载链接】Momentum-Firmware Feature-rich, stable and customizable Flipper Firmware项目地址: https://gitcode.com/GitHub_Trending/mo/Momentum-Firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考