Build Steps

This section briefly explains the steps required to download and build IoT Yocto.

Based on Yocto project, rity-demo-image is a image target. The image contains a set of tools, applications, and configurations for evaluation. The demo image also demonstrates how to build a custom image on top of the IoT Yocto BSP.

For general Yocto concept introductions, please refer to the Yocto Project Overview.

Project Root

Choose a directory as the root of your IoT Yocto project:

mkdir iot-yocto; cd iot-yocto
export PROJ_ROOT=`pwd`

In the following sections, we use $PROJ_ROOT as the root directory of your Yocto project.

Download the Recipes

Important

Please read and agree AIoT Software License Agreement before accessing or using IoT Yocto software. If you do not agree to the terms and conditions of AIoT Software License Agreement, you must not access or use the software.

IoT Yocto uses manifest files to store locations of Yocto recipes.

To download the IoT Yocto, please run the following repo command to initialize which version or branch of IoT Yocto you’d like to download:

repo init -u https://gitlab.com/mediatek/aiot/bsp/manifest.git -b <manifest-branch> -m <manifest-file>

The <manifest-branch> can be:

  • refs/tags/rity-v21.3 is a release tag for IoT Yocto v21.3. Since this is a tag, it is freezed and serves as a baseline for debugging and development. repo sync always download the same recipe.

  • rity/dunfell is a branch actively maintained currently in IoT Yocto. The maintainers continuously updates this branch between each release. The recipe content may get updated after a repo sync.

  • There are also other branches listed in https://gitlab.com/mediatek/aiot/bsp/manifest/. These are development branches that can break frequently.

The -m <manifest-file> selects different manifest files that provides additional Yocto recipe layers:

  • For v22.0.1 and after

    • If omitted, default.xml is used. The default manifest already includes Tensorflow-Lite and VP6 support recipes.

  • For v21.3 and before

    • If omitted, default.xml is used. This default manifest does not include Tensorflow-Lite and VP6 support recipes. If you don’t have to develop or deploy machine learning related features on the board, you can download codebase without machine learning support. It would save build time, disk space and reduce the image size.

    • -m rity-nn.xml is available to i350 and i500 boards to provide Tensorflow-Lite and VP6 support recipes.

Next, please run the following command to download all the Yocto layers of the IoT Yocto SDK into the $PROJ_ROOT/src/ directory:

repo sync

Unlike an Android codebase, this step only downloads the IoT Yocto layers and the recipes. The actual packages, such as the Linux kernel code, are not downloaded to your local disk yet.

Troubleshooting

If the repo tool reports manifest syntax error, you might want to install the latest repo tool manually with:

mkdir -p ~/.bin
PATH="${HOME}/.bin:${PATH}"
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
chmod a+rx ~/.bin/repo

Configure Build Environment

After the recipes are downloaded, use the following commands to initialize a Yocto project build environment:

export TEMPLATECONF=<template-configuration-files>
source src/poky/oe-init-build-env <build-directory>
export BUILD_DIR=`pwd`

The <template-configuration-files> provides default configurations. IoT Yocto provides several default configuration files:

  • For v21.3 and before

    • export TEMPLATECONF=$PROJ_ROOT/src/meta-rity/meta/conf/ provides default configuration, minus Tensorflow-Lite related recipes.

    • export TEMPLATECONF=$PROJ_ROOT/src/meta-nn-extra/conf/ provides additional configurations Tensorflow-Lite and VP6 support recipes. This meta layer is only available if you’ve fetched the recipes with rity-nn.xml manifest in the previous step.

  • For v22.0.1 and after

    • export TEMPLATECONF=$PROJ_ROOT/src/meta-rity/meta/conf/ provides default configuration and Tensorflow-Lite and VP6 support recipes.

The <build-directory> defaults to build if omitted. You can use a different name for the build directory, and even have multiple build directories. This step creates a Yocto build environment in the $PROJ_ROOT/<build-directory> directory. The oe-init-build-env will change current directory to the <build-directory> of your choice automatically. The Yocto project allows you to switch between multiple build environments, each build environment is a directory.

In the following sections, $BUILD_DIR is pointed to the build environment directory of your choice.

Initially, the build directory structure should look like this:

$BUILD_DIR
         └── conf
                 ├── bblayers.conf
                 ├── local.conf
                 └── templateconf.cfg

When building the project image, all the source code, intermediate files and the output binaries are located under this $BUILD_DIR.

Note

oe-init-build-env not only creates a build directory, it also sets up several environment variables required by subsequent bitbake commands. If you re-start the console session, make sure you run source src/poky/oe-init-build-env <build-directory> again to properly set the environment variables. The script is smart enough to keep the content of the build directory untouched if you’ve made some modifications.

Setup Without NDA Repo

Default the IoT Yocto will build with full feature set. During the build process, the nda repo will be accessed. If you do not have access right to aceess https://gitlab.com/mediatek/aiot/nda, you will get error when fetching nda repo.

For this situation, you can build an image with limited feature set by apply following commands after Download the Recipes.

# Cherry-pick solution to build image with limited feature set
# cherry-pick for meta-rity
cd iot-yocto/src/meta-rity
git cherry-pick e00bc87c53bb41314e9c790a497e8b75d0802ede
git cherry-pick 19e42d3a9e31f862b6896a910e3c1f5689ed5895

# cherry-pick for meta-nn
cd iot-yocto/src/meta-nn
git cherry-pick 97db3c1d00668f0f294e72729f6a080d6d6b2ebf

# cherry-pick for meta-mediatek-bsp
cd iot-yocto/src/meta-mediatek-bsp
git cherry-pick 66f2d7acc457015dc8e855f78400bcdf4ce88a02

After apply above commands, please delete ${BUILD_DIR}/conf/ if you have configured build environment before. Then repeat Configure Build Environment to re-initialize a Yocto project build environment

Setup DL_DIR and SSTATE_DIR

If you have already built IoT Yocto before, you might notice there are two folders downloads and sstate-cache created during the build process. These two folders serve for different purposes:

  • downloads folder is a central place for storing source tarballs downloaded during the build process. The build process searches in this folder for finding sources first before downloading from the Internet.

  • sstate-cache is a directory stores shared state during the build process. IoT Yocto uses the shared state to quickly reconstruct built artifacts if things haven’t changed since the last build.

By default the downloads and sstate-cache are located under $BUILD_DIR. We recommend to setup these folders to be outside of $BUILD_DIR for several reasons:

  • In default setup, after removing $BUILD_DIR, it usually takes several hours to rebuild IoT Yocto, because those caching folders are also deleted when deleting $BUILD_DIR. By separating caching folders from $BUILD_DIR, if something goes wrong, it’s easy to just delete $BUILD_DIR and rebuild. Since downloads and sstate-cache are in different places, it takes less time to reconstruct built artifacts.

  • It is not recommended to reuse the same $BUILD_DIR after changing build configurations (e.g. changing MACHINE, updating DISTRO_FEATURES, etc.). Sometimes reusing $BUILD_DIR may cause subtle issues that are hard to diagnose. But users tend to take a shortcut because it saves hours of build time. After separating caching folders from $BUILD_DIR, removing $BUILD_DIR becomes less expensive, which encourages users to reconstruct $BUILD_DIR more often instead of reusing the same folder when changing configurations.

To do so, prepare a site.conf file with the following content:

DL_DIR = "${TOPDIR}/../downloads"
SSTATE_DIR = "${TOPDIR}/../sstate-cache"

You might want to add your site.conf into the conf directory in the $BUILD_DIR, or modify the settings in local.conf to assign your own DL_DIR and other cache or mirror repositories.

Note

The variable ${TOPDIR} is a Bitbake variable used in IoT Yocto, which indicates the build folder (that is, $BUILD_DIR).

To learn more about DL_DIR, please refer to Yocto Reference Manual. For details about the content in the conf directory, please refer to Yocto Project Concepts.

Fetch and Build the Packages

The previous steps does not actually fetch source code of packages in IoT Yocto. Instead, we need to use bitbake command to execute recipes. Each recipe defines:

  • How and where to fetch the package source code

  • What patches have to be applied to the source code

  • What are the dependencies and toolchain required by the package

  • How to setup the build environment of the package

In IoT Yocto, the information are encapsulated in the rity-demo-image recipe. To build the image, use the following command:

DISTRO=rity-demo MACHINE=<machine> bitbake rity-demo-image

The <machine> parameter can be the following values:

  • genio-1200-evk

  • genio-700-evk

  • genio-350-evk

The bitbake command then analyzes all the dependencies and fetches the required packages. As a result, this step can take a very long time.

Build Result and Images

If everything works as expected, a summary log would be printed:

NOTE: Tasks Summary: Attempted 7180 tasks of which 11 didn't need to be rerun and all succeeded.

The exact task number may vary, but if all succeeded, your image is located in:

$BUILD_DIR/tmp/deploy/images/<machine>

If something goes wrong, you can look for the error logs by search for these patterns in the log:

ERROR: Logfile of failure stored in: '<path-to-logfile>'

For details and additional parameters of the bitbake command, please refer to the Yocto project’s bitbake manual.

Partial Build

During development, you might want to build a single package instead of the entire image. To do so, use the following commands:

$ bitbake <recipe-name>

The <recipe-name> is the name of the BitBake recipe of the package you want to build. For example, the Linux kernel is defined in these recipe .bb files:

  • meta-mediatek-bsp/recipes-kernel/linux/linux-mtk/recipes-kernel/linux/linux-mtk_5.4.bb

  • meta-mediatek-bsp/recipes-kernel/linux/linux-mtk/recipes-kernel/linux/linux-mtk_5.10.bb

  • meta-mediatek-bsp/recipes-kernel/linux/linux-mtk/recipes-kernel/linux/linux-mtk_5.15.bb

The name of the package is therefore linux_mtk. To only rebuild the kernel instead of the entire rity-demo-image, use the following command:

$ bitbake linux-mtk

Please note that this only rebuilds the kernel image (fitImage), but not the image of the entire system (*.wic.img). To update the kernel image, use Yocto virtual provider:

$ bitbake virtual/kernel

Similarly, if you only want to rebuild bootloader BL2 image (bl2.img), you can use:

$ bitbake trusted-firmware-a

Similarly, if you only want to rebuild bootloader U-boot (BL33) image, you can use the commands below and repackage the bootloader BL31/BL32/BL33 image fip.bin:

$ bitbake virtual/bootloader
$ bitbake trusted-firmware-a

BSP Source Code Modification

Kernel

Please note that modifying source code directly under the build/tmp/work directory causes a lot of problems. To modify the source code of kernel, please refer to Kernel Development and use devtool to modify package source code.

Trusted-Firmware-A (BL2/BL31)

For BL2/BL31 source modification, the BL2/BL31 is implemented and based on Trusted-firmware-A(TF-A). If you would like to modify the source code of TF-A, please use devtool tool and modify the source under build/workspace folder.

  1. Run devtool modify trusted-firmware-a. This will fetch the sources for the recipe and unpack them to a workspace/sources/trusted-firmware-a/ directory and initialise it as a git repository if it isn’t already one.

$ devtool modify trusted-firmware-a

  1. Make the changes you want to make to the source.

  2. Run a build to test your changes - you can partial build trusted-firmware-a.

$ bitbake trusted-firmware-a

U-Boot (BL33)

For BL33 source modification, the BL33 is implemented and based on U-Boot. If you would like to modify the source code of U-Boot, please use devtool tool and modify the source under build/workspace folder.

  1. Run devtool modify u-boot. This will fetch the sources for the recipe and unpack them to a workspace/sources/u-boot/ directory and initialise it as a git repository if it isn’t already one.

$ devtool modify u-boot

  1. Make the changes you want to make to the source.

  2. Run a build to test your changes - you can partial build u-boot.

$ bitbake u-boot

Clean Output and Intermediate Files

The Bitbake system used by Yocto project manages various caches and intermediate files when building recipes.

In some cases, you might want to remove the intermediate files and rebuild images or packages from scratch. To remove the output of a package recipe, use the command:

$ bitbake -c clean <recipe-name>

For example, to remove kernel output and intermediate files,

$ bitbake -c clean virtual/kernel

If you suspect there are corrupted recipe task states, you can clean the sstate cache by:

$ bitbake -c cleansstate virtual/kernel

To learn more about various clean tasks, refer to Yocto manual.