📚 课程目录第2章开发环境搭建

2. 开发环境搭建：安装Zephyr SDK、获取Zephyr源码、配置west工具、编译第一个示例

搭建一个稳定、可复现的开发环境是Zephyr驱动开发的第一步。本章将引导你完成从零开始配置Zephyr开发环境的全过程，包括SDK安装、源码获取、west工具配置以及编译运行第一个示例程序。

2.1 环境概览与依赖关系

Zephyr开发环境由四个核心层次组成，它们之间的依赖关系如下图所示：

提示：Zephyr SDK 并非必须使用官方预编译包。如果你熟悉交叉编译，也可以使用系统自带的工具链（如 ARM GCC），但官方 SDK 提供了最一致的体验和预编译的调试器、QEMU 支持。

2.2 安装 Zephyr SDK

Zephyr SDK 为每个支持的架构提供了预编译的交叉工具链、GDB 调试器以及 QEMU 模拟器。推荐使用最新稳定版本。

2.2.1 下载与解压

访问 Zephyr SDK 发布页面，下载适用于你主机系统的 SDK 压缩包（如 zephyr-sdk-0.16.8_linux-x86_64.tar.xz）。
将 SDK 解压到目标目录，例如 /opt/zephyr-sdk：

# 创建目标目录
sudo mkdir -p /opt/zephyr-sdk

# 解压 SDK
sudo tar xvf zephyr-sdk-0.16.8_linux-x86_64.tar.xz -C /opt/zephyr-sdk

# 进入解压后的目录
cd /opt/zephyr-sdk/zephyr-sdk-0.16.8

2.2.2 运行安装脚本

SDK 目录中包含一个 setup.sh 脚本，它会安装 udev 规则（用于 USB 设备访问）和必要的符号链接：

sudo ./setup.sh

安装完成后，验证工具链是否可用：

# 检查 ARM 工具链版本
/opt/zephyr-sdk/zephyr-sdk-0.16.8/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc --version

2.2.3 设置环境变量

将以下内容添加到你的 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）中：

export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk/zephyr-sdk-0.16.8

然后执行 source ~/.bashrc 使配置生效。

注意：ZEPHYR_SDK_INSTALL_DIR 环境变量必须指向 SDK 的具体版本目录，而不是父目录。如果设置错误，west 构建时会提示找不到工具链。

2.3 获取 Zephyr 源码

Zephyr 使用 west 工具来管理多个 Git 仓库（manifest + 模块）。首先需要安装 west，然后使用它来获取源码。

2.3.1 安装 west 工具

west 是一个 Python 包，通过 pip 安装：

# 使用 pip3 安装 west
pip3 install --user west

# 验证安装
west --version

如果 west 命令找不到，请确保 ~/.local/bin 已添加到 PATH 环境变量中。

2.3.2 初始化工作空间

创建一个工作目录并初始化 west：

# 创建工作目录
mkdir ~/zephyr-workspace
cd ~/zephyr-workspace

# 初始化 west（使用官方 manifest）
west init

# 拉取所有模块源码（耗时较长）
west update

west init 会创建一个 .west 目录和 west.yml manifest 文件。west update 会根据 manifest 拉取 Zephyr 主仓库、hal 库、驱动模块等所有依赖。

2.3.3 导出 Zephyr CMake 包

为了让 CMake 能够找到 Zephyr 的构建系统，需要导出 CMake 包：

# 在 zephyr 目录内执行
cd ~/zephyr-workspace/zephyr
west zephyr-export

2.4 配置 west 工具

west 的配置文件位于 ~/.config/west/config.yml。你可以通过 west config 命令查看和修改配置。

2.4.1 常用配置项

配置项	说明	默认值
`manifest.path`	manifest 文件所在目录（相对于工作空间根目录）	`zephyr`
`manifest.file`	manifest 文件名	`west.yml`
`zephyr.base`	Zephyr 仓库的路径	自动检测

2.4.2 设置默认构建目录

你可以配置 west 将构建输出放在工作空间内的统一目录中：

west config build.dir-fmt "build/{board}/{app}"

这样，每次构建的输出都会按 build/<板卡名>/<应用名> 的格式组织，便于管理。

2.5 编译第一个示例：Hello World

现在环境已经就绪，我们来编译 Zephyr 自带的 hello_world 示例，目标板卡选择 qemu_cortex_m3（ARM Cortex-M3 模拟器）。

2.5.1 构建步骤

cd ~/zephyr-workspace/zephyr/samples/hello_world

使用 west 构建：

west build -b qemu_cortex_m3 .

构建过程会执行以下操作：

CMake 配置：检测工具链、板卡配置、设备树。
编译：编译内核、驱动、应用源码。
链接：生成 ELF 文件（zephyr/zephyr.elf）。
生成 hex/bin 文件：用于烧录或模拟。

2.5.2 构建输出结构

构建完成后，输出目录（默认 build）的关键文件如下：

文件/目录	说明
`build/zephyr/zephyr.elf`	带符号的 ELF 可执行文件
`build/zephyr/zephyr.bin`	纯二进制镜像（用于烧录）
`build/zephyr/zephyr.hex`	Intel HEX 格式镜像
`build/zephyr/.config`	最终使用的 Kconfig 配置
`build/zephyr/include/generated/`	自动生成的头文件（设备树、配置宏等）

2.5.3 在 QEMU 中运行

构建成功后，使用 west 的 build -t run 命令在 QEMU 中运行：

west build -t run

你会看到 QEMU 窗口弹出（或终端输出），并打印：

***** Booting Zephyr OS v3.6.0 *****
Hello World! qemu_cortex_m3

按 Ctrl+A 然后按 X 退出 QEMU。

  关键概念：Zephyr 的构建系统基于 CMake，west 只是封装了 CMake 调用。你可以直接使用 cmake -B build -DBOARD=qemu_cortex_m3 . 和 cmake --build build 来手动构建，但 west 提供了更简洁的跨平台体验。

2.6 构建流程详解

理解 Zephyr 的构建流程有助于后续调试驱动问题。下图展示了从源码到可执行文件的完整链路：

2.7 常见问题与排查

问题	可能原因	解决方案
`west: command not found`	Python 用户 bin 目录未加入 PATH	添加 `export PATH=$HOME/.local/bin:$PATH` 到 shell 配置
`ZEPHYR_SDK_INSTALL_DIR not set`	环境变量未配置或配置错误	检查 `echo $ZEPHYR_SDK_INSTALL_DIR`，确保指向 SDK 版本目录
`Board 'xxx' not found`	板卡名称拼写错误或未拉取板卡定义	运行 `west boards` 列出所有可用板卡，确认名称
undefined reference to `...'	Kconfig 未启用相关模块	检查 `.config` 文件，确认所需驱动或子系统已启用

调试技巧：如果构建失败，首先查看 build/zephyr/.config 文件，确认你的配置是否生效。使用 west build -t menuconfig 可以交互式修改配置。

2.8 本章小结

完成本章后，你应该已经掌握了：

Zephyr SDK 的安装与环境变量配置。
使用 west 工具初始化工作空间并拉取源码。
west 的基本配置方法。
编译并运行第一个 Zephyr 示例程序。
理解 Zephyr 从源码到镜像的完整构建流程。