编译和烧录

概述

按照本指南，您可以：

在 Ubuntu 或 Windows 上搭建 Zephyr 命令行开发环境（其他 Linux 发行版请参考 Install Linux Host Dependencies）
获取源代码
编译、烧录和运行示例应用程序

选择和更新操作系统

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

本指南适用于 Ubuntu 22.04 LTS 及以上版本。如果您使用其他 Linux 发行版，请参考 Install Linux Host Dependencies 。

Linux (Ubuntu):

更新系统软件包：

sudo apt update
sudo apt upgrade

安装依赖

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

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

工具	最低版本
CMake	3.20.5
Python	3.10
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:

请参考 Install Windows Host Dependencies 页面安装依赖项。

验证已安装的版本：

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

获取 Zephyr 并安装 Python 依赖

接下来，下载 Zephyr 及其模块到新的 west 工作区。在以下说明中，工作区名称使用 nuwa，但实际名称和位置可以自由选择。您还将在 Python 虚拟环境中安装 Zephyr 的额外 Python 依赖项。

创建新的虚拟环境：
```
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 包。这允许 CMake 自动加载编译 Zephyr 应用程序所需的样板代码：
```
west zephyr-export
```
创建指向 nuwa.py 的快捷方式，该 python 脚本对 west command 进行封装，使用 nuwa.py 编译时，会自动帮忙安装 Python 依赖项以及安装 Toolchain：
```
ln -sf tools/meta_tools/nuwa.py nuwa.py
```
使用 west 安装 Python 依赖项（使用 nuwa.py 时自动安装）：
```
west packages pip --install
```
备注

此操作可能会降级或升级 west 本身。

安装 Toolchain

Zephyr Software Development Kit (SDK) 包含 Zephyr 支持的每种架构的工具链，包括编译器、汇编器、链接器以及编译 Zephyr 应用程序所需的其他程序。

使用 west sdk install 安装由 Ameba 提供的 SDK（使用 nuwa.py 时自动安装）：

cd ~/nuwa
west realtek ameba install

小技巧

通过命令选项，可以指定 SDK 安装目标位置和安装哪些架构的工具链。详情请参见 west realtek ameba install -h。

创建应用程序

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 <device> -a <application> [-p]

参数说明：

build：执行 build 子命令；
-b <device>：指定目标开发板（如 rtl872xda_evb，编译工具链会自动从 zephyr/boards/realtek/rtl872xda_evb 目录下搜索需要的 board 配置文件）；
-d BUILD_DIR：可选，设置 build 输出文件目录，所有编译过程中生成的文件均存此目录中，目录名可以任意指定；
-a <application>：指定应用程序路径（相对 SDK 根目录）；
-p：重新编译（Rebuild），如果 build 目录中存在之前编译的信息，若不指定 -p 参数，则执行默认的增量编译操作，否则将执行重新编译操作；

示例：编译 Hello World 示例

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

部分清理（Clean）

删除 Build Phase 下生成的文件（如 .obj/.elf/.hex 等），但保留 Configuration Phase 下生成的配置文件（如 .config 文件等）：

west build -t clean 或者 ./nuwa.py build -c

完整清理（Pristine）

同时删除 Build Phase 与 Configuration Phase 下生成的文件：

west build -t pristine

打开 Menu Config 菜单

menuconfig 是编译过程的一部分，依赖于配置阶段生成的编译系统中间文件，如果 build 目录为空时，则无法启动 menuconfig（因为此时编译系统不知道具体的应用程序目录）：

west build -t menuconfig 或者 ./nuwa.py config

build 目录内容

默认情况下，build 目录结构如下：

SDK/build
├── amebaxxx_gcc_project       多个 MCU bin 拼接的中间过程文件
├── build.ninja                Ninja 编译脚本（自动生成）
├── CMakeCache.txt             CMake 缓存配置
├── CMakeFiles                 CMake 中间文件
├── cmake_install.cmake        安装脚本（通常不使用）
├── rules.ninja                Ninja 规则定义
└── zephyr                     用于生成编译系统的工作目录，大部分生成的文件都是在其中创建和存储的。

运行 ninja 后，以下编译输出文件将被写入 build 目录的 zephyr 子目录。

.config ，包含用于编译应用程序的配置设置。
包含已编译内核和应用程序代码的各种目标文件（ .o 文件和 .a 文件）。
zephyr.elf ，其中包含最终组合的应用程序和内核二进制文件。还支持其他二进制输出格式，例如 .hex 和 .bin 。

images 目录和固件下载

使用 ./nuwa.py 编译完成后，供 ImageTool 下载的固件将放置在 SDK/images 目录下。然后使用 ImageTool 进行固件下载，工具位于： SDK/tools/ameba/ImageTool 目录下，请参考 Image Tool 使用指南进行烧录。

west 编译烧录方法介绍

west build 用法介绍

需要添加两个环境变量（需要检查环境有没有配置，如果没有需要添加）：

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

常用命令示例：

west build -b <BOARD> path/to/build/directory //编译某个板型的某个工程
west build -t pristine                        //纯净编译，删除编译目录中的所有文件

west flash 用法介绍

Linux:

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

在 window 电脑下载并打开 AmebaRemoteService 软件;
使用串口线连接 windows 电脑和开发板，并按键进入下载模式；
在 Linux 服务器上执行命令，其中 ip 是 windows 电脑的 ip ：
```
west flash --port port --remote-server ip
```

Windows:

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

使用串口线连接 windows 电脑和开发板，并按键进入下载模式；
使用命令指定 port 下载：
```
west flash --port port
```

备注

如果开发板中的固件在编译时打开了 CONFIG_SHELL 配置，则可以识别 flash 下载前自动给开发板发送的命令进入烧录模式，就不需要手动按按键进入烧录模式了。