搭建开发环境并运行第一个应用

本页依据 文档基线与后续更新 中记录的 Zephyr main 快照更新。

先准备主机工具，再创建 Python 虚拟环境与 west 工作区，最后安装 SDK 并构建应用。 本页以 Ubuntu 24.04 LTS 或更新版本为主；Windows 步骤见 Windows 原生开发环境。

版本要求

本次核对的官方入门指南列出的最低版本为：

工具

最低版本

Python

3.12

CMake

3.20.5

Devicetree compiler（dtc）

1.4.6

这些是 Zephyr 开发环境要求；仅构建本中文资料站的依赖见 构建与维护中文文档。

Ubuntu 主机工具

在终端安装依赖：

sudo apt update
sudo apt install --no-install-recommends git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget python3-dev python3-venv python3-tk \
  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1
cmake --version
python3 --version
dtc --version

AArch64 主机的软件仓库可能没有 gcc-multilib、g++-multilib，应移除这两项。 其他发行版请参照官方 Linux 安装说明选择软件包。

创建工作区

以下命令用于新工作区 ~/zephyrproject，需能够访问 GitHub 和 Python 包源：

python3 -m venv ~/zephyrproject/.venv
source ~/zephyrproject/.venv/bin/activate
python -m pip install west
west init -m https://github.com/zephyrproject-rtos/zephyr --mr main ~/zephyrproject
cd ~/zephyrproject
west update
west packages pip --install
west zephyr-export
cd zephyr
west sdk install

每次打开新终端，先激活同一个虚拟环境。west packages pip --install 从工作区收集 所需 Python 包；安装过程中 west 自身也可能被升级或降级。 west sdk install 根据当前 Zephyr 版本选择 SDK。可用选项见 west sdk install --help，需要时仅安装目标架构工具链。

上述 --mr main 获取运行命令时的开发分支。要复现本次文档基线，把 main 换成 02d743889396e724d53be61e4fe34c484c1d5a97；使用发布版时换成对应标签， 同时选择该版本官方文档。不要在已有工作区重复运行 west init，升级步骤见 工作区、清单与版本更新。

没有开发板时使用 QEMU

在 ~/zephyrproject/zephyr 中，可以直接使用 QEMU 模拟 32 位 Cortex-M3 或 64 位 Cortex-A53 目标板：

# 32 位 ARMv7-M 模拟目标
west build -p always -b qemu_cortex_m3 samples/hello_world
west build -t run

# 64 位 ARMv8-A 模拟目标（调用 qemu-system-aarch64）
west build -p always -b qemu_cortex_a53 samples/hello_world
west build -t run

终端会显示启动横幅与 Hello World! qemu_cortex_a53 输出。QEMU 通常可先按 Ctrl+A 松开后再按 X 退出。首次构建或切换目标板时使用 -p always 清理指定构建目录的旧产物， 后续相同目标可用 west build 进行增量构建。这里的清理只应针对构建输出目录。

想要基于 qemu_cortex_a53 从零编写包含日志、Shell、GPIO 中断、多线程消息队列和 NVS 存储的 完整工程，可在阅读完 应用构建、Kconfig 与 Devicetree 后进入 综合应用实战（基于 qemu_cortex_a53）。

在硬件上运行

查看所用板卡的官方页面，取得准确的 board target，并确认烧录工具和调试探针要求：

west boards
west build -p always -b nrf52840dk/nrf52840 samples/basic/blinky
west flash

此例目标是 nRF52840 DK；使用其他开发板时替换目标。多核目标可能还需要 CPU cluster， 例如 nrf5340dk/nrf5340/cpuapp。Blinky 需要板级定义的 LED；没有相应 LED 的板卡可以 构建 samples/hello_world。Linux 主机还可能需要调试探针的 udev 规则。

macOS

当前上游入门文档注明不支持 x86-64 macOS。受支持主机可按官方步骤安装 Homebrew 依赖：

brew install cmake ninja gperf python3 python-tk ccache qemu dtc libmagic wget openocd

随后使用本页的虚拟环境、west 工作区与 SDK 流程，先确认 python3 --version 满足最低要求；Homebrew 的路径设置按安装器输出配置。

排查顺序

  1. python --version 和 python -m pip --version 是否来自预期虚拟环境。

  2. west topdir 是否指向当前工作区，west list 是否显示完整的所需模块。

  3. 切换版本后是否重新执行 west update 和依赖安装。

  4. 开发板名称是否符合当前硬件模型，是否使用了该目标自己的构建目录。

  5. SDK 是否与当前源码要求匹配，烧录 runner 是否已安装且能访问调试探针。

上游依据