Build from Source Code

The IoT Yocto BSP is based on the Yocto project. The rity-demo-image image recipe is provided as part of this BSP contains a set of tools, applications, and configurations for evaluation of Genio devices. The demo image also demonstrates how to build a custom image on top of the IoT Yocto BSP.

Hint

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

Note

Please ensure you have setup the build environment on a Linux host computer before continuing with this guide. If you do not wish to build an image at this time, prebuilt demo images can be downloaded from the Download page.

Important

You need permission to access the https://gitlab.com/mediatek/aiot/nda to build fully functioned rity-demo-image. You can still build image using only publicly available packages through configuration, but the resulting images have only limited feature set.

To request for the permission, please contact your MediaTek sales.

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 refs/tags/rity-kirkstone-v24.1

The -b refs/tags/rity-kirkstone-v24.1 option specifies use of the rity-kirkstone-v24.1 release tag,

Note

Since this is a tag, it is frozen and repo sync always download the same recipes. Please note that since this is a static version, you will not receive important security and bug fixes or feature improvements.

There are other branches also listed in https://gitlab.com/mediatek/aiot/bsp/manifest/. For example the branch critical-fixes/rity-kirkstone-v24.0 contains critical patches based on the rity-kirkstone-v24.0 release tag.

Others development branches can break frequently. For example, rity/kirkstone is actively developed in IoT Yocto. The maintainers continuously update the recipes in this branch every week.

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=$PROJ_ROOT/src/meta-rity/meta/conf/
source src/poky/oe-init-build-env <build-directory>
export BUILD_DIR=`pwd`

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 with NDA Repository

By default the IoT Yocto will be built only with packages that are publicly available on Internet. To build IoT Yocto with MediaTek proprietary packages, access to private repositories under https://gitlab.com/mediatek/aiot/nda is required.

Note

For more information on applying for access permission to NDA repositories, please contact your local MediaTek support window.

To enable NDA build, please add following setting to the site.conf file after configuring the build environment:

echo 'NDA_BUILD = "1"' >> $BUILD_DIR/conf/site.conf

Note

This can be skipped if you don’t have NDA repository access or if you’d like to build a public configuration.

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.

Run the following commands to add these variables to your site.conf file:

$ echo 'DL_DIR = "${TOPDIR}/../downloads"' >> $BUILD_DIR/conf/site.conf
$ echo 'SSTATE_DIR = "${TOPDIR}/../sstate-cache"' >> $BUILD_DIR/conf/site.conf

Note

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

Hint

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

Typically the desired outcome from a build is an image that can be flashed to a device. This is what we specify for bitbake to build. By parsing the recipes it builds up a chain of dependencies that it works through to build the specified item. In this guide we will tell bitbake to build the rity-demo-image recipe.

Depending on which board you’d like to build for, assign the MACHINE config variable:

export MACHINE=genio-350-evk
bitbake rity-demo-image

Note

Please see Build for Other Boards for information on building with other boards.

Warning

As the bitbake command analyzes all the dependencies and fetches the required packages, building each down to the required cross-toolchain, 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.