工程配置及创建

概述

本章介绍 SDK 配置的相关内容。

第一小节，将介绍如何 配置一个 SoC 工程。包括配置步骤、初始配置以及配置指令。

第二小节，将介绍 配置系统的组成。包括 Kconfig 以及 conf 文件。

第三小节，将介绍如何创建 外部工程, 用户可以通过此方式在 Realtek SDK 之外的目录中进行独立开发。

配置工程（menuconfig）

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

配置步骤

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 项目的配置初始值。

• prj.conf ：优先级高于 amebaxxx_gcc_project/default.conf 。有两种使用场景：

  • 当执行编译命令 build.py -a 指定一个 example 时，该路径下的 prj.conf （如有）将作为项目的初始配置生效；

  • 当编译 外部工程 时，该路径下的 prj.conf 将会生效。

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

• user.conf ：用户自定义的配置文件，可用于保存一些配置项组合。当用户执行 menuconfig.py -f 命令时，将代替 prj.conf （如有）作为初始配置生效。关于 conf 文件更详细的介绍，请参见 conf 文件介绍 。

备注

Kconfig 文件或 .conf 文件更新后（例如从远程仓库中拉取），继续使用已存在的 .config 进行编译可能会产生预期外的结果。因此， 每次编译前会自动检查初始配置的更新状态。

基于最新的初始配置文件生成 menuconfig/.config_default 文件，若该文件已存在且与本次生成的不一致，控制台将打印 diff 差异，由用户自行判断后选择：

• 如果用户判断此次更新可以忽略，那么可以按下 Enter，本次编译将继续使用当前的 .config 配置。

• 如果用户认为忽略此次更新内容可能会对编译结果造成影响，那么可以按下 Ctrl+C 退出。退出后，用户可以通过可视化配置或 menuconfig.py -f 的方式重新进行配置，亦或通过 menuconfig.py -c 、 build.py -p 等方式清理 menuconfig 文件夹后采用默认配置编译。

配置指令

menuconfig.py 脚本的常用指令如下表所示：

功能	命令	描述
帮助	menuconfig.py -h	列出支持的命令
手动配置	menuconfig.py	进入可视化配置界面
生成配置文件	menuconfig.py -s <name>.conf	将当前配置保存为 conf 文件
应用配置文件	menuconfig.py -f <name>.conf	通过 conf 文件配置
清理	menuconfig.py -c	清理当前配置和编译产物（如有）

备注

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

• 执行 menuconfig.py -f 命令会自动将 default.conf 加载为第一个输入文件； prj.conf 如果存在但未通过 -f 指定，将不会生效。

• 通过 -f 可导入多个 .conf 文件。若其中存在相同配置项，后者将覆盖前者，即最后一个文件中的配置项将会生效。

• menuconfig.py -c 将同时清理当前项目的配置 （ menuconfig 文件夹）及编译产物（如有，默认在 build 文件夹）。

配置系统

Kconfig 介绍

本节将介绍 Kconfig 的组织结构，以及一个配置项在 Kconfig 中是如何定义的。

组织结构

本项目的配置系统采用 Kconfig 组织，通过 Kconfig 的层级引用，将各个组件的配置结构化到 amebaxxx_gcc_project/Kconfig 中。关于 Kconfig 更详细的信息可参见： https://docs.kernel.org/kbuild/kconfig-language.html

用户执行 menuconfig.py 选中需要的配置项后，会保存为 .config 文件。经过脚本处理后，生成供 CMake 使用的 .config_xxx 文件，以及供 C 代码调用的头文件 platform_autoconf.h 。

定义 Kconfig 符号

定义一个 Kconfig 符号需要遵循下面格式：

config FOO
   bool "choose FOO"
   default n

上述 Kconfig 结构定义了一个名为 FOO 的 bool 类型符号，默认值为 n 。通过 menuconfig 进入可视化界面后，该符号将显示为：

[ ]  choose FOO

• "choose FOO" 为提示词，其将显示在可视化配置界面中，若删除 "choose FOO" ，那么可视化界面中将不会显示该配置项。除 bool 类型外，还可以定义 string, hex, int 等其他类型的配置项。

• default n 表示 no, 代表该项默认不会被选中， default n 可缺省。注意，通过 default 定义的默认值，只有在用户没有设置过该 config 项时才会生效。

• 如果同一个 config 中定义了多重 default 值，那么将以首次出现的有效 default 值为准。

• 上述符号在 .config 文件中将被解析为 CONFIG_FOO 。

conf 文件介绍

本节介绍 conf 文件的格式，以及涉及的几种 conf 文件。

conf 文件通过将用户需要设置的配置项写入其中，代替可视化界面的 menuconfig 方式。 和 menuconfig 交互式配置的方式类似，这种方式本质上也是选中/取消选中一些 Kconfig 文件中定义的项，只是用参数输入的方式代替了交互的的输入。

conf 文件格式

conf 文件由多行配置项组成，这些配置项遵循以下格式：

CONFIG_<name1>=<value>

CONFIG_<name2>=<value>

...

= 号左右不允许有空格。

default.conf

• 在 {SDK}/amebaxxx_gcc_project 目录下，提供了一个名为 default.conf 的配置集合文件，定义了编译本 SoC 项目的 初始配置 。

• 特殊地， menuconfig.py -f 隐含了 menuconfig.py -f default.conf 的规则，这样其它 conf 文件中只需编写 default.conf 的增量配置即可。若存在相同配置项，其它 conf 文件中的值将覆盖 default.conf 中的值。

• Kconfig 中的 default 值只有在未设定某个配置项时才会生效， 而 default.conf 文件相当于一系列默认的输入项，因此 default.conf 的优先级要高于 Kconfig 中的 default 值。

prj.conf

• prj.conf 存放在 example 下或用户创建的 外部工程路径 下，记录此 example 或外部工程需要的配置项。 用户可通过 menuconfig.py -f /.../prj.conf 对项目进行配置。当用户未通过可视化配置或指定其他 conf 文件时， prj.conf 会作为 初始配置 生效。

• prj.conf 的优先级高于 default.conf。

user.conf

• 用户自定义的 conf 文件。

• 生成：用户可以手动编写 .conf 文件；也可以先运行 menuconfig.py 利用可视化界面进行手动配置，退出后通过 menuconfig.py -s 命令将本次配置结果保存为 <name>.conf 文件。

  menuconfig.py -s <name>.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 将会生效。

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

备注

用户可通过 menuconfig.py -s 将当前配置保存为 conf 文件，之后利用 menuconfig.py -f 对保存的 .conf 文件进行加载。

创建外部工程

用户可以选择在 Realtek 提供的默认工程目录中进行开发和配置；也可以选择基于某个 example 单独创建外部工程，然后在该工程目录中进行开发和配置。

前文介绍了如何在 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：用于记录该工程的默认配置

• manifest.json5：用于配置固件的安全特性

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

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

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

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

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

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