编译和烧录

概述

按照本指南，您可以：

在 Ubuntu 或 Windows 上搭建 Zephyr 命令行开发环境（本指南适用于 Ubuntu 24.04 LTS 及以上版本。如果您使用其他 Linux 发行版，请参考 Install Linux Host Dependencies）
获取源代码
编译、烧录和运行示例应用程序

选择和更新操作系统

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

Linux (Ubuntu):

更新系统软件包：

sudo apt update
sudo apt upgrade

安装依赖

接下来，使用包管理器安装主机依赖项。

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

工具	最低版本
CMake	3.28.0
Python	3.12
Device Tree Compiler	1.4.6

Linux (Ubuntu):

使用 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 可能不可用，需要从安装列表中移除。

验证已安装的主要依赖项版本：
```
cmake --version
python3 --version
dtc --version
```
将输出版本与上表中的要求进行对照。如需手动更新依赖项，请参考 Install Linux Host Dependencies 页面。

Windows:

使用 winget 安装所需的依赖项：

winget install Kitware.CMake Ninja-build.Ninja oss-winget.gperf Python.Python.3.12 Git.Git oss-winget.dtc wget 7zip.7zip

更多说明请参考 Zephyr 官方 Getting Started Guide 的 Install dependencies 章节。

验证已安装的版本：

cmake --version
python --version
dtc --version

获取 Zephyr 并安装 Python 依赖

接下来，下载 Zephyr 及其模块到新的 west 工作区。您还将在一个独立的 Python 虚拟环境中安装 Zephyr 所需的 Python 依赖项，使其与系统自带的 Python 环境相互隔离。

下文命令以 ~/nuwa 作为工作区路径示例，实际名称和位置可以自由选择，请替换为您自己的实际路径。

创建新的虚拟环境：
```
python3 -m venv ~/nuwa/.venv
```
激活虚拟环境：
```
source ~/nuwa/.venv/bin/activate
```
激活后，shell 提示符将显示 (.venv) 前缀。随时可以通过运行 deactivate 退出虚拟环境。

备注

每次开始工作时，请记得激活虚拟环境。
安装 west：
```
pip install west
```

获取 nuwa Zephyr 源代码：

cd ~/nuwa
west init -m https://github.com/Ameba-AIoT/nuwa.git
west update

导出 Zephyr CMake 包。将当前 Zephyr 源码注册到 CMake。注册后，CMake 在编译应用程序时便能自动找到并加载 Zephyr：
```
west zephyr-export
```
创建指向 nuwa.py 的快捷方式。该 Python 脚本封装了 west 命令，使用 nuwa.py 编译时，会自动安装 Python 依赖项和 Toolchain：
```
ln -sf tools/meta_tools/nuwa.py nuwa.py
```
使用 west 安装 Python 依赖项（使用 nuwa.py 时自动安装）：
```
west packages pip --install
```

安装 Toolchain

Zephyr 工具链包含编译 Zephyr 应用程序所需的编译器、汇编器、链接器等工具，覆盖 Zephyr 支持的各种目标架构。

目前 Ameba 平台仅支持使用 Ameba 提供的 gnuarmemb 工具链，不支持 Zephyr 官方发布的 Zephyr SDK 工具链。

使用以下命令，即可安装由 Ameba 提供的工具链（使用 nuwa.py 时自动安装）：

cd ~/nuwa
west realtek ameba install

通过命令选项可以指定 SDK 的安装位置和需要安装哪些架构的工具链，详情请运行 west realtek ameba install -h 查看。

使用 nuwa.py 编译时，会自动将 ZEPHYR_TOOLCHAIN_VARIANT 和 GNUARMEMB_TOOLCHAIN_PATH 两个环境变量设置为指向此处安装的 Toolchain，无需手动配置；若跳过 nuwa.py，直接使用 west 或 zephyr 原生命令，则需手动配置这两个工具链环境变量：

Linux (Ubuntu):

export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH=~/rtk-toolchain/asdk-12.3.1-4600/linux/newlib

Windows:

使用 setx 命令配置用户环境变量（配置后需重新打开终端窗口才会生效）：

setx ZEPHYR_TOOLCHAIN_VARIANT gnuarmemb
setx GNUARMEMB_TOOLCHAIN_PATH C:\rtk-toolchain\asdk-12.3.1-4600\mingw32\newlib

更多说明可参考 Zephyr 官方文档 GNU Arm Embedded。

创建应用程序

SDK 采用 CMake 作为编译系统。该编译系统以应用程序为中心，将应用程序代码与 Zephyr 内核源代码编译成一个统一的二进制文件。主要包括两部分：

Zephyr 基本目录：包含 Zephyr 自己的源代码、内核配置选项和编译定义。
应用程序目录：包含所有指定用于应用程序的文件，例如配置选项和源代码。

一个典型的应用程序目录结构如下：

<app>
├── CMakeLists.txt     编译入口脚本，链接 Zephyr 编译系统
├── app.overlay        设备树覆盖文件（可选）
├── prj.conf           应用专属 Kconfig 配置文件
├── VERSION            版本标识文件（可选）
└── src
    └── main.c         应用主程序源文件

编译应用程序

Zephyr 编译系统将应用程序的所有组件编译并链接到单个应用程序固件中，该固件可以在模拟硬件或真实硬件上运行。

与任何其他基于 CMake 的系统一样，编译过程分两个阶段进行。

配置阶段（Configuration Phase）：使用 CMake 命令行工具，在指定生成器时生成编译文件；在 Zephyr 中，该阶段还包括：
- 基于 DTS 内容和 YAML 绑定，生成 build/zephyr/zephyr.dts 和 build/zephyr/include/generated/devicetree_generated.h
- 收集所有 Kconfig 文件，加载默认配置，并结合 DTS 的输出，确定最终的配置选项集合和依赖关系，生成 build/zephyr/.config 和 build/zephyr/include/generated/autoconf.h
- 生成编译系统文件，生成 CMakeCache.txt 和 build.ninja
编译阶段（Build Phase）：使用本地编译工具（如 Ninja）执行实际编译并链接生成固件。要了解有关这些概念的更多信息，请参阅 CMake 官方文档中的 CMake 介绍。

编译命令

使用以下命令编译应用程序：

./nuwa.py build -b <BOARD> [-d <BUILD_DIR>] [-i <IMAGE_DIR>] [-p] [--sysbuild] <SOURCE_DIR>

参数说明：

build：执行 build 编译子命令；
-b <BOARD>：【必填】指定目标开发板名称（如 rtl872xda_evb）。编译工具链会自动在 zephyr/boards/realtek/rtl872xda_evb 路径下加载开发板配置文件；
<SOURCE_DIR>：【必填】位置参数，指定应用工程路径（相对 SDK 根目录的相对路径）；
-d <BUILD_DIR>：【可选】设置编译产物的输出目录，编译生成的所有中间文件与结果文件均存放至该目录，目录名可自定义，不指定时默认为 build 文件夹；
-i <IMAGE_DIR>：【可选】设置 ImageTool 固件输出目录，不指定时默认为 SDK/images；
-p：【可选】完整清理并重新编译，不指定时默认按需增量编译（仅在配置变化时重新生成），指定后会先清理并重新生成整个编译目录再编译，等价于先执行 west build -t pristine 后再编译；
--sysbuild：【可选】创建 multi-domain（sysbuild）编译系统，用于将多个 image（如应用程序与 MCUboot）合并编译，详见 Zephyr 官方 Sysbuild 文档；

示例：编译 Hello World 示例

./nuwa.py build -b rtl872xda_evb zephyr/samples/hello_world

备注

编译（build）阶段建议优先使用 ./nuwa.py build，它是对 west build 的封装，比手动使用 west build 更省事，环境准备详见安装 Toolchain。

部分清理（Clean）

删除编译阶段下生成的文件（如 .obj/.elf/.hex 等），但保留配置阶段下生成的配置文件（如 .config 文件等）：

west build -t clean

完整清理（Pristine）

同时删除编译阶段与配置阶段下生成的文件：

west build -t pristine

打开 menuconfig 菜单

menuconfig 需要读取 build 目录中已有的编译配置信息。请先完成一次应用程序的编译配置，再运行：

west build -t menuconfig

build 目录内容

build 是 CMake 和 Ninja 使用的编译目录，其中包含编译系统文件、中间文件及最终固件。其主要结构如下：

SDK/build/
├── amebaxxx_gcc_project/    多 MCU 固件合并所需的中间文件
├── build.ninja              Ninja 编译文件
├── CMakeCache.txt           CMake 配置缓存
├── CMakeFiles/              CMake 内部文件
├── rules.ninja              Ninja 编译规则
└── zephyr/                  Zephyr 的生成文件和编译产物

完成配置和编译后，通常会生成以下文件：

.config：最终生效的 Kconfig 配置。
.o、.a：编译生成的目标文件和静态库。
zephyr.elf：包含应用程序和 Zephyr 内核的最终 ELF 固件。
zephyr.bin、zephyr.hex：转换得到的其他格式固件。

images 目录和固件下载

编译完成后，可以通过以下两种方式将固件下载至开发板：

west flash：直接使用 west 提供的命令行方式烧录，无需额外工具，具体用法请参考 west flash 用法介绍；
ImageTool：使用 ./nuwa.py 编译完成后，供 ImageTool 下载的固件默认会放置在 SDK/images 目录下；ImageTool 工具位于 SDK/tools/ameba/ImageTool 目录下，请参考 Image Tool 使用指南进行烧录。

west 编译烧录方法介绍

west build 用法介绍

编译前需要设置工具链环境变量。使用 ./nuwa.py 时会自动完成配置，无需手动设置；若直接使用 west 原生命令，请参阅安装 Toolchain 手动配置。

常用命令如下：

# 使用指定开发板编译应用程序
west build -b <BOARD> <SOURCE_DIR>

# 清理默认编译目录
west build -t pristine

west flash 用法介绍

Linux:

Windows 电脑通过串口线连接开发板，Linux 服务器远程烧录。

在 Windows 电脑下载并打开 AmebaRemoteService 软件;
使用串口线连接 Windows 电脑和开发板，并按键进入下载模式；
在 Linux 服务器上执行命令，其中，<PORT> 是开发板在 Windows 电脑上的串口，<WINDOWS_IP> 是该电脑的 IP 地址。
```
west flash --port <PORT> --remote-server <WINDOWS_IP>
```

Windows:

Windows 电脑通过串口线直连开发板烧录。

使用串口线连接 Windows 电脑和开发板，并按键进入下载模式；
使用命令指定串口下载，其中，<PORT> 是开发板在本机上的串口。
```
west flash --port <PORT>
```

备注

如果开发板当前运行的固件已启用 CONFIG_SHELL，执行 west flash 时，烧录工具会在烧录前通过串口发送命令，使开发板自动进入烧录模式，无需手动按键。