CLI 集成开发工具

概述

本章介绍基于 CLI 环境的集成开发工具 ameba.py，以及如何使用该工具进行开发。

ameba.py 封装了常用的开发功能。通过该工具，用户可以方便地进行工程创建、配置、编译等操作。

其中封装的工具主要有：

tools/scripts/build.py ，提供编译功能，通过 ameba.py build 命令调用。用户可通过 ameba.py build -h 命令查询支持的参数。

tools/scripts/menuconfig.py ，提供配置功能，通过 ameba.py menuconfig 命令调用。用户可通过 ameba.py menuconfig -h 命令查询支持的参数。

tools/scripts/jlink_script/jlink.py ，提供 J-Link 调试功能，通过 ameba.py jlink 命令调用。用户可通过 ameba.py jlink -h 命令查询支持的参数。

ameba.py 支持对 SDK 中的所有 Ameba 系列芯片进行开发。在开始首次编译之前，必须先选定一个芯片，例如 RTLxxx。

如果在当前目录下已选择过 SOC，一般无需再次选择。后续的配置、编译等操作均基于该芯片进行。

开始编译或配置后，会在当前目录下自动生成 build_RTLxxx 目录，其中 RTLxxx 为当前选定的芯片型号。该目录下存放编译产物（固件文件和 build 文件夹）和配置产物（ menuconfig 文件夹）。

下面将介绍以下几个部分的内容：

使用 ameba.py 的开发流程

如何创建外部工程

ameba.py 的常用指令

开发流程

Step 1: 环境配置

在终端中执行以下命令：

source {sdk}/env.sh

{sdk}\env.bat

环境配置成功后，终端将输出以下信息：

PIP CHECK... All packages are installed correctly!
================================================================================
|  Setup complete. The Ameba SDK is now ready for use.
|  Go to the project root directory and run ameba.py
|  Usage:      ameba.py [COMMAND] [ARGS]
|  Build:      ameba.py build
|  Select SoC: ameba.py soc
|  Help:       ameba.py help
================================================================================

备注

将 {sdk} 替换为用户自己的 Ameba SDK 路径。
每次新打开终端都要重新执行以上命令配置环境。因为如果将该脚本放到 bashrc 中，会在每个终端中都配置 Ameba 环境，影响用户原有的软件环境，因此建议用户在每个终端中进行手动配置。

Step 2: 选择一个 SOC

进入目标目录（例如， /home/demo/test ），完成环境配置后，执行以下命令：

ameba.py soc [RTLxxx]

选择后该 SOC 会被记录在当前目录下的 soc_info.json 文件中。

例如，指定 RTL8713E：

$ ameba.py soc RTL8713E
Current SoC is set to: RTL8713E. Saved as /home/demo/test/soc_info.json

若不指定芯片，则会进入交互式选择界面。例如：

$ ameba.py soc

Available SoCs:
----------------------------------------

1. RTL8713E
2. RTL8720E
3. RTL8721Dx
4. RTL8721F
5. RTL8726E
6. RTL8730E

----------------------------------------
Enter an SoC number (1-6): 1
Current SoC is set to: RTL8713E. Saved as /home/demo/test/soc_info.json

备注

可使用 ameba.py list 查询所有可用芯片。
选择后可使用 ameba.py show 查看当前芯片。
支持在同一目录下编译多个芯片，每个芯片都有一个专属的 build_RTLxxx 文件夹存放编译、配置产物。但由于一个目录下的 soc_info.json 文件只能保存一个芯片的信息，请在编译前通过 ameba.py show 确认当前芯片型号，以防结果不符合预期。

Step 3: 配置

如果用户无需修改配置，可跳过此步骤，将使用 Ameba SDK 默认配置进行编译。

如需修改当前 SOC 的配置，可使用以下命令：

ameba.py menuconfig [args]

[args] 部分可选，表示传递给底层 tools/scripts/menuconfig.py 脚本的参数，可通过 ameba.py menuconfig -h 命令查看支持的参数，或查阅配置工程（menuconfig）一节。

配置内容会保存在 build_RTLxxx/menuconfig 目录中。

例如，在 /home/demo/test 目录下执行 ameba.py menuconfig ，进入图形化界面修改配置。

由于在前面的步骤中，已当前芯片设置为 RTL8713E ，此处将对 RTL8713E 进行配置:

配置成功保存后，终端将输出以下信息：

$ ameba.py menuconfig
Start to menuconfig RTL8713E ...
Loaded configuration '/home/demo/test/build_RTL8713E/menuconfig/.config'
Configuration saved to '/home/demo/test/build_RTL8713E/menuconfig/.config'

将在当前目录下生成 build_RTL8713E/menuconfig 目录，如图所示：

../../_images/amebapy_menuconfig_dir.png

Step 4: 编译

使用以下命令编译当前 SOC：

ameba.py build [args]

[args] 部分可选，表示传递给底层 tools/scripts/build.py 脚本的参数，可通过 ameba.py build -h 命令查看支持的参数，或查阅编译指令一节。

编译的中间产物位于 build_RTLxxx/build 目录，最终固件位于 build_RTLxxx 目录。

例如，在 /home/demo/test 目录下执行 ameba.py build 。由于在前面的步骤中，已当前芯片设置为 RTL8713E ，此处将对 RTL8713E 进行编译。

编译成功后将输出以下信息：

$ ameba.py build
Start to build RTL8713E ...
ccache found
Default toolchain path: /opt/rtk-toolchain
Toolchain Version Matched
......
-- Configuring done (1.6s)
-- Generating done (0.3s)
-- Build files have been written to: /home/demo/test/build_RTL8713E/build
[1216/1219] Linking C executable project_km4/make/image1/target_loader_km4.axf
[1219/1219] cd /home/demo/test/build_RTL8713E/build && .../component/soc/amebalite/project/postbuild.cmake
========== Image app generate start ==========
========== Image manipulating end ==========
Build done

编译完成后， build_RTL8713E 目录如下图所示：

备注

如需编译其他 SOC，可再次执行 ameba.py soc，然后通过 build 指令进行编译。也可以直接通过 build 指令编译指定的 SOC，例如 ameba.py build RTL8721Dx 。
如需清理某个 SOC 的产物，可使用 clean 或 cleansoc 命令，具体用法请参考常用指令。

创建外部工程

在一些场景下，用户希望创建独立于 Realtek SDK 的工程目录，方便独立维护或更新，或方便基于同一个 SOC 开发不同的项目。

用户可以基于某个应用示例单独创建一个外部工程，然后在该工程目录中进行开发。

这样，用户可以对自己的应用程序的功能和配置进行扩展，独立维护该工程目录，方便更新 Realtek SDK 中的文件内容。

下文介绍基于外部工程的开发方式。

创建外部工程

首先，按照开发流程的步骤 1 ，配置好 Ameba SDK 环境。

在终端中执行以下命令：

ameba.py new-project path/to/target [-a app_name]

备注

将 path/to/target 替换为新工程的路径，必须要在 SDK 外部，可以是相对路径或绝对路径。
-a app_name 可选，表示要在新工程中包含的应用示例名称，若不加该参数，将会创建一个空的应用示例。

创建完成后，在指定的路径下会生成一个新的外部工程目录。该目录中包含：

env.bat env.sh：用户可以通过这些脚本配置环境；也可以按照前述的步骤 1 中的方式配置环境。

<app_name> 文件夹：指定的应用示例目录中的文件将被拷贝至相应文件夹；若不指定，将创建 app_example 文件夹，包含一个空的应用示例

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

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

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

例如，在当前目录（ /home/demo/test ）的同一层级创建一个名为 my_project 的外部工程，并包含 http_client 应用示例。创建成功后，将输出以下信息：

$ ameba.py new-project ../my_project -a http_client
A new project based on app 'http_client' is created in '/home/demo/my_project'.

在外部工程目录中进行开发

进入外部工程目录： cd path/to/target
配置环境： source env.sh （在 Windows 系统中执行 env.bat ）；也可以按照前述的步骤 1 中的方式配置环境。
使用 ameba.py 进行编译、配置等操作，可参考开发流程的步骤 2 ~ 步骤 4 。

常用指令

ameba.py 用法如下：

ameba.py <command> [args]

其中， <command> 为具体的指令， [args] 为可选参数。

常用指令如下表所示：

功能	命令	描述
帮助	`ameba.py help`	列出支持的命令
查询可用芯片	`ameba.py list`	列出所有可用的芯片型号
选择芯片	`ameba.py soc [RTLxxx]`	设置当前芯片为 RTLxxx
显示当前芯片	`ameba.py show`	显示当前的芯片型号
编译	`ameba.py build`	编译当前选择的芯片
配置	`ameba.py menuconfig`	配置当前选择的芯片
清理编译产物	`ameba.py clean`	清理当前芯片的编译产物
清理芯片	`ameba.py cleansoc`	清理当前芯片的所有产物
创建外部工程	`ameba.py new-project`	在SDK之外创建一个新的工程
J-Link 调试工具	`ameba.py jlink`	通过 J-Link 调试当前芯片

小技巧

在 Linux 系统中，支持按 TAB 键启动自动补全命令。此外， soc 命令支持自动补全芯片型号。

帮助指令

如果您是第一次使用 ameba.py 脚本，可以通过以下命令了解此脚本的用法，所有支持的命令将会被列出：

ameba.py help

$ ameba.py help
Ameba CLI Development Tool
Usage: ameba.py [COMMAND] [ARGS]

Available commands:
build        : Build on the current or given SoC. e.g. ameba.py build [soc_name] [args]
clean        : Clean build products of the given or current SoC. e.g. ameba.py clean [soc_name]
cleansoc     : Clean all products of the given or current SoC. e.g. ameba.py cleansoc [soc_name]
flash        : Firmware flashing.
help         : Display this help information.
jlink        : J-Link tool.
list         : List all available SoC names.
menuconfig   : Run menuconfig tool for the current or given SoC. e.g. ameba.py menuconfig [soc_name] [args]
monitor      : Serial monitor.
new-project  : Create a new empty project in the given path. e.g. ameba.py new-project path/to/your/project [-a app_name]
show         : Show the current selected SoC name.
soc          : Select an SoC to build. If no SoC name given, enter the interactive selection.

Run 'ameba.py <COMMAND> -h' for more information of command build/menuconfig/flash/monitor/jlink.

查询可用芯片

ameba.py 脚本被调用时，会自动检测当前 SDK 中的全部可用芯片型号。

使用 list 命令可以罗列出所有可用芯片型号：

ameba.py list

选择芯片

使用 soc 命令选择当前要编译的芯片型号，可以加上芯片型号名称，例如：

ameba.py soc RTL8721Dx

选择的 SOC 信息会被保存在当前目录下的 soc_info.json 文件中，后续的编译、配置等操作均基于当前选择的芯片型号进行。一次只能有一个芯片型号被选择。

要更换芯片型号，可以再次使用 ameba.py soc [RTLxxx] 命令选择新的芯片型号。

小技巧

如果不指定芯片型号， soc 命令会进入交互式选择模式，用户可以从列表中选择所需的芯片型号。
要查看当前选择的芯片型号，可以使用 ameba.py show 命令。

显示当前芯片

使用 show 命令查看当前的芯片型号：

ameba.py show

这个命令会查询 soc_info.json 文件，从中读取当前选择的芯片型号。

编译

使用 build 命令编译当前芯片：

ameba.py build [args]

其中， [args] 部分可选，表示传递给底层 tools/scripts/build.py 脚本的参数，支持的参数请参考编译指令一节，也可通过 ameba.py build -h 命令查看。

例如，要进行纯净编译，可以使用以下命令：

ameba.py build -p

编译产物位于 build_RTLxxx 目录下，其中 RTLxxx 为编译的芯片型号。其中， build_RTLxxx/build 目录下存放编译生成的中间文件，最终固件（image 文件）位于 build_RTLxxx 目录下。

小技巧

若当前未选择芯片型号， ameba.py build 命令会提示用户进行交互式选择，然后开始编译。
若要编译特定芯片型号，可以在 build 命令后直接指定芯片型号，例如 ameba.py build RTL8721Dx 。通过这种方式选择的芯片会被更新到 soc_info.json 文件中。

配置

使用 menuconfig 命令对当前芯片进行配置：

ameba.py menuconfig [args]

其中， [args] 部分可选，表示传递给底层 tools/scripts/menuconfig.py 脚本的参数，支持的参数可以参考配置工程（menuconfig）一节，或者通过 ameba.py menuconfig -h 命令查看。

配置产物位于 build_RTLxxx/menuconfig 目录下，其中 RTLxxx 为配置的芯片型号。

小技巧

若当前未选择芯片型号， ameba.py menuconfig 命令会提示用户进行交互式选择，然后进入配置界面。
若要配置特定芯片型号，可以在 menuconfig 命令后直接指定芯片型号，例如 ameba.py menuconfig RTL8721Dx 。通过这种方式选择的芯片会被更新到 soc_info.json 文件中。

调试

使用 jlink 命令对当前芯片进行调试：

ameba.py jlink [args]

其中， [args] 部分可选，表示传递给底层 tools/scripts/jlink_script/jlink.py 脚本的参数，支持的参数可以通过 ameba.py jlink -h 命令查看。

该指令将根据当前芯片的架构自动生成 J-Link 脚本，位于 build_RTLxxx/jlink_script 目录下，其中 RTLxxx 为配置的芯片型号。生成脚本后，会自动调用相应的 J-Link 程序进行连接。

清理编译产物

使用 clean 命令清理当前芯片的编译产物：

ameba.py clean

build_RTLxxx/build 文件夹和固件（ build_RTLxxx/*.bin ）将被删除，但 build_RTLxxx/menuconfig 目录和 soc_info.json 文件会被保留。

可以指定芯片型号，例如， ameba.py clean RTL8721Dx 将会清理 RTL8721Dx 编译产物。

清理芯片

使用 cleansoc 命令清理当前芯片的所有产物：

ameba.py cleansoc

将会清理编译产物和配置产物， build_RTLxxx 文件夹以及 soc_info.json 文件都被删除。下次编译时需要重新选择芯片型号。

可以指定芯片型号，例如， ameba.py cleansoc RTL8721Dx 将会清理 RTL8721Dx 的所有产物。

新建外部工程

使用 new-project 命令在 SDK 之外创建一个新的外部工程：

ameba.py new-project path/to/your/project [-a app_name]

其中， path/to/your/project 为新工程的路径，必须要在 SDK 外部，可以是相对路径或绝对路径； -a app_name 可选，表示要在新工程中包含的应用示例名称，若不加该参数，将会创建一个空的应用示例。

例如，要创建一个名为 my_project 的新工程，并包含 http_client 示例，可以在 SDK 根目录执行以下命令：

ameba.py new-project ../my_project -a http_client

该命令将在 SDK 根目录的上一级目录创建 my_project 文件夹，并将 http_client 示例代码复制到该文件夹中。

创建完成后，进入新工程目录，可直接使用 ameba.py 进行开发。通过 ameba.py soc 选择芯片型号，然后通过 ameba.py menuconfig 和 ameba.py build 进行配置和编译。

如需在新终端中直接打开该外部工程目录，需先执行以下命令以配置开发环境：

source env.sh

然后即可通过 ameba.py 进行开发。