nuwa 编译和烧录

概述

本章介绍如何搭建 GCC 编译环境，包括 Windows 平台和 Linux 平台。

Windows 平台：以 Windows 10 64-bit 为例
Linux 平台：以 Ubuntu 22.04 x86_64 为例

环境准备

准备 GCC 编译环境

GCC 编译环境包括 CMake 编译环境、Python 环境，以及其他一些工具软件，如下表所示：

软件	版本
cmake	3.20 及以上
ninja	1.10.1 及以上
make	3.82 及以上
ccache	4.5.1 及以上
Python3	3.10 及以上
wget	推荐最新版
7zip	推荐最新版

用户可以下载 Realtek 提供的软件合集包，并在编译前运行脚本自动配置环境变量。这种方式不会影响用户原先的软件环境，并且可以避免因软件版本带来的兼容性问题。

下载压缩包并解压至 /opt/rtk-toolchain 文件夹下

mkdir /opt/rtk-toolchain
cd /opt/rtk-toolchain
wget https://github.com/Ameba-AIoT/ameba-toolchain/releases/download/prebuilts-v1.0.3/prebuilts-linux-1.0.3.tar.gz
tar -xzf prebuilts-linux-1.0.3.tar.gz

如果下载遇到问题，可尝试使用 aliyun 地址：

wget https://rs-wn.oss-cn-shanghai.aliyuncs.com/prebuilts-linux-1.0.3.tar.gz

备注

压缩包需要解压到默认的 /opt/rtk-toolchain 路径下。如需更改默认路径，请参考更改工具链安装路径。

预安装 Python（Linux 下不提供 Python 的免安装版本）
```
sudo apt install python3 python3-pip python3-venv
```
备注
- 运行 python --version 检查 Python 版本，建议大于 3.10。
- 如果主机中存在多个 Python 版本，可以使用命令 update-alternatives --install /usr/bin/python python /usr/bin/python3.x 1 选择特定 Python 版本，x 代表期望的版本号。
- 如果报错 command 'python' not found，尝试运行 ln -s /usr/bin/python3 /usr/bin/python 解决问题。

安装依赖库

sudo apt install libssl-dev libncurses5

进入 SDK 根目录，运行 ameba.sh 脚本，自动配置环境变量。

source ameba.sh

PIP CHECK... All packages are installed correctly!
========================================================
|  First choose IC platform: cd [IC]_gcc_project
|  Configure command: menuconfig.py
|  Build command: build.py
========================================================
(.venv)

备注

每次重启终端后，都需要执行 source ameba.sh 命令设置环境变量。

在 C 盘下新建 C:\rtk-toolchain 文件夹
下载压缩包并解压至 C:\rtk-toolchain 文件夹下
下载路径

中国大陆地区用户建议使用 aliyun 链接。
从 GitHub 下载

从 aliyun 下载
备注

压缩包需要解压到默认的 C:\rtk-toolchain 路径下。如需更改安装路径，请参考更改工具链安装路径。

进入 SDK 根目录，双击运行根目录下的 ameba.bat，将自动配置环境变量，后续请继续在此窗口运行命令。

PIP CHECK... All packages are installed correctly!
========================================================
|  First choose IC platform: cd [IC]_gcc_project
|  Configure command: menuconfig.py
|  Build command: build.py
========================================================
(.venv) C:\sdk>

备注

如果用户想在 Windows 下使用 Git Bash 或 MSYS2 等类 Unix 的命令行环境，请在 SDK 根目录下打开新终端后运行 source ameba.sh。

小技巧

此方式依赖 Python 虚拟环境。若出现 Python 系统错误，如提示找不到 dll 动态库等，请尝试手动删除 SDK 根目录下的 .venv 文件夹并运行 ameba.bat 脚本，将自动重新安装 Python 虚拟环境。

安装工具链 (TODO)

默认情况下，工具链会在第一次编译项目时被自动安装到默认路径下：

Linux：/opt/rtk-toolchain
Windows：C:\rtk-toolchain

在进行项目编译前，我们会检查工具链是否被正确安装以及版本是否匹配。如果弹出报错信息，请根据报错信息修复问题并尝试重新编译。

工具链压缩包默认托管在 GitHub 上，首次编译时会尝试从 GitHub 下载工具链压缩包。如果下载遇到问题，请确认主机是否可以正确访问 GitHub。如果无法正常访问，请通过以下命令更换下载源：
```
build.py -D USE_ALIYUN_URL=True
```

如果需要修改工具链的安装路径，请在系统中创建环境变量 RTK_TOOLCHAIN_DIR，并将其赋值为修改后的安装路径。
1. 打开 ~/.bashrc 文件，在其末尾添加：
  export RTK_TOOLCHAIN_DIR="/path/to/your/toolchain/dir"
2. 运行以下命令使环境变量立即生效：
  source ~/.bashrc
1. 在设置 > 高级系统设置 > 环境变量选项中新建变量：
  - 变量名为 RTK_TOOLCHAIN_DIR
  - 变量值为用户希望的安装路径
2. 重启终端使环境变量生效。

备注

如果已有下载好的工具链压缩包，可以将压缩包移动到安装路径后，再次执行 build.py。
如果报错 Download Failed, 请检查网络连接。如果问题仍然存在，请参考步骤 2。
如果报错 Create Toolchain Dir Failed. May Not Have Permission，请尝试手动创建文件夹。如果问题仍然存在，请参考步骤 3 修改默认安装路径。
如果报错 Unzip Failed，可能是压缩包损坏，请手动删除安装路径下的压缩包后，再次执行 build.py。

完成上述安装步骤后，在 rtk-toolchain 路径下将有以下文件：

|--- prebuilts-[win/linux]-1.x.x
|
|--- asdk-10.3.1-xxxx
|
|--- vsdk-10.3.1-xxxx

安装 Python 依赖项

运行以下命令创建 python 虚拟环境并安装 Python 依赖项：

./nuwa.py setup

创建应用程序

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

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

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

<app>
├── CMakeLists.txt     编译入口脚本，链接 Zephyr 编译系统
├── app.overlay        应用专属 Kconfig 配置文件
├── prj.conf           设备树覆盖文件（可选）
├── 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 -d <device> -a <application> [-p]

参数说明：

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

示例：编译 Hello World 示例

./nuwa.py build -d 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 或者 ./nuwa.py build -p

打开 Menu Config 菜单

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

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

build 目录内容

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

NUWA_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 下载的固件将放置在 NUWA_SDK/images 目录下。然后使用 ImageTool 进行固件下载，工具位于： NUWA_SDK/tools/ameba/ImageTool 目录下，请参考 Image Tool 使用指南进行烧录。