入门指南

按照本指南可以：

  • 在 Ubuntu、macOS 或 Windows 上搭建 Zephyr 命令行开发环境（其他 Linux 发行版的安装说明见 安装 Linux 主机依赖）

  • 获取源代码

  • 构建、烧录并运行示例应用

选择并更新操作系统

点击你正在使用的操作系统。

本指南适用于 Ubuntu 24.04 LTS 及更高版本。如果你使用其他 Linux 发行版，请参阅 安装 Linux 主机依赖。

sudo apt update
sudo apt upgrade

安装依赖

接下来安装 Zephyr 配置和构建应用所需的主机工具。下面的说明使用各操作系统推荐的包管理器，安装后即可在终端中使用这些工具。

主要依赖当前要求的最低版本如下：

工具

最低版本

CMake

3.28.0

Python

3.12

Devicetree 编译器

1.4.6

备注

强烈建议使用 Python 3.12。使用更新的 Python 版本在某些系统上可能会失败，例如在 Windows 上安装所需软件包时。

  1. 使用 apt 安装所需依赖：

    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

    备注

    由于 AArch64（ARM64）系统上没有 gcc-multilib 和 g++-multilib，你可能需要把它们从待安装的软件包列表中移除。

  2. 输入以下命令，确认系统中已安装的主要依赖版本：

    cmake --version
python3 --version
dtc --version

    将这些版本与本节开头表格中的版本进行对比。有关手动更新依赖的更多信息，请参阅 安装 Linux 主机依赖 页面。

获取 Zephyr 并安装 Python 依赖

接下来使用 west 创建工作区，并获取 Zephyr 及其 模块。

下面的命令使用 zephyrproject 作为工作区名称，你可以选择其他名称和位置。你还会把 Zephyr 的 Python 依赖安装到 Python virtual environment 中，使其与系统 Python 环境相互隔离。

  1. 创建新的虚拟环境：

    python3 -m venv ~/zephyrproject/.venv

  2. 激活虚拟环境：

    source ~/zephyrproject/.venv/bin/activate

    激活后命令提示符前会出现 (.venv) 前缀。随时可以通过运行 deactivate 退出虚拟环境。

    备注

    每次打开新的终端会话后，在使用 Zephyr 之前都要记得激活虚拟环境。否则 west 等命令会找不到，或运行在其他 Python 环境中，从而产生令人困惑的错误。

  3. 安装 west：

    west 是 Zephyr 的工作区管理工具，接下来的命令将使用它创建和更新工作区。

    pip install west

  4. 获取 Zephyr 源代码：

    west init 会创建一个 west 工作区，并把 https://github.com/zephyrproject-rtos/zephyr 克隆为其 清单仓库。

    west update 随后会获取 Zephyr 的 west 清单 中列出的各个 west 项目，也就是前面提到的模块（例如硬件抽象层 HAL、各种库等）。

    west init -m https://github.com/zephyrproject-rtos/zephyr ~/zephyrproject
cd ~/zephyrproject
west update

    小技巧

    为了减少磁盘占用、避免在初始化时下载不需要的模块或厂商 HAL，可以在运行 west update 之前配置 项目组。

  5. 安装 Zephyr 的 Python 依赖：

    west packages 会从已检出的 Zephyr 工作区（包括其中的模块）读取 Python 依赖要求，因此安装的软件包与所获取的 Zephyr 版本一致。

    west packages pip --install

    备注

    安装这些依赖可能会升级或降级 west 本身。

  6. 导出 Zephyr CMake 包。这会把当前的 Zephyr 检出注册到 CMake 的用户包注册表中，使 find_package(Zephyr) 在构建应用时能够自动找到它。

    west zephyr-export

安装 Zephyr SDK

Zephyr 软件开发工具包（SDK） 包含 Zephyr 所支持的每种架构的工具链，其中包括为目标硬件构建 Zephyr 应用所需的编译器、汇编器、链接器以及其他程序。

它还包含额外的主机工具，例如用于仿真、烧录和调试 Zephyr 应用的定制 QEMU 和 OpenOCD。

在 Zephyr 仓库中通过 west sdk install 安装 Zephyr SDK：

cd ~/zephyrproject/zephyr
west sdk install

小技巧

可以使用命令选项指定 SDK 的安装位置，或只安装选定架构的工具链。详情请运行 west sdk install --help。

备注

如果不想使用 west sdk 命令安装 Zephyr SDK，请参阅 安装 Zephyr SDK。

构建 Blinky 示例

备注

Blinky 兼容大多数 开发板，但并非全部。如果你的开发板不满足 Blinky 的 Requirements，可以改用 Hello World。

如果不确定 west 使用的开发板名称，可以用 west boards 列出 Zephyr 支持的所有开发板。开发板的 文档页面 也会给出传给 west build 的准确开发板目标名称。

使用 west build 构建 Blinky。将 <your-board-name> 替换为你的开发板名称：

cd ~/zephyrproject/zephyr
west build -p always -b <your-board-name> samples/basic/blinky

-p always 选项会强制执行全新构建，清除之前配置留下的构建产物，在入门阶段可以避免残留文件造成干扰。之后可以使用 -p auto，让 west build 自行判断何时需要全新构建。详情请运行 west build -h。

备注

一块开发板可能包含一个或多个 SoC，每个 SoC 又可能包含一个或多个 CPU 集群。为这类开发板构建时，需要指定示例要构建到哪个 SoC 或 CPU 集群。例如，要为 nRF5340 DK 上的 cpuapp 核心构建 Blinky，开发板名称应写成：nrf5340dk/nrf5340/cpuapp。更多细节参见 开发板术语。

烧录示例

连接开发板（通常通过 USB），如果有电源开关请打开。如果不确定该如何操作，请查看 开发板 中对应开发板的页面，因为某些开发板需要特定的设置或烧录步骤。

使用 west flash 烧录示例。该命令会把刚构建好的应用烧写到已连接的开发板上：

west flash

备注

你可能需要为开发板安装额外的 主机工具。如果缺少必需的依赖，west flash 命令会报错。

备注

在 Linux 上，首次通过调试探针烧录前可能需要配置 udev 规则，参见 设置 udev 规则。

如果使用的是 blinky，LED 会按下图所示开始闪烁：

../../_images/ReelBoard-Blinky.webp

运行 blinky 的 Phytec reel_board

后续步骤

下面是进一步探索 Zephyr 的一些建议：

寻求帮助

在寻求帮助之前，请先搜索本文档、Zephyr 项目的 GitHub discussions 与 issues，以及 Discord 聊天记录，你的问题可能已经有答案。你也可以使用每个文档页面都提供的 聊天机器人。

寻求帮助时，请附上：

  1. 你想做什么

  2. 你尝试过什么，包括运行过的命令

  3. 实际结果如何，包括完整的文本输出

请复制并粘贴文本，不要直接发截图。在 Discord 或 GitHub 上，如果终端输出、源代码或日志超过 5 行，请用三个反引号创建代码块。