Skip to main content
Version: Torizon OS 7.x.y

Build Torizon OS from Source With Yocto Project/OpenEmbedded

Introduction​

info

To use Torizon OS without customizing the base image, refer to the Quickstart Guide for instructions on how to install it on your Toradex System-on-Module (SoM).

Before building Torizon OS with Yocto Project/Open Embedded, refer to TorizonCore Builder Overview to understand how the TorizonCore Builder tool can be used to customize a Torizon OS image without working directly with Yocto. This tool, provided by Toradex, simplifies the customization process and may be a more efficient option for many use cases.

Torizon OS, formerly known as TorizonCore, is the base operating system on which Torizon is built. It is a minimal, Yocto Project–based embedded Linux image. While most users focus on application development using containers, there are scenarios where customizing the base image becomes necessary to meet specific requirements.

The Toradex manifest repository provides the Repo manifest and setup scripts required for the Torizon OS build system. It is intended for users who need to modify, extend, or port Torizon OS to new hardware platforms. The Torizon OS build system is based on the Yocto Project and uses the OpenEmbedded build system, the BitBake task executor, and various BSP application layers.

This article presents two methods to build Torizon OS:

  • Native Linux distribution: build Torizon OS directly on the host machine.
    • Not all distribution and Yocto Project version combinations are supported. If the host distribution is not supported, BitBake will display a warning when you run the first bitbake command. In such cases, the distribution may not be suitable for building Torizon OS, and using a Docker container should be considered.
  • Docker container: build Torizon OS within a containerized environment

This article complies with the Typographic Conventions for Torizon Documentation.

Common Prerequisites​

This section lists the common prerequisites required, regardless of the chosen build method. Read carefully the information below before proceeding with either build option.

Manifest Branch​

The manifest branch refers to the Git branch of the manifest repository used during setup. The branches in the Toradex Manifest Repository corresponding to Torizon OS versions are listed below:

Torizon OS versionBranch
7.x.yscarthgap-7.x.y
6.x.y¹kirkstone-6.x.y
5.x.y¹dunfell-5.x.y
0.0.0master
  1. Versions 6.3.0 and earlier were released with the TorizonCore name.
caution

The master branch is maintained to track changes in external layers. It is not recommended for productization, as builds may be unstable or broken for extended periods.

Manifest File​

The manifest file refers to the specific file in the manifest repository used during setup. The files available for Torizon OS images are:

  • torizon/default.xml
  • torizon/integration.xml
  • torizon/next.xml

Toradex recommends using the torizon/default.xml manifest file, as the other manifest files are used by Toradex to track upcoming changes and may not be stable.

info

The path to the manifest files changed in Torizon OS 7. Previously, the path was torizoncore/<manifest>.xml, and now it is torizon/<manifest>.xml.

Torizon OS Distro​

Within the Torizon Cloud ecosystem, formerly known as Torizon Platform, Toradex provides different versions of Torizon OS, which are referred to as "Distros" in the OpenEmbedded community. Each Distro corresponds to a specific kernel base and configuration.

The available Distros for Torizon OS are listed in the table below:

DistroKernel BaseKernel Config
torizonDownstream kernel from SoC vendor
Default for iMX95, iMX8, AM69/TDA4, AM62 and AM62P based modules		Default
Note: without Linux PREEMPT_RT patch
torizon-upstreamMainline kernel
Default for iMX6 and iMX7 based modules		Default
Note: without Linux PREEMPT_RT patch
torizon-rtDownstream kernel from SoC vendorFully preemptive
Note: real-time with Linux PREEMPT_RT patch
torizon-upstream-rtMainline kernelFully preemptive
Note: real-time with Linux PREEMPT_RT patch

Machine​

The supported MACHINE targets refer to the specific hardware platforms for which Torizon OS can be built. Each MACHINE corresponds to a particular Toradex SoM and its associated BSP layers.

The available MACHINE targets for Torizon OS are listed in the table below:

MACHINECorresponding Toradex SoM
aquila-imx95Aquila iMX95
Note: supported on 7.5.0 or newer Torizon OS releases
aquila-am69Aquila AM69/TDA4
verdin-imx95Verdin iMX95
Note: supported on 7.4.0 or newer Torizon OS releases
verdin-imx8mpVerdin iMX8M Plus
verdin-imx8mmVerdin iMX8M Mini
verdin-am62pVerdin AM62P
Note: supported on 7.3.0 or newer Torizon OS releases
verdin-am62Verdin AM62
toradex-smarc-imx95Toradex SMARC iMX95
Note: supported on 7.3.0 or newer Torizon OS releases
toradex-smarc-imx8mpToradex SMARC iMX8M Plus
Note: supported on 7.3.0 or newer Torizon OS releases
apalis-imx8Apalis iMX8
apalis-imx6Apalis iMX6
colibri-imx8xColibri iMX8X V1.0C or newer
colibri-imx7-emmcColibri iMX7D 1GB
Note: equipped with eMMC flash
colibri-imx6ull-emmcColibri iMX6ULL 1GB
Note: equipped with eMMC flash
colibri-imx6Colibri iMX6

Torizon OS Image​

The supported IMAGE targets refer to the specific Torizon OS images that can be built using the Yocto build system. Each IMAGE corresponds to a particular set of features and configurations for Torizon OS.

The available IMAGE targets for Torizon OS are listed in the table below:

IMAGEDescription
torizon-dockerDefault image provided by Toradex
  • Network Manager: NetworkManager
  • Service Manager: systemd
  • Container Engine: Docker
  • OTA Framework: OSTree and Uptane
torizon-minimalTorizon OS reference minimal image without a container engine
Note: all other Torizon OS features are included. Refer to Torizon OS Yocto Reference Minimal Image for more information
torizon-podmanExperimental image using Podman instead of Docker
Note: all Torizon OS features are included

Native Torizon OS Build Process​

Prerequisites​

For Secure Boot-enabled builds, refer to Secure Boot on Torizon OS documentation.

Setup Environment​

To setup the build environment and download the necessary metadata, follow the instructions below.

  1. Make sure that Git user name and e-mail are configured:

    $ git config --global user.email "email@email.com"
    $ git config --global user.name "Name"

  2. Download the repo tool:

    $ mkdir ~/bin
    $ PATH=~/bin:$PATH
    $ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
    $ chmod a+x ~/bin/repo

  3. Initialize the repo tool to download the manifest repository metadata. Make sure to specify the desired manifest branch and file:

    $ repo init -u git://git.toradex.com/toradex-manifest.git -b scarthgap-7.x.y -m torizon/default.xml
    tip

    For reproducible builds, Toradex recommends using tagged versions to ensure consistency. If reproducibility is critical for your use case, consider fetching all source code during setup and storing it locally.

  4. After a successful initialization, the repo tool will have created a .repo directory in the current working directory.

  5. Sync the metadata to download the source code:

    $ repo sync --no-clone-bundle

  6. Additionally, it might be necessary to specify proxy settings when downloading from behind a proxy:

    $ export HTTP_PROXY=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
    $ export HTTPS_PROXY=https://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
info

In some cases, Linux hosts may experience connectivity issues during downloads. Adjusting TCP/IP stack settings and disabling parallel downloads can help mitigate these issues. Root privileges are required to modify TCP settings:

$ sudo sysctl -w net.ipv4.tcp_window_scaling=0
$ repo sync -j1

Configure the Image Build​

The default DISTRO variable is automatically set based on the chosen MACHINE. To select a different DISTRO, specify it in the following command:

$ [DISTRO=<DISTRO>] [MACHINE=<MACHINE>] source setup-environment [BUILDDIR]

Build the Image​

To build the Torizon OS image, run the following command:

$ bitbake <IMAGE>

If an NXP MACHINE is selected and the ACCEPT_FSL_EULA="1" flag has not been previously added to the conf/local.conf file, a prompt will appear asking whether to review and accept NXP’s EULA. If the EULA is accepted, the flag is automatically added to conf/local.conf. If it is not accepted, the build fails until the EULA is accepted by adding ACCEPT_FSL_EULA="1" to conf/local.conf.

info

It is possible to accept the EULA automatically and skip the prompt by using the EULA variable in the setup-environment script. The following command will automatically accept NXP's EULA and add ACCEPT_FSL_EULA="1" to conf/local.conf:

$ [DISTRO=<DISTRO>] [MACHINE=<MACHINE>] EULA=1 source setup-environment [BUILDDIR]

Containerized Torizon OS Build Process​

Prerequisites​

Additionally, for Windows hosts, the following prerequisites are required:

For Secure Boot-enabled builds, refer to Secure Boot on Torizon OS documentation.

Build Configuration​

Create a working directory where the Yocto build will be stored:

$ mkdir ~/yocto-workdir

Build the Image​

If an NXP MACHINE is selected, a prompt to accept the NXP/Freescale EULA appears before the build begins. Acceptance of the EULA is required for certain packages and the build proceeds only after the EULA is accepted.

Run the following docker run command to start the build container. Make sure to update <machine> and <image> flags with the desired MACHINE and IMAGE for the build:

$ docker run --rm -it --name=crops -v ~/yocto-workdir:/workdir --workdir=/workdir -e MACHINE=<machine> -e IMAGE=<image> torizon/crops:scarthgap-7.x.y startup-tdx.sh

Container Arguments​

The docker run commands above include the minimum required arguments to start the build container. Additional arguments can be passed to further configure the build or change its behavior. These arguments are passed as environment variables using the -e flag in docker run:

  • -e MACHINE=<machine>: Specifies the target machine for the image build. This is required and does not have a default value.
  • -e DISTRO=<distro>: Specifies the Torizon DISTRO to be built. Defaults to either torizon or torizon-upstream based on the chosen MACHINE.
  • -e BRANCH=<branch>: Specifies the manifest repository branch. Defaults to scarthgap-7.x.y.
  • -e MANIFEST=<manifest>: Specifies the manifest file to be used. Defaults to torizon/default.xml.
  • -e IMAGE=<IMAGE>: Specifies the Yocto build recipe to be built. If not provided, the container will set up the build environment and start a shell without initiating a build.

Customization​

Enable Graphics Stack​

Torizon OS releases are headless by default, meaning that graphics-related features are removed at the distribution level. This configuration does not affect the default Torizon OS image and the experimental image using Podman, as the required userspace graphics stack is provided through containerized applications.

For the Torizon OS reference minimal image, graphics support can be enabled to allow the use of the Torizon ecosystem without the Docker engine or containers, while still providing a graphical user interface for embedded applications.

To enable the graphics stack, add the following line to local.conf to revert the removal of Distro features related to Wayland and OpenGL reintroducing graphics support to the built Torizon OS image:

local.conf
DISTRO_FEATURES_REMOVE:remove = " wayland opengl"

Custom Layers​

All custom layers in Torizon OS must be version-controlled using Git. This requirement is due to how layer revision information is included with OSTree, which is essential for the system update and over-the-air (OTA) process in Torizon OS.

For more details on how to manage custom layers in Yocto and their integration with Torizon OS, refer to Custom Meta Layers, Recipes and Images in Yocto Project (hello-world Examples) article.

Deploy to Torizon Cloud Using Yocto​

Prerequisites​

Java must be installed on the host system to deploy a custom image to Torizon Cloud:

$ sudo apt install openjdk-21-jre

Setup Environment​

Variables can be configured to automatically push a custom Torizon OS image to a Torizon Cloud account during the Yocto build process. Update the path to the credential.zip file and specify the target hardware in conf/local.conf:

local.conf
SOTA_PACKED_CREDENTIALS = "<path/to/credential.zip>"
SOTA_HARDWARE_ID = "verdin-imx8mp"
info

For more information about obtaining Torizon Cloud credentials, refer to How to Get Torizon Cloud credential.zip documentation.

After the build completes, the image is automatically pushed to the Torizon Cloud account and can be viewed in the Recent Packages tab.

Deploy to Torizon Cloud Using TorizonCore Builder​

To deploy a custom image to Torizon Cloud, ensure the following requirements must be met:

  • The OSTree and Aktualizr components remain unchanged in the Yocto build configuration, as they are responsible for system updates and the over-the-air (OTA) update mechanism in Torizon OS.

Build the image using Yocto and generate the output in the Toradex Easy Installer format. The build system stores the built image in the deploy/images/<machine> directory and includes the string Tezi in the file name. Then, use the TorizonCore Builder Tool to unpack the image and push it to Torizon Cloud.

Refer to the article Signing and Pushing Torizon OS and Application Packages to Torizon Cloud for more information about this process.

caution

When building a custom Torizon OS image, users are totally responsible for regularly building and deploying updates to ensure the security and functionality of their devices.

Send Feedback!