CLI Build and Download

Introduction

This chapter illustrates how to build Realtek’s SDK under CLI environment, then download the image to the chip.

Build Flow

Configuring and building can be performed in any directory. The ameba.py build [args] command is used for building. Please refer to the Common Commands section for more details on this command.

The building steps are as follows:

  1. Set up the environment: source path/to/your/sdk/env.sh (on Windows, execute env.bat)

  2. Select the SoC model: ameba.py soc

  3. Execute the build command: ameba.py build to start compiling.

  4. Intermediate files generated by CMake will be stored in the build_RTLxxx/build directory.

  5. Upon completion, the firmware will be copied to the build_RTLxxx directory under the current directory, where RTLxxx represents the SoC model.

For more usage of the build command, please refer to Build Command.

The final build product is the image files, which users need to download into the chip.

Build Commands

ameba.py build command wraps the underlying script tools/scripts/build.py. Common commands are listed below:

Function

Command

Description

Help

ameba.py build -h

List supported commands

Build

ameba.py build

Incremental build of project

Pristine Build

ameba.py build -p

Remove all products and build

Specify Example

ameba.py build -a <APP>

Build example named ‘APP’

Specify Target

ameba.py build -g target

Build specified target

Cleanup

ameba.py build -c

Clean compilation products

Debug

ameba.py build -debug

Enter debug mode

Help Command

If you are using the build command for the first time, use the following command to understand its usage.

ameba.py build -h

With the -h or --help option, all supported commands will be listed.

Pristine Build

Pristine build means that there are no previous residual products affecting this build. All previously products and configurations will be removed before this build. The -p option is equivalent to the --pristine option.

ameba.py build -p

Note

  • A clean build will also remove the menuconfig folder, and any previous configurations will be discarded. This build process will use initial configurations.

  • If you only need to clean up the build artifacts but want to retain the previous configurations, use the ameba.py build -c command for cleanup.

Incremental Build

Without any arguments, the project will undergo incremental build, which significantly saves time compared to full build.

ameba.py build

Build Specified Example

Some application examples are provided under the ${SDK}/component/example directory. To build one of these examples, pass the application name or path to ameba.py build using the -a or --app options.

ameba.py build -a <APP>

For instance, to build the ${SDK}/component/example/network_protocol/http_client example, you can input the following command:

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

If you do not pass an app name or path through -a, it will build a default application, which only enables wireless connection.

Note

  • The examples provide file named prj.conf. When you have not configured the project, running ameba.py build -a <APP> will combine component/soc/amebaxxx/project/default.conf with example/.../<APP>/prj.conf to use initial configuration.

  • If menuconfig folder already exists in the current project, you can run menuconfig.py -f /.../prj.conf first or reconfigure manually, then build it using ameba.py build -a <APP>. Alternatively, you can directly use ameba.py build -a <APP> -p to delete previous configuration files.

Build Specified Target

By default, all necessary targets will be built together. Specific targets can be built individually using the -g or --target options. Use the -h option to view all available targets.

ameba.py build -g <TARGET>

For example, to regenerate imgtool flashloader, enter the following command:

ameba.py build -g gen_imgtool_floader

Project Cleanup

Both -c and --clean clean up the current project’s products and intermediate files. But .config files will be retained.

ameba.py build -c

Pass CMake Cache Variables

CMake cache variables’ initial values can be set using the -D option. To inherit this functionality, ameba.py build also supports the -D option. Predefined values by CMake and user-defined values can both follow after -D.

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

Note

  • Native CMake command requires each variable definition to have a -D prefix, e.g., -DCACHE_VAL1=VALUE1 -DCACHE_VAL2=VALUE2

  • However, ameba.py build requires all variables to follow a single -D with spaces, e.g., -D CACHE_VAL1=VALUE1 CACHE_VAL2=VALUE2

Download Image

We provide ImageTool specifically for firmware download. Please refer to Image Tool .