6. Building a Yocto image#
The Yocto Project is an open-source project that helps building Linux-based distributions, mainly for embededded products. CHERRY provides a minimal BSP layer to allow building Yocto images for the company’s modules. An extended layer is also provided for a less bare experience, see instructions in Section 6.3 Extended meta layer. Upon request, access can be given to a more featureful “demonstration” layer which provides hardware and software validation scripts as well as demo applications.
This user guide does not aim at getting the user familiar with development with the Yocto Project but rather help them setup their build environment to create a basic Yocto image that can be used on one of CHERRY modules.
The Yocto project provides an open source Linux build framework, which allows to create customized build environments for embedded systems.
Yocto consists of the following parts:
The Yocto Project tools,
Reference Linux distribution (Poky),
Build system (co-maintained with OpenEmbedded),
There exists extensive documentation for the Yocto Project and BitBake.
The Yocto Project releases a new version twice a year and some versions are maintained for a longer time when marked as LTS (Long-Term Support). Such is the case of Kirkstone (4.0), supported until at least April 2024. CHERRY highly recommend to use LTS versions and update to a newer version once its support has reached end-of-life, to benefit from bug fixes, security fixes, miscellaneous improvements and additional features.
6.1. Prerequisites#
While the Yocto Project supports many different build systems, CHERRY currently only tests building on Debian 11 (Bullseye).
The required packages for Debian are listed in the documentation and can be installed with the following command:
sudo apt-get install -y --no-install-recommends gawk wget git diffstat unzip \
texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-venv \
python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 \
libegl1-mesa libsdl1.2-dev xterm python3-subunit mesa-common-dev zstd \
liblz4-tool file
6.2. BSP meta layer#
The Yocto Project BSP meta layer can be found at https://git.embedded.cherry.de/yocto-layers/meta-theobroma-systems-bsp.git/.
It contains the minimal configuration and recipe append files (bbappend) necessary to build a minimal working image. It is meant to be a base upon which to build and thus many tools are purposefully missing.
6.2.1. Initial setup#
Clone the BSP meta layer and its dependencies from a new directory called
yocto:
mkdir yocto
cd yocto || return
git clone https://git.embedded.cherry.de/yocto-layers/meta-theobroma-systems-bsp.git \
-b kirkstone
git clone https://git.yoctoproject.org/poky -b kirkstone-4.0.10
git clone https://git.yoctoproject.org/meta-arm -b yocto-4.0.2
git clone https://git.yoctoproject.org/meta-rockchip -b kirkstone
git clone https://git.openembedded.org/meta-openembedded -b kirkstone
The following directory layout should be observed:
$ tree -L 1 yocto/
yocto
├── meta-arm
├── meta-openembedded
├── meta-rockchip
├── meta-theobroma-systems-bsp
└── poky
Note
It is essential that the Yocto layers are checked out on a branch that supports the same release as the others, otherwise there may be some unexpected issues. With the aforementioned instructions, the layers have been checked out to a branch supporting the Yocto Project Kirkstone (4.0) release.
One can check if a branch supports a release by looking into conf/layer.conf
and look for the LAYERSERIES_COMPAT_* variable. All layers should have the
same one in common, here “kirkstone”.
6.2.2. Initializing build environment#
Once the layers have been properly cloned in their appropriate branch, the build environment needs to be initialized. This can be done by running the following command:
# shellcheck disable=SC3046,SC1091
source poky/oe-init-build-env build
This will initialize the build environment by making the bitbake build tool
available in the current shell and creating a build directory where
temporary and final build artifacts will be stored.
The following directory layout should be observed:
$ tree -L 1 yocto/
yocto
├── build
├── meta-arm
├── meta-openembedded
├── meta-rockchip
├── meta-theobroma-systems-bsp
└── poky
The first time the command is run, it’ll create a new build directory called
build and add the appropriate configuration files. On the later runs, if the
directory still exists, the command will only configure the terminal environment
and not change anything in the build directory. This makes it perfectly safe to
run the command multiple times, from different terminals for example.
Note
Once the current terminal is closed or a new one is opened, this command should be re-executed to be able to interact again with the Yocto Project tools.
The Yocto Project then needs to be configured to include layers to find new recipes or configuration files, which is essential to build new pieces of software or compile for a specific hardware target system.
This can be done with the bitbake-layers tool:
bitbake-layers add-layer ../meta-arm/meta-arm-toolchain
bitbake-layers add-layer ../meta-arm/meta-arm
bitbake-layers add-layer ../meta-rockchip
bitbake-layers add-layer ../meta-openembedded/meta-oe
bitbake-layers add-layer ../meta-openembedded/meta-python
bitbake-layers add-layer ../meta-theobroma-systems-bsp
6.2.3. Building a minimal image#
To build a bootable artifact, BitBake will be called with the specified machine and target image:
MACHINE="jaguar" bitbake core-image-minimal
Note
Technically speaking, the MACHINE variable could be set in
build/conf/local.conf file once and for all. If possible, CHERRY
recommends passing the variable explicitly in the command directly
as this makes it more visible to the user and also allows to easily build
for multiple machines without modifying a file in-between.
The build process can take several hours depending on the capabilities of the build machine and the user’s Internet connection.
Note
If the Bitbake process needs to be stopped for any reason, a SIGINT
(Ctrl + c) signal can be sent once. Bitbake will gracefully close
down upon reception of this signal. This graceful shutdown can take a lot of
time depending on the tasks that are currently being executed. It is
highly recommended to not send this signal more than once, failing to do
so may hinder next Bitbake commands.
The artifacts can be found after some time in
build/tmp/deploy/images/jaguar/ directory. A flashable image is one whose
extension is .wic, e.g.
core-image-minimal-jaguar-20221021134027.rootfs.wic.
Make the resulting image available for later steps:
export SDCARD_IMG="$PWD/build/tmp/deploy/images/jaguar/core-image-minimal-jaguar.wic"
6.2.4. Building with kas#
kas is a setup tool for Bitbake-based projects, such as the Yocto Project, which aims to replace the commands listed above for a simpler, more automated, setup and creation of images.
CHERRY provides a kas configuration file kas-theobroma.yml
in the BSP meta layer for convenience.
kas can be installed on the build machine with the following command:
sudo apt-get install -y --no-install-recommends kas
Note
It is also available as a Python package and installable with:
python3 -m venv venv
# shellcheck disable=SC3046,SC1091
source venv/bin/activate
python3 -m pip install kas==4.0
The Section 6.2.1 Initial setup and Section 6.2.2 Initializing build environment can then be replaced by the following two commands:
mkdir yocto
cd yocto || return
git clone https://git.embedded.cherry.de/yocto-layers/meta-theobroma-systems-bsp.git \
-b kirkstone
kas checkout meta-theobroma-systems-bsp/kas-theobroma.yml
The Section 6.2.3 Building a minimal image can now be replaced with:
KAS_MACHINE="jaguar" kas build meta-theobroma-systems-bsp/kas-theobroma.yml
Note
kas is also available in an OCI container form on
GitHub container registry.
It is still recommended to install kas through pip but then use its
kas-container wrapper script to start the container properly. E.g. to replace
the last command to build an image with kas one can call this instead:
python3 -m venv venv
# shellcheck disable=SC3046,SC1091
source venv/bin/activate
python3 -m pip install kas==4.0
export KAS_IMAGE_VERSION="4.0"
export KAS_MACHINE="jaguar"
kas-container build meta-theobroma-systems-bsp/kas-theobroma.yml
6.3. Extended meta layer#
The Yocto Project extended layer can be found at https://git.embedded.cherry.de/yocto-layers/meta-theobroma-systems-extended.git/.
In addition to the minimal features, this layer includes the network manager, and many more features will be added soon.
6.3.1. Initial setup#
Clone the Extended layer and its dependencies from a new directory called
yocto:
mkdir yocto
cd yocto || return
git clone https://git.embedded.cherry.de/yocto-layers/meta-theobroma-systems-extended.git \
-b kirkstone
git clone https://git.embedded.cherry.de/yocto-layers/meta-theobroma-systems-bsp.git \
-b kirkstone
git clone https://git.yoctoproject.org/poky -b kirkstone-4.0.10
git clone https://git.yoctoproject.org/meta-arm -b yocto-4.0.2
git clone https://git.yoctoproject.org/meta-rockchip -b kirkstone
git clone https://git.openembedded.org/meta-openembedded -b kirkstone
The following directory layout should be observed:
$ tree -L 1 yocto/
yocto
├── meta-arm
├── meta-openembedded
├── meta-rockchip
├── meta-theobroma-systems-bsp
├── meta-theobroma-systems-extended
└── poky
Note
It is essential that the Yocto layers are checked out on a branch that supports the same release as the others, otherwise there may be some unexpected issues. With the aforementioned instructions, the layers have been checked out to a branch supporting the Yocto Project Kirkstone (4.0) release.
One can check if a branch supports a release by looking into conf/layer.conf
and look for the LAYERSERIES_COMPAT_* variable. All layers should have the
same one in common, here “kirkstone”.
6.3.2. Initializing build environment#
Once the layers have been properly cloned in their appropriate branch, the build environment needs to be initialized. This can be done by running the following command:
# shellcheck disable=SC3046,SC1091
source poky/oe-init-build-env build
This will initialize the build environment by making the bitbake build tool
available in the current shell and creating a build directory where
temporary and final build artifacts will be stored.
The following directory layout should be observed:
$ tree -L 1 yocto/
yocto
├── build
├── meta-arm
├── meta-openembedded
├── meta-rockchip
├── meta-theobroma-systems-bsp
├── meta-theobroma-systems-extended
└── poky
The first time the command is run, it’ll create a new build directory called
build and add the appropriate configuration files. On the later runs, if the
directory still exists, the command will only configure the terminal environment
and not change anything in the build directory. This makes it perfectly safe to
run the command multiple times, from different terminals for example.
Note
Once the current terminal is closed or a new one is opened, this command should be re-executed to be able to interact again with the Yocto Project tools.
The Yocto Project then needs to be configured to include layers to find new recipes or configuration files, which is essential to build new pieces of software or compile for a specific hardware target system.
This can be done with the bitbake-layers tool:
bitbake-layers add-layer ../meta-arm/meta-arm-toolchain
bitbake-layers add-layer ../meta-arm/meta-arm
bitbake-layers add-layer ../meta-rockchip
bitbake-layers add-layer ../meta-openembedded/meta-oe
bitbake-layers add-layer ../meta-openembedded/meta-python
bitbake-layers add-layer ../meta-openembedded/meta-networking
bitbake-layers add-layer ../meta-theobroma-systems-bsp
bitbake-layers add-layer ../meta-theobroma-systems-extended
6.3.3. Building an image#
To build a bootable artifact, BitBake will be called with the specified machine and target image:
MACHINE="jaguar" bitbake theobroma-extended-image
Note
Technically speaking, the MACHINE variable could be set in
build/conf/local.conf file once and for all. If possible, CHERRY
recommends passing the variable explicitly in the command directly
as this makes it more visible to the user and also allows to easily build
for multiple machines without modifying a file in-between.
The build process can take several hours depending on the capabilities of the build machine and the user’s Internet connection.
Note
If the Bitbake process needs to be stopped for any reason, a SIGINT
(Ctrl + c) signal can be sent once. Bitbake will gracefully close
down upon reception of this signal. This graceful shutdown can take a lot of
time depending on the tasks that are currently being executed. It is
highly recommended to not send this signal more than once, failing to do
so may hinder next Bitbake commands.
The artifacts can be found after some time in
build/tmp/deploy/images/jaguar/ directory. A flashable image is one whose
extension is .wic, e.g.
theobroma-extended-image-jaguar-20221021134027.rootfs.wic.
Make the resulting image available for later steps:
export SDCARD_IMG="$PWD/build/tmp/deploy/images/jaguar/theobroma-extended-image-jaguar.wic"
6.3.4. Building with kas#
kas is a setup tool for Bitbake-based projects, such as the Yocto Project, which aims to replace the commands listed above for a simpler, more automated, setup and creation of images.
CHERRY provides a kas configuration file kas-theobroma.yml
in the BSP meta layer for convenience.
kas can be installed on the build machine with the following command:
sudo apt-get install -y --no-install-recommends kas
Note
It is also available as a Python package and installable with:
python3 -m venv venv
# shellcheck disable=SC3046,SC1091
source venv/bin/activate
python3 -m pip install kas==4.0
The Section 6.3.1 Initial setup and Section 6.3.2 Initializing build environment can then be replaced by the following two commands:
mkdir yocto
cd yocto || return
git clone https://git.embedded.cherry.de/yocto-layers/meta-theobroma-systems-extended.git \
-b kirkstone
kas checkout meta-theobroma-systems-extended/kas-theobroma.yml
The Section 6.3.3 Building an image can now be replaced with:
KAS_MACHINE="jaguar" kas build meta-theobroma-systems-extended/kas-theobroma.yml
Note
kas is also available in an OCI container form on
GitHub container registry.
It is still recommended to install kas through pip but then use its
kas-container wrapper script to start the container properly. E.g. to replace
the last command to build an image with kas one can call this instead:
python3 -m venv venv
# shellcheck disable=SC3046,SC1091
source venv/bin/activate
python3 -m pip install kas==4.0
export KAS_IMAGE_VERSION="4.0"
export KAS_MACHINE="jaguar"
kas-container build meta-theobroma-systems-extended/kas-theobroma.yml