IC: RTL8721Dx RTL8720E RTL8726E RTL8713E RTL8730E RTL8721F

概述

本章介绍如何搭建 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 提供的软件合集包，并在编译前运行脚本自动配置环境变量。这种方式不会影响用户原先的软件环境，并且可以避免因软件版本带来的兼容性问题。

LinuxWindows

1. 下载压缩包并解压至 /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 路径下。如需更改默认路径，请参考 更改工具链安装路径。

2. 预安装 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 解决问题。

3. 安装依赖库

   sudo apt install libssl-dev libncurses5
   

4. 进入 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 命令设置环境变量。

安装工具链

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

• Linux：/opt/rtk-toolchain

• Windows：C:\rtk-toolchain

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

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

   build.py -D USE_ALIYUN_URL=True
   

3. 如果需要修改工具链的安装路径，请在系统中创建环境变量 RTK_TOOLCHAIN_DIR，并将其赋值为修改后的安装路径。

   LinuxWindows

   1. 打开 ~/.bashrc 文件，在其末尾添加：

      export RTK_TOOLCHAIN_DIR="/path/to/your/toolchain/dir"
      

   2. 运行以下命令使环境变量立即生效：

      source ~/.bashrc
      

备注

• 如果已有下载好的工具链压缩包，可以将压缩包移动到安装路径后，再次执行 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

SDK 路径

配置及编译 SDK 需要在 SoC 的 project 路径下进行，对应路径下均放置了供配置及编译的 Python 脚本。

SoC 对应的 GCC project 路径如下所示：

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

{SDK}/amebadplus_gcc_project

备注

将 {SDK} 替换为用户自己的 SDK 路径。

配置 SDK（menuconfig）

用户可通过项目对应的 menuconfig.py 脚本配置 SDK。

配置步骤

1. 进入 {SDK}/amebaxxx_gcc_project 目录。

2. 在 Windows 的命令提示符窗口或 Linux 终端下运行 menuconfig.py 命令。

   正确运行命令后，终端会显示如下可视化界面，用户可通过：

   • 方向键选择需设置的配置

   • 空格 或 回车 键进行选中/取消选中

   • ESC 键返回上一层

   • Q 键退出

   --------MENUCONFIG FOR General---------
   CONFIG BOOT OPTION  --->
   CONFIG TrustZone  --->
   CONFIG Mass Production  --->
   CONFIG Linux  --->
   CONFIG AT CMD  --->
   CONFIG RTK Assert Level  --->
   CONFIG VFS  --->
   CONFIG OS  --->
   CONFIG OTA OPTION  --->
   CONFIG USB  --->
   CONFIG APPLICATION  --->
   -----Connectivity Config-----
   CONFIG WHC INTF  --->
   CONFIG WIFI  --->
   CONFIG BT  --->
   CONFIG LWIP  --->
   CONFIG SSL  --->
   CONFIG WPAN  --->
   CONFIG COEX  --->
   ---------Test Config---------
   Verification and Test  --->
   --------Build Config---------
   Build Option  --->
   -----end of MENUCONFIG FOR General-----
   MENUCONFIG FOR KM0 CONFIG  --->
   MENUCONFIG FOR KM4 CONFIG  --->
   MENUCONFIG FOR CA32 CONFIG  --->
   ----- DO NOT ENTER IN THIS BUTTON ------
   MENUCONFIG FOR Private  --->
   

3. 退出 menuconfig 菜单后，UI 会提示用户是否保存配置。若选择保存，配置将被存放到当前目录下的 menuconfig 文件夹中。

   文件夹内一般包含以下几项：

   • .config 文件：保存着用户选择的配置项。

   • .config_{MCU} 文件：分配到每个 MCU 的最终配置文件，如 .config_km4, .config_km0，这些文件是基于 .config 文件二次处理的产物。

   • project_{MCU}/platform_autoconf.h：根据最终配置文件生成的头文件，供 C/C++ 源文件引用。

备注

• 每次配置完成的结果会保存到 menuconfig/.config 文件，且此文件会在下一次手动配置时被加载。

• 打开 menuconfig 进行可视化配置时，可以看到前一次的配置记录，即这种方式的配置是 有记忆的。

初始配置

项目的配置从 menuconfig/.config 解析得来。但当项目不存在 menuconfig/.config 文件，即当前为空配置时，将自动使用初始配置。

初始配置说明：

• amebaxxx_gcc_project/default.conf 中记录了该型号 SoC 默认需要打开的配置项，此文件将作为该 SoC 项目的配置初始值。

• 特别地，当通过命令 build.py -a 指定一个 example 或在 工程路径 进行编译时，该路径下的 prj.conf （如有）也将作为项目的初始配置生效，且优先级高于 amebaxxx_gcc_project 路径下的 default.conf。

• default.conf 和 prj.conf 中未定义的项，将采用 Kconfig 中的 default 值作为初始值。

配置流程如下所示：

其他配置命令

1. 清理配置

以下命令会清理当前项目的配置 （ menuconfig 文件夹）及编译产物（如有，默认在 build 文件夹）。

menuconfig.py -c

2. 通过 conf 文件配置

用户可以将一些配置项组合保存成 .conf 后缀的配置集合文件，代替可视化界面中的手动选择。这样只需要一条指令就可以完成项目的配置。关于 conf 文件更详细的介绍，请参见 conf 文件介绍

menuconfig.py -f <name1>.conf <name2>.conf ...

• <name1>.conf，<name2>.conf 为用户命名的配置集合文件。

• 运行 menuconfig.py -f 命令时，可以指定一个或多个 .conf 文件。如果多个 .conf 文件中存在相同配置项， <name2>.conf 的优先级将高于 <name1>.conf。

例如，如果 <name1>.conf 中定义了 CONFIG_BT_MENU=y， <name2>.conf 中定义了 CONFIG_BT_MENU=n，那么最终 CONFIG_BT_MENU=n 将会生效。

备注

• 在 -f 执行之前，会先自动删除 menuconfig 文件夹，这样通过 -f 配置后的结果不会受到前一次 .config 文件的影响，即这种 -f 的配置方式是 无记忆的。

• 执行此命令会自动将 default.conf 加载为第一个输入文件。

3. 生成 conf 文件

如果用户不希望手动编写 .conf 文件，可以先运行 menuconfig.py 利用可视化界面进行手动配置，退出后通过 menuconfig.py -s 命令将本次配置结果保存为 <name>.conf 文件。之后，用户可以利用 menuconfig.py -f <name>.conf 对保存的 .conf 文件进行加载。

menuconfig.py -s <name>.conf

编译代码

Realtek 提供 build.py 脚本来简化项目的编译，常用指令如下表所示：

功能	命令	描述
帮助	build.py -h	列出支持的命令
编译	build.py	增量编译工程
纯净编译	build.py -p	移除所有产物并编译工程
指定示例	build.py -a <APP>	编译名为 APP 的示例
指定目标	build.py -g target	编译指定的 target
清理	build.py -c	清理编译产物
调试	build.py -debug	进入调试模式

帮助指令

如果您是第一次使用 build.py 脚本，可以通过以下命令了解此脚本的用法：

build.py -h

通过 -h 或 --help 选项，所有支持的命令将会被列出。

build.py -h
usage: build.py [-h] [-a APP] [-c] [-p]
               [-g {flashloader,imgtool_flashloader,gen_imgtool_floader}]
               [-gdb] [-debug] [-D DEFINED [DEFINED ...]] [--new NEW [NEW ...]]

options:
-h, --help            show this help message and exit
-a APP, --app APP     application path
-c, --clean           clean
-p, --pristine        pristine build
-g {flashloader,imgtool_flashloader,gen_imgtool_floader}, --target {flashloader,imgtool_flashloader,gen_imgtool_floader}
                        custom target
-gdb, --gdb           gdb
-debug, --debug       debug
-D DEFINED [DEFINED ...], --Defined DEFINED [DEFINED ...]
                        user defined variables
--new NEW [NEW ...]   build.py --new-prj <target_dir> [-a <APP>]

纯净编译

纯净编译意味着此次编译环境没有之前残留产物的影响，所有之前编译的产物及配置项都会在此次编译之前被移除。 -p 选项和 --pristine 选项等价。

build.py -p

备注

• 纯净编译同时会移除 menuconfig 文件夹，之前的配置内容也将被丢弃，本次编译将会使用 初始配置。

• 如果仅需清理编译产物但保留之前的配置选项，请使用 build.py -c 命令进行清理。

增量编译

如果不带任何参数，项目将会进行增量编译，增量编译和全量编译相比会大大节省时间。

build.py

编译指定示例

${SDK}/component/example 目录下提供了丰富的应用示例。如果您想要编译其中一个示例，可以通过 -a 或 --app 将应用名称或应用路径传递给 build.py。

build.py -a <APP>

例如，需要编译 ${SDK}/component/example/network_protocol/http_client 示例，可以输入以下命令：

build.py -a ${SDK}/component/example/network_protocol/http_client
//or
build.py -a http_client

如果不通过 -a 传入应用名称或路径，将编译默认应用（仅使能无线连接）。

备注

• example 目录下提供了名为 prj.conf 的文件，当用户未配置过项目时， build.py -a <APP> 将会组合 amebaxxx_gcc_project/default.conf 与 example/.../<APP>/prj.conf 以使用 初始配置。

• 如果当前 SoC 目录下已有 menuconfig 文件夹，可先通过 menuconfig.py -f /.../prj.conf 配置或手动重新配置，然后使用 build.py -a <APP> 编译，也可以直接使用 build.py -a <APP> -p 删除之前的配置项。

编译指定目标

默认情况下，所有必要的目标将被一起编译。

• 可通过 -g 或 --target 选项单独编译特定的目标

• 可通过 -h 选项查看所有可用目标

build.py -g <TARGET>

例如，要重新生成 imgtool flashloader，需输入以下命令：

build.py -g gen_imgtool_floader

项目清理

-c 和 --clean 都可以清理当前项目的产物及中间文件，但 .config 配置文件会被保留。

build.py -c

传递 CMake 的 Cache 变量

CMake 可以通过 -D 选项设置 Cache 变量的初始值。为了继承这一功能， build.py 也同样支持 -D 选项。CMake 预定义的值和用户自定义的值都可以放在 -D 后面。

build.py -D CACHE_VAL1=VALUE1 CACHE_VAL2=VALUE2 …

更多关于本项目 Cache 变量的描述，请参考 ${SDK}/amebaxxx_gcc_project 目录下的 CMakeLists.txt 文件。

备注

CMake 原生的 -D 与 build.py 的 -D 的不同之处如下：

• CMake 要求每个变量定义前都要有 -D 前缀，例如： -DCACHE_VAL1=VALUE1 -DCACHE_VAL2=VALUE2。

• build.py 要求所有变量跟随在一个单独的 -D 后面，并在 -D 和变量之间留有空格。例如： -D CACHE_VAL1=VALUE1 CACHE_VAL2=VALUE2。

固件文件（Image）

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

• 编译完成后，固件将被拷贝到 \amebadplus_gcc_project 路径下，用户也可以在如下文件夹看到固件：

  • \amebadplus_gcc_project\project_km0\asdk\image

  • \amebadplus_gcc_project\project_km4\asdk\image

• CMake 生成的中间文件将会被存放在 build 文件夹。

• 如果生成失败, 尝试运行 build.py -c 后重新编译。

KM4 & KM0 工程编译日志

KM4 & KM0 固件生成

备注

如果想要获取 .map 文件进行调试， 请在如下路径中查找：

• \amebadplus_gcc_project\project_km0\asdk\image

• \amebadplus_gcc_project\project_km4\asdk\image

创建外部工程

前文介绍了如何在 amebaxxx_gcc_project 目录下进行配置与编译，这种模式下用户将在 Realtek 提供的 SDK 中开发自己的项目。但在一些场景下，用户希望创建独立于 Realtek SDK 的工程目录，方便独立维护或更新，或方便多团队开发。下文介绍基于外部工程的开发模式。

1. 创建命令

进入到 SoC 对应的 GCC project 路径下，运行：

cd {SDK}/amebaxxx_gcc_project

build.py --new <project_dir> [-a <APP_NAME>]

将以 example 中的 APP_NAME 为模板，在 project_dir 路径下建立新的工程。例如：

build.py --new ~/my_project -a http_client

工程路径下包含：

• ameba.bat ameba.sh：用户可以通过这些脚本设置环境变量。

• menuconfig.py build.py：用于配置及编译工程

• CMakeLists.txt：编译此新建工程的入口文件

• Kconfig：在此可添加用户自己的配置项

• <APP_NAME> 文件夹：指定模板的文件将被拷贝至相应文件夹

• prj.conf：用于记录该工程的默认配置

2. 在创建的工程目录下设置环境

工程目录下的 ameba.bat 和 ameba.sh 建立了对 Realtek SDK 根目录下同名脚本的引用，用户可通过任意位置的脚本设置环境。

3. 在创建的工程目录下配置

使用方法同 配置 SDK 中的命令。配置生成的 menuconfig 文件夹将会生成在此工程目录下。

4. 在创建的工程目录下编译

使用方法同 编译 SDK 中的命令。编译生成的 build 文件夹将会生成在此工程目录下。

固件下载

我们提供了 ImageTool 专门用于固件的下载，请参考 Image Tool。