从源码到跑起来:完整讲解 Zephyr 在 Nucleo G474RE 板上的编译

嵌入式开发中，将 RTOS 从源码构建到硬件运行是一项核心技能。本文以 Nucleo G474RE 为例，梳理 Zephyr 从源码获取、Python 依赖、HAL 模块提取、构建、烧录到运行的全过程，涵盖 Windows 环境变量、遇到的坑及解决方案。

一、编译前工具准备

1. 必要工具

• Python ≥ 3.9：构建系统脚本、测试和工具依赖
• pip：安装 Python 依赖包
• CMake ≥ 3.20：Zephyr 构建系统生成 Make/Ninja 文件
• Ninja ≥ 1.10：快速构建系统
• Zephyr SDK 或 ARM 工具链（arm-none-eabi-gcc）：交叉编译 STM32 目标
• west：Zephyr meta-tool，管理源码和模块
• 串口工具（minicom / PuTTY）：查看串口输出

1. Python 依赖

安装 Zephyr 的 Python 依赖：

pip install --upgrade pippip install -r zephyr/scripts/requirements.txt

requirements.txt 会安装以下类型工具：

• 构建工具：west、pyyaml、jinja2
• 测试工具：pytest、pytest-xdist、pyserial、colorama
• 脚本工具：pyelftools、packaging

建议使用 Python 虚拟环境：

python -m venv .venv.venv\Scripts\activate   # Windows

1. Windows 下环境变量

在 Windows 开发时，需要设置以下临时环境变量：

set ZEPHYR_BASE=%~dp0set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmembset GNUARMEMB_TOOLCHAIN_PATH=D:\tool\armgccset PATH=D:\tool\armgcc\bin;D:\tool\cmake\bin;%PATH%

说明：

• ZEPHYR_BASE 指向 Zephyr 源码目录
• ZEPHYR_TOOLCHAIN_VARIANT 指定工具链类型
• GNUARMEMB_TOOLCHAIN_PATH 指向 ARM GCC 工具链
• PATH 包含工具链和 CMake
• 临时变量仅对当前命令行窗口有效，关闭后失效

二、获取 Zephyr 源码

1. 克隆源码包

git clone --recursive https://github.com/zephyrproject-rtos/zephyr.gitcd zephyr

1. 无法拉取或中断的解决方案

• 网络慢或 Git 超时：使用浅克隆或手动下载 GitHub zip/tar
• 子模块未初始化：git submodule update --init --recursive
• 部分模块卡住：手动 clone，例 git clone https://github.com/zephyrproject-rtos/hal_stm32.git modules/hal/stm32

三、提取 HAL 模块 modules/hal/stm32

编译 Nucleo G474RE 时，如果没有 HAL 模块，可能报错：

fatal error: stm32g474rbtx-pinctrl.dtsi: No such file or directory

原因：Devicetree 文件在 HAL 模块中，必须先提取：

west update modules/hal/stm32

提取日志示例：

=== updating hal_stm32 (modules/hal/stm32):--- hal_stm32: initializingInitialized empty Git repository in D:/work/item/linux/zephyr/modules/hal/stm32/.git/--- hal_stm32: fetching, need revision ff0f1fa5ab4e6559cfbb61d5270d38caad9ad0b0remote: Enumerating objects: 49592, done.Receiving objects: 100% (49592/49592), 144.39 MiB | 891.00 KiB/s, done.Updating files: 100% (8162/8162), done.HEAD is now at ff0f1fa5 lib: stm32wba: Add Bluetooth LE link layer for WBA2x

modules/hal/stm32 目录内容：

• dts/：Devicetree pinctrl 文件
• lib/：HAL 库与通用驱动
• LICENSE：模块许可证
• README.rst：模块说明
• scripts/：辅助 Python / Bash 脚本
• stm32cube/：STM32Cube 封装库
• zephyr/：Zephyr HAL 接口和适配文件

四、编译示例程序

以 hello_world 为例：

cd zephyr/samples/hello_worldmkdir buildcd buildwest build -b nucleo_g474re ..

生成文件：

• zephyr.elf → 可调试
• zephyr.hex / zephyr.bin → 烧录用

CMake 会自动识别 workspace 下的 HAL 模块。

五、烧录固件

west flash# 或使用 OpenOCDwest flash --runner openocd

六、查看运行效果

默认输出到 LPUART1（PA2/PA3），波特率 115200：

minicom -D /dev/ttyACM0

输出示例：

Hello World! arm

七、常见坑与解决方案

• 找不到 STM32 DTS 文件 → HAL 模块未提取，运行 west update modules/hal/stm32
• 编译找不到头文件 → modules/hal/stm32 目录位置不对
• 多次 update 卡住 → Git 仓库大，可使用 --depth 1 或手动 clone
• CMake 找不到模块 → ZEPHYR_BASE 未设置
• Python 工具报错 → 未执行 pip install -r zephyr/scripts/requirements.txt
• 烧录失败 → 板子没电或驱动未装

八、总结

• 先安装 Python 依赖，保证构建和工具脚本正常
• 拉取完整 HAL 模块，确保 DTS、HAL、pinctrl 文件存在
• Windows 下使用临时环境变量，方便多版本共存
• 使用独立 build 目录，避免污染源码
• 遇到问题时检查 ZEPHYR_BASE、modules 和工具链路径

完整流程：源码获取 → Python 依赖 → HAL 模块提取 → 编译 → 烧录 → 运行