A Step-by-Step Guide to Getting Started with Embedded Yocto (Based on the i.MX Platform)

1. Introduction to the Yocto Project

The Yocto Project is an open-source collaboration project focused on the development of embedded Linux operating systems, enabling developers to build customized Linux images for various hardware platforms. For NXP i.MX series development boards, Yocto provides dedicated BSP (Board Support Package), integrating the kernel, U-Boot, drivers, and application components through a layered architecture, supporting multiple families of SoCs (System-on-Chips) such as i.MX 6/7/8/9.

This tutorial focuses on setting up the Yocto environment, building images, deploying, and customizing operations on the i.MX platform, suitable for embedded development engineers to get started quickly.

1. Core Concepts

Before understanding the build process, it is essential to clarify the core components of Yocto:

Poky: The reference distribution of Yocto, containing the build system (BitBake), basic metadata (meta-poky), and open-source layers (meta-openembedded), among other core contents.
BitBake: The build engine of Yocto, responsible for parsing recipes, managing dependencies, and executing build tasks.
Layer: The organizational unit of metadata, used to separate hardware, software, and customization configurations (e.g., meta-yocto-bsp corresponds to hardware BSP, meta-custom corresponds to custom configurations).
Recipe: A .bb file that defines the build rules for a single software package (source address, compilation parameters, dependencies, installation steps).
Machine Configuration: A conf/machine/<machine>.conf file that defines the parameters of the hardware platform (architecture, kernel, drivers, partitions, etc.).
Distro Configuration: A conf/distro/<distro>.conf file that defines global system features (package manager, initialization system, compiler version, etc.).
Build Directory: The directory where temporary files, compiled products, and final images generated during the build process are stored (usually build/).

2. Prerequisites

(1) Hardware Requirements

Host System: Recommended Ubuntu 22.04 or higher (other Linux distributions may require dependency adaptation)
Disk Space: Minimum 50GB (basic build), recommended 120GB (full backend compilation), machine learning component builds require over 250GB
Network Environment: Stable network (for downloading source code, dependency packages, and image resources)

(2) Software Dependency Installation

Execute the following command in the Ubuntu host to install the necessary dependency packages for Yocto build:

sudo apt-get install build-essential chrpath cpio debianutils
 diffstat file gawk gcc git iputils-ping libacl1 liblz4-tool locales
 python3 python3-git python3-jinja2 python3-pexpect python3-pip 
 python3-subunit socat texinfo unzip wget xz-utils zstd efitools

Note: Ensure that the system’s default grep version has not been replaced, as this may lead to build failures.

(3) Repo Tool Installation

Repo is a Git-based multi-repository management tool used to simplify the download of Yocto layered source code. The installation steps are as follows:

Create a tool directory and download Repo:

mkdir -p ~/bin

curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo

chmod a+x ~/bin/repo

Configure environment variables (permanently effective):

echo "export PATH=~/bin:\$PATH" >> ~/.bashrc

source ~/.bashrc

3. Setting Up the Yocto Environment

(1) Download i.MX Yocto BSP Source Code

Create a working directory and initialize Repo:

mkdir imx-yocto-bsp

cd imx-yocto-bsp

repo init -u https://github.com/nxp-imx/imx-manifest -b imx-linux-walnascar -m imx-6.12.34-2.1.0.xml

-b specifies the branch (corresponding to Yocto 5.2 Walnascar version)
-m specifies the manifest file (defining the source repository and version)

Sync the source code (may take a long time depending on network speed):

repo sync

After synchronization, the source code will be stored in the imx-yocto-bsp/sources directory, containing the i.MX specific layer (meta-imx) and community layers (such as poky, meta-freescale, etc.).

(2) Build Configuration Initialization

The i.MX provides the imx-setup-release.sh script to simplify build configuration, requiring the specification of target hardware (MACHINE) and graphical backend (DISTRO), with the syntax as follows:

DISTRO=<distro configuration> MACHINE=<machine name> source imx-setup-release.sh -b <build directory name>

Key Parameter Descriptions:

Parameter	Optional Values	Description
DISTRO	fsl-imx-wayland	Pure Wayland graphics (recommended for i.MX 8/9)
fsl-imx-xwayland	Wayland + X11 (default, compatible with X11 applications)
fsl-imx-fb	Framebuffer (only supports i.MX 6/7, not 8/9)
MACHINE	imx8mpevk	i.MX 8M Plus EVK development board
imx8mqevk	i.MX 8M Quad EVK development board
imx6qpsabresd	i.MX 6QuadPlus SABRE-SD development board
Others	For a complete list, see section 5.1 of the documentation (e.g., imx93evk, imx7dsabresd, etc.)

Example: Configure i.MX 8M Plus EVK + XWayland Backend

DISTRO=fsl-imx-xwayland MACHINE=imx8mpevk source imx-setup-release.sh -b build-xwayland

After execution, you will be prompted to accept the NXP EULA (End User License Agreement). Enter y to confirm, and the script will create the build directory build-xwayland and generate configuration files conf/bblayers.conf (layer configuration) and conf/local.conf (local parameter configuration).

4. Image Building

(1) Select Image Type

Yocto supports various predefined images suitable for different scenarios, commonly used images are as follows:

Image Name	Usage	Provided Layer
core-image-minimal	Minimal system (only able to boot)	poky
core-image-base	Complete console system (supports hardware features)	poky
imx-image-multimedia	With multimedia features (without Qt)	meta-imx/meta-imx-sdk
imx-image-full	With Qt 6 + machine learning features (requires GPU support)	meta-imx/meta-imx-sdk
fsl-image-machine-test	Community basic test image (without GUI)	meta-freescale-distro

(2) Execute Build Command

Use the bitbake command to start the build, syntax:bitbake <image name>

The core command for Yocto builds is <code>bitbake <target>, the complete process can be broken down into configuration initialization → metadata parsing → dependency resolution → resource downloading → compilation building → image packaging six stages.

For example, to build the minimal system image core-image-minimal:

bitbake core-image-minimal

BitBake will execute the build in the following stages (you can view the complete variables and stages using bitbake -e <target>):

Stage 1: Metadata Parsing

Load metadata from all layers in bblayers.conf (recipes, configuration files).
Parse the recipe for the target image (e.g., core-image-minimal.bb), recursively parsing all dependent package recipes (such as kernel, root filesystem, toolchain).
Generate a build task dependency graph (Task Graph) to determine the execution order of tasks (e.g., compile dependencies first, then compile the main package).

Stage 2: Dependency Resolution

BitBake analyzes all recipes’ DEPENDS (compile dependencies) and RDEPENDS (runtime dependencies), resolving dependency conflicts.
Determine the build order for each package (e.g., compile glibc first, then gcc, and finally the application).

Stage 3: Resource Downloading

Download the source specified in the recipe’s SRC_URI (e.g., kernel source, package source), caching it to <code>DL_DIR.
Supports various protocols (HTTP, Git, FTP) and verifies checksums (e.g., SHA256) to ensure source integrity.
If cached locally, skip the download (speeding up the build).

Stage 4: Unpacking & Patching

Unpack the downloaded source to build/tmp/work/<architecture>/<package name>/<version>/workdir/.
Apply patches defined in the recipe (SRC_URI contains <code>.patch files), adapting the source to the target platform.

Stage 5: Configuration & Compilation

Configuration: Execute the configuration script of the source (e.g., ./configure, <code>make menuconfig, <code>CMake), injecting Yocto-defined compilation parameters (e.g., cross-compiler path, CFLAGS, LDFLAGS).
Compilation: Call the cross-compiler (Yocto automatically builds the toolchain, located in build/tmp/sysroots/<host architecture>/usr/bin/<target architecture>/) to compile the source, generating executables/libraries.

Stage 6: Installation & Packaging

Installation: Install the compiled products (executables, libraries, configuration files) to build/tmp/work/<architecture>/<package name>/<version>/image/ (temporary installation directory).
Packaging: Based on the PACKAGE_CLASSES configuration, package the files from the installation directory into the specified format (deb/rpm/ipk), or directly package them into the root filesystem.

Stage 7: Generate Root Filesystem (RootFS)

Collect all installed files from packages and merge them into the root filesystem directory (build/tmp/work/<architecture>/<image name>/<version>/rootfs/).
Generate filesystem images (e.g., ext4, squashfs, ubifs), or generate bootable images (e.g., SD card images, ISO images).

Stage 8: Output Final Image

The final image files are output to build/tmp/deploy/images/<MACHINE>/, common products include:

core-image-minimal-<MACHINE>.rootfs.ext4: Root filesystem image.
core-image-minimal-<MACHINE>.sdimg: Image that can be directly burned to an SD card.
zImage/Image: Kernel image.
u-boot.bin: U-Boot image (if U-Boot build is configured).

Example 1: Build Multimedia Image (Without Qt)

cd build-xwayland  # Enter build directory

bitbake imx-image-multimedia

Example 2: Build Full Image with Qt 6 and Machine Learning

bitbake imx-image-full

The first build will automatically download the toolchain and dependency packages, which may take a long time (from several hours to tens of hours, depending on hardware performance)
During the build process, you can check the progress through logs:build-xwayland/tmp/work/<architecture>/<component>/temp

(3) Common BitBake Options

Option	Function
-c fetch	Only download component source (do not compile)
-c cleanall	Clean component build directory (rebuild from scratch)
-c deploy	Deploy image/component to root filesystem
-k	Continue compiling other components when build fails
-g	Generate component dependency tree
-s	Display current and recommended versions of all recipes
-DDD	Enable triple debug logging

Example: Force recompile a specific component

bitbake -c compile -f u-boot-imx

(4) U-Boot Configuration (Optional)

The default U-Boot uses SD card booting. If you need to configure other boot methods (such as SPI, NAND), you need to add configurations in local.conf:

# Single boot method (e.g., eimnor)

echo "UBOOT_CONFIG = \"eimnor\"" >> conf/local.conf

# Multiple boot methods (e.g., SD + eimnor)

echo "UBOOT_CONFIG = \"sd eimnor\"" >> conf/local.conf

# Build U-Boot separately

MACHINE=imx8mpevk bitbake -c deploy u-boot-imx

5. Image Deployment

(1) Locate Build Products

After the build is complete, the image files are stored in build-xwayland/tmp/deploy/images/<machine name>/, core files include:

.wic.zst: SD card image (includes partitions, U-Boot, kernel, root filesystem)
.tar.gz: Compressed root filesystem package (for deployment to other storage media)
u-boot.imx: U-Boot binary file
Image: Linux kernel image

(2) Burn SD Card Image

Insert the SD card into the host and use lsblk to check the device node (e.g., <code>/dev/sdb)
Execute the burn command (replace <image name> and <code><device node>):

zstdcat <image name>.wic.zst | sudo dd of=/dev/sd<partition> bs=1M conv=fsync

Example:

zstdcat imx-image-multimedia-imx8mpevk.wic.zst | sudo dd of=/dev/sdb bs=1M conv=fsync

After burning, insert the SD card into the i.MX development board, set the boot switch to SD card boot, and power on to start the system.

6. Customization Operations

(1) Add Custom Packages

If you need to add additional software packages to the image (which must have corresponding Yocto recipes), add the following in local.conf:

# Single package

CORE_IMAGE_EXTRA_INSTALL:append = " <package name>"

# Multiple packages (space-separated)

CORE_IMAGE_EXTRA_INSTALL:append = " chromium-ozone-wayland opencv"

Example: Add the Wayland version of the Chromium browser

CORE_IMAGE_EXTRA_INSTALL:append = " chromium-ozone-wayland"

bitbake-layers add-layer ../sources/meta-browser/meta-chromium  # Add browser layer

bitbake imx-image-multimedia  # Rebuild the image

(2) Create Custom Distribution (DISTRO)

Copy the existing distribution configuration file (based on fsl-imx-xwayland):

cp ../sources/meta-imx/meta-imx-sdk/conf/distro/fsl-imx-xwayland.conf ../sources/meta-imx/meta-imx-sdk/conf/distro/my-custom-distro.conf

Edit my-custom-distro.conf to modify parameters (such as kernel version, default packages, graphical backend, etc.)
Build using the custom distribution:

DISTRO=my-custom-distro MACHINE=imx8mpevk source imx-setup-release.sh -b build-custom

bitbake imx-image-full

7. Common Problem Solutions

(1) Build Failure: Dependency Package Download Timeout

Manually download the corresponding package to DL_DIR (default <code>build-xwayland/downloads)
Create a <package name>.done file to mark the download as complete:<code>touch <package name>.done
Re-execute the bitbake command

(2) Image Boot Failure

Check if the SD card burning is complete (re-burn if necessary)
Confirm that the development board’s boot switch configuration is correct
Check the U-Boot logs (serial output) to confirm that the kernel and root filesystem paths are correct

(3) Custom Recipe (bbappend) Not Effective

Check if the recipe filename matches the original recipe (e.g., u-boot-imx_%.bbappend)
Check the log.do_fetch log to confirm if the patch is loaded correctly
Ensure that the FILESEXTRAPATHS path is configured correctly:

FILESEXTRAPATHS:prepend := "\\${THISDIR}/\\${PN}:

8. References

Official Documentation: i.MX Yocto Project User’s Guide (UG10164)
Yocto Project Official Documentation: https://docs.yoctoproject.org/
NXP i.MX Developer Official Website: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/i-mx-applications-processors/i-mx-8-processors:i.MX8

Finally

The author has collected some embedded learning materials. Reply with 【1024】 in the public account to find the download link!

Recommended Articles  Click the blue text to jump
☞ Collection|Linux Application Programming Guide
☞ Collection|Learn Some Networking Knowledge
☞ Collection|C Language Essentials

☞ Collection|C++ Language Essentials
☞ Collection|Experience Sharing
☞ Collection|From Microcontrollers to Linux
☞ Collection|Power Control Technology
☞ Collection|Essential Mathematics for Embedded Systems
☞ Collection|MCU Advanced Collection