Build a Reference Image with Yocto Project/OpenEmbedded

Introduction

This article guides you on how to build our Reference Images for Yocto Project using OpenEmbedded-Core (OE-Core). For a conceptual article about the relationship between Toradex' Embedded Linux offerings and the Yocto Project, refer to Yocto Project. If you wish to build Torizon OS, refer to Build Torizon OS With Yocto Project..

For further information about the Yocto project and use-cases beyond the scope of our articles, check out the Yocto Project Documentation and the Yocto Project Reference Manual.

The build process consists of the following steps:

1. Set up the shell environment you will use to build the image
2. Edit the build configuration files to configure the image to your liking
3. Build the image with the bitbake tool
4. Deploy the Image to Your Device

For information regarding our BSP versions and Yocto images, refer to our BSP Reference Documentation.

Prerequisites

• Follow the article: Host Machine Setup for Building with Yocto

A Yocto Project build requires intensive computing power and specific software packages, which are specified below.

Host Machine Requirements

A powerful host machine is highly recommended to build a Yocto Project image. We recommend:

• Disk Space: Around 120 GB.
• Memory:
  • Minimal: a 32-bit host with 4 GBytes.
  • Recommended: a 64-bit machine with at least 16 GBytes. Especially to build the the tdx-reference-multimedia-image.

If your host machine satisfies the hardware requirements above, make sure to set it up as follows:

• Use one of the Linux distributions supported by Yocto
• Install all the Yocto build dependencies

danger

Follow only the steps in the Yocto Mega Manual to install the build dependencies. Do not go any further into the environment setup.

Building on Virtual Machines, Containers and Cloud Builds

If you wish to build a Toradex Reference Image on a Virtual Machine (VM), Container, or a public cloud provider as AWS or Azure. Consider the following points:

• Virtual Machine (VMs): We do not recommend using a VM for building with Yocto, as it may introduce a high performance penalty.
• Container: Containers have a negligible performance penalty. Use bind-mounts or volumes to keep persistent data and reduce build time. Containers theoretically allow you to do a Yocto Project build from a Windows PC.
  • Toradex supports a container environment for building Torizon OS with the Yocto Project, read the article Build Torizon OS With Yocto for details. You may use it to build Reference Images, but note that this is not officially supported.
• Cloud: Cloud infrastructure providers have powerful machines that significantly reduce the build time for a Yocto Project. Similar to containers, you should plan how to store the output of a build.

Set Up the Environment Shell

Every time you open a new terminal, go to the OpenEmbedded directory you created in the Host Machine Setup article and source the export file:

$ . export

Edit the Build Configuration Files

The main configuration file a generic Yocto build is conf/local.conf. There are two main variables you need to modify for a basic build:

• MACHINE: specifies the target device for the image. Set this variable to the module type you are planning to build for.
• DISTRO: specifies the target distribution for the image. Set this variable to the distro you are planning to build.

To see the available machines and distros, refer to our BSP Reference Documentation. The default distro is tdx-xwayland, and it is already configured in the conf/local.conf file. You can set it to your distro of choice.

As an example, we will set the MACHINE to verdin-imx8mp. You should set it to your corresponding SoM.

local.conf

MACHINE ?= "verdin-imx8mp"

Building an image for NXP based SoMs may require you to read and accept the NXP^®/Freescale EULA available in layers/meta-freescale/EULA. You must state your acceptance by adding the following line to your local.conf file:

local.conf

ACCEPT_FSL_EULA = "1"

Build the Image

Decide what image you wish to build. The IMAGE defines which packages be built and installed into the final root file system. For more details on the IMAGE variable, refer to our BSP Reference Documentation.

Toradex provides two reference image variants, shown below. These images are primarily for BSP evaluation, and we do not recommend using them as-is. To build images for production, we recommend building on top of a Torizon OS Reference Image.

Image	Description
Reference Minimal Image tdx-reference-minimal-image	Minimal image without a graphical interface that just boots - Network manager: connman - Init system: systemd - Base command-line packages: packagegroup-base-tdx-cli. Included in packagegroup-tdx-cli.bb
Reference Multimedia Image tdx-reference-multimedia-image	Image for BSP verification with Qt and multimedia features - All that is included in the Reference Minimal Image - Graphics stack: Weston / Wayland + XWayland - Graphical User Interface framework: Qt - Camera and Video framework: V4L2 and Gstreamer - All command-line packages included in packagegroup-tdx-cli.bb - All graphical packages included in packagegroup-tdx-graphical.bb - All Qt5 packages included in packagegroup-tdx-qt5.bb

Build your desired image with the bitbake tool. Optionally use the -k flag so that the build keeps going with independent packages even after an error occurred. Keep in mind the following points when using bitbake:

• To use bitbake, you must first source the export file in your current shell, as instructed in Set Up the Environment Shell.
• You need to be in the directory build when you execute bitbake.
• The first build will typically take a large amount of time (possibly several hours).

$ bitbake -k tdx-reference-minimal-image

Bitbake automatically logs console output to timestamped files in build/tmp/log/cooker/$MACHINE/. If your build finishes without errors, advance to Deploy the Built Image to Your Device

Build with reduced RAM usage

Your computer may run out of RAM while compiling some packages (such as Qt, in the tdx-reference-multimedia-image).

To reduce RAM usage, set the environment variables PARALLEL_MAKE and BB_NUMBER_THREADS to a limited number of threads. make.

• PARALLEL_MAKE: Number of threads used by make
• BB_NUMBER_THREADS: Number of threads used by bitbake. Setting BB_NUMBER_THREADS also limits the number of download and configuration threads.

$ PARALLEL_MAKE="-j 4" BB_NUMBER_THREADS="6" bitbake <image>

warning

If a build fails due to lack of RAM, some files could be corrupted. Trying to build again may not solve this issue. In this situation:

1. Delete the corrupted package state
2. Delete all temporary files
3. Attempt to build the image again

Bitbake Commands

Below are some useful common bitbake commands. For further details, refer to the Yocto Bitbake Documentation.

• bitbake virtual/kernel: Build only the Linux kernel for your machine
• bitbake -e <recipe>: Output the environment variables and settings for your build. You can see all the settings with less or other text viewers, or use grep to see the value of a specific variable
• bitbake -c listtasks <recipe>: List all tasks for a given recipe

Deploy the Built Image to Your Device

After the bitbake tasks have finished, the output image will be located at build/deploy/images/${MACHINE}/.

Deploy the Tezi image generated in the build process to your borad using Toradex Easy Installer (Tezi). In the previous example, the generated image was the Verdin-iMX8MP_Reference-Minimal-Image-Tezi_6.0.0-devel-20221021202153+build.0.tar.

Debug a Failing Build

If your OpenEmbedded build fails, try to some of the steps below:

• Restart bitbake without deleting anything and see if it happens again.

• Clean the task which failed with one of bitbake's clean commands (clean, cleansstate and cleanall) and then restart the build. For example, if python-native fails:

  $ bitbake -c clean python-native
  $ bitbake <image>

• Check the layer which provides the recipe if a newer commit exists which addresses the problem.

Customize a Yocto Build

Our reference images are for evaluation purposes, and come with a minimal set of packages and configurations. Since BSP 3.0, our images don't include a package manager (due to the change from the Ångström distribution to Poky). To include additional packages for developing your application, either:

• Use Torizon OS and install additional packages inside containers, from Debian feeds.
• Customize your Yocto build to include your additional packages and configurations.

Customizing Yocto builds is typically done by adding your own meta-layers on top of the ones included by default in the reference images. For details on how to customize a Yocto Built image, refer to our Custom meta layers, recipes and images in Yocto Project (hello-world examples) article.

Production Programming

Since BSP 5.2, we have introduced an End User License Agreement (EULA) to our Reference Images. It prevents you from using the autoinstall feature of the Toradex Easy Installer, as suggested in the article Production Programming for Linux.

You must remove the license line from the image.json file included in the deployable tarball image resulting from the OpenEmbedded build to allow the autoinstall. It also means that you accept the EULA.

Read-Only Rootfs

Our base BSP layers and reference images do not support a read-only filesystem because there are features that won't work with a read-only system. In other words, the features of the read/write filesystem are used in several parts of the system, such as the case of the serial number in the hostname of the module. If the rootfs is read-only there is no way to write that modification at runtime.

For more information, refer to How to implement a Read-Only Rootfs (Linux).

Webinars

Webinar: Building Embedded Linux Images with the Yocto Project

Webinar: Criando Distribuições de Linux Embarcado com Yocto Project (Brazilian Portuguese)