Zephyr平台学习指南

一、先建立心智模型West、CMake、Ninja 的分工Zephyr 的构建系统由三层工具协作完成理解它们的分工是学习的第一步West是 Zephyr 的“元工具”它不直接编译代码而是负责工作区管理、多仓库版本控制并封装了对 CMake 的调用。你可以把它理解为 Zephyr 开发的总入口——初始化工作区、拉取依赖、触发构建、烧录、调试都通过west命令完成。CMake是构建系统的生成器。它读取你的CMakeLists.txt、Kconfig 配置和设备树描述执行配置阶段configuration phase生成 Ninja 构建文件。Ninja是实际的构建执行器。它读取 CMake 生成的build.ninja调用编译器完成编译和链接产出zephyr.elf、zephyr.hex、zephyr.bin等最终文件。Zephyr 的构建过程分为两个主要阶段配置阶段由 CMake 驱动和构建阶段由 Make 或 Ninja 驱动。三者的调用关系是west build→ CMake配置 → Ninja构建 → 产出固件。二、构建流程全貌一次完整的构建经过以下阶段west build调用 CMakeCMake 处理CMakeLists.txt执行find_package(Zephyr)加载开发板配置.dts、_defconfig处理 Kconfig 配置prj.conf处理设备树.dts.overlay生成build.ninjaNinja 执行编译和链接产出zephyr.elf/.hex/.bin三、Kconfig 与设备树构建系统的配置层Kconfig 和设备树是 Zephyr 构建系统中“配置”与“硬件描述”的两个核心机制。Kconfig 源自 Linux 内核用于在编译时选择启用或禁用功能。你的应用配置通常写在prj.conf中例如kconfigCONFIG_GPIOy CONFIG_UART_CONSOLEy CONFIG_LOGy初始配置由开发板的*_defconfig与应用的prj.conf合并而成。设备树则描述“硬件长什么样”。当你的应用需要使用开发板原生不支持的外设时可以通过.overlay文件扩展。例如添加一个 I2C 设备dtsi2c1 { status okay; my_sensor: sensor48 { compatible my-vendor,my-sensor; reg 0x48; }; };Shield扩展板机制也基于设备树 overlay 实现开发板定义连接器引脚的标签如arduino_i2cShield 的 overlay 文件引用这些标签构建时自动“接线”。四、项目管理West Manifest 与多仓库West 的核心能力是管理多个 Git 仓库。Manifest 文件是 YAML 格式的配置定义了项目中包含的所有仓库及其版本yamlmanifest: projects: - name: zephyr url: https://github.com/zephyrproject-rtos/zephyr revision: main - name: hal_nordic url: https://github.com/zephyrproject-rtos/hal_nordic path: modules/hal/nordic revision: mainManifest 文件让开发者能够轻松管理多个 Git 仓库实现模块化开发和版本控制。你可以创建自己的 manifest 仓库将 Zephyr 核心、你的应用代码、以及第三方模块统一管理通过west init -m your-manifest-url一键初始化整个项目。五、分阶段学习路径第一阶段入门筑基1-2 周目标环境搭建、理解构建流程、能编译和烧录示例。安装 West、Zephyr SDK 和工具链用west build编译hello_world用west flash烧录理解west build→ CMake → Ninja 的调用链阅读一个示例的CMakeLists.txt和prj.conf里程碑能在目标开发板上跑通hello_world并修改源代码后重新编译烧录。第二阶段进阶实战2-4 周目标掌握 Kconfig、设备树、自定义应用结构。创建自己的应用目录编写CMakeLists.txt和prj.conf学习 Kconfig 语法用menuconfig或guiconfig交互式配置编写设备树 overlay添加外设I2C 传感器、SPI Flash 等掌握west build -p、-d、--等常用选项用west flash和west debug完成烧录和调试里程碑能独立创建包含自定义外设配置的 Zephyr 应用。第三阶段高级深耕1-2 个月目标深入构建系统内部掌握多仓库管理和高级构建特性。创建自定义 West manifest 仓库管理私有模块编写 Zephyr 模块module集成第三方库理解 Sysbuild多镜像构建的使用场景掌握 Kconfig 依赖解析和设备树 binding 编写使用west forall、west diff等批量管理命令里程碑能搭建一套基于 West manifest 的多仓库项目模板供团队复用。六、内存与堆栈分析ram_report的输出会按文件路径分组并标出每个符号的字节数和占比。如果某个符号出现在(hidden)或(no paths)类别下说明它没有可用的文件元数据通常是链接器生成的符号或未归档的模块。实用技巧把报告重定向到文件用文本编辑器按大小排序bashwest build -t ram_report ram_report.txt七、构建诊断命令用途west build -t menuconfig启动 curses 交互界面搜索、查看、修改 Kconfig 配置west build -t guiconfig图形化 Kconfig 配置界面west build -t traceconfig追踪每个 Kconfig 值的来源排查“为什么这个配置没生效”west build -p alwaysPristine 构建清除缓存后重新配置切换板子/改设备树后必备west build --cmake-only只跑 CMake 配置阶段不编译用于快速检查设备树/Kconfig 是否有效menuconfig里按/可以搜索符号按?查看帮助和依赖关系是排查“配置项为什么没生效”的首选工具。traceconfig特别适合解决 Kconfig 配置被覆盖或依赖不满足的问题它能显示每个值的最终来源。注意必须在 pristine 构建之后运行否则旧的.config会干扰结果。八、设备树排查命令用途west build --cmake-only只跑配置生成最终的zephyr.dts不编译查看build/zephyr/zephyr.dts所有 overlay 合并后的最终设备树确认节点、属性、状态是否正确查看build/zephyr/include/generated/devicetree_generated.h设备树生成的宏定义确认DT_NODELABEL等宏展开结果设备树语法错误会在west build时直接报错但如果节点存在却没有生成对应设备通常是 Kconfig 中驱动选项未启用需要用menuconfig确认。九、烧录与调试命令用途west flash烧录固件到目标板west flash -r runner指定烧录器jlink、openocd、pyocd等west flash -H列出当前板子支持的所有 runnerwest debug启动 GDB 调试会话自动连接 OpenOCD/JLink 等west debugserver只启动调试服务器不自动连接 GDBwest attach附加到已在运行的目标不重新烧录适合调试已烧录的签名固件west rtt通过 SEGGER RTT 实时读取目标日志west debug会加载未签名的 ELF 文件如果你的固件经过签名比如 Ambiq 的 OTA 打包流程直接用west debug可能不匹配。这时先用west flash烧录再用west attach附加调试。十、工作区与依赖诊断命令用途west list列出工作区中所有项目及其路径west manifest --validate校验 manifest 文件语法是否正确west manifest --resolve输出合并所有 import 后的最终 manifest排查“某个模块为什么没被拉取”west manifest --path打印当前使用的 manifest 文件路径west diff显示工作区中所有仓库的未提交改动你已经用过west status类似git status但作用于整个工作区west forall -c 命令在所有项目中批量执行命令如west forall -c git log --oneline -1west update --stats更新时输出统计信息排查拉取失败west -v update详细模式输出实际执行的 Git 命令排查网络/权限问题west config -l列出当前生效的所有配置项system/global/local 合并后的结果十一、配置诊断命令用途west config -l列出所有生效配置west config manifest.path查看当前 manifest 路径配置west config zephyr.base查看ZEPHYR_BASE的实际来源west boards列出所有支持的开发板确认板子名称拼写是否正确west help command查看任意命令的详细帮助