03 24, 2026 10:38

Overview

phyLinux, the build script for all Phytec yocto BSPs, requires a very specific build environment. Therefore, Phytec uses Virtual Machines, or Docker images (container), with a full build environment to make building OS images as easy as possible. The virtual machine images for your product and the complete instructions for the VM build environment can be found on our website, for example for the phyBOARD Polis: phycore-imx-8m-mini/nano/#downloads. 

This how-to explains how to use an alternative build environment in a container to build a BSP from sources without booting into a full VM. Using containers has the advantage of being independent of the OS on your build machine but leveraging the full power of your machine as well as giving you the opportunity to use the tools you are used to. 

After this guide you are able to boot your phyBOARD Polis with a fresh image from an SD card.

To follow this guide you need a PC with enough processing power (Intel i7 category or similar) and RAM (16GB upwards) with installed Podman (preferred, https://podman.io/) or Docker Engine (https://www.docker.com/). Linux is a good choice for the operating system but all instructions here should also run on Windows and MAC.

Hardware and software used in this example

For this guide I'll be using a phyBOARD Polis connected via USB/Serial to my development machine like it is explained in the Quickstart guides. You need an SD card with enough space for your image (ca. 2GB)

Hardware: phyBoard i.MX8MM Polis

BSP: BSP-Yocto-NXP-i.MX8MM-PD22.1.0

Yocto: 3.3.x hardknott

Kernel: NXP Vendor Kernel v5.10.72_2.2.0-phy4

Bootloader: v2021.04-2.2.0-phy5

Machine: phyboard-polis-imx8mm-4

Build Environment: Ubuntu 20.04 

Prepare Podman

Follow the installation instructions https://podman.io/docs/installation.

If you choose Podman, you need to enable the docker mode, so you can load docker container with podman.

Preparing the container

Phytec provides ready-to-use container-images for you that you can download and use: https://hub.docker.com/u/phybuilder

• yocto-ubuntu-16.04

• yocto-ubuntu-18.04

• yocto-ubuntu-20.04

• yocto-ubuntu-22.04

• yocto-ubuntu-24.04

Verify the connection to the Linux system

podman system connection list

First you need to start a podman machine with wsl. You can start the created podman machine like this:

wsl -d podman-machine-default

Select the one you would like to use (e.g. Ubuntu 20.04) like this

podman pull docker.io/phybuilder/yocto-ubuntu-20.04

Load your container:

podman run --rm=true -v /home:/home --userns=keep-id --workdir=$PWD -it docker.io/phybuilder/yocto-ubuntu-20.04 bash

Setup phyLinux

Inside the Container create a new folder with enough space (20GB+) and change into the folder.

Then download the phyLinux setup script which takes care of all the configurations and mark it as executable:

mkdir Yocto
cd Yocto
wget https://download.phytec.de/Software/Linux/Yocto/Tools/phyLinux
chmod +x phyLinux

Configure yocto with phyLinux

Initializing phyLinux

Run phyLinux to setup your yocto build environment. phyLinux takes care of all the settings to build an image which fits your hardware.

./phyLinux init

The script interactively guides you through the process for the image. Your processor platform for the Polis is "imx8mm" (1), I selected the most current build PD22.1.0 (14) at the time of writing and as the machine select the minimal configuration number (1):

...

No SoC Platform selected
***************************************************
* Please choose one of the available SoC Platforms:
*
*   1: am335x
*   2: am62x
*   3: am64x
*   4: imx6
*   5: imx6ul
*   6: imx7
*   7: imx8
*   8: imx8m
*   9: imx8mm
*   10: imx8mp
*   11: nightly
*   12: rk3288
*   13: stm32mp1
*   14: topic
*
$ 9
switching to imx8mm
$ repo init -b imx8mm

***************************************************
* Please choose one of the available Releases:
*
*   1: BSP-Yocto-Ampliphy-i.MX8MM-master
*   2: BSP-Yocto-FSL-i.MX8MM-ALPHA1
*   3: BSP-Yocto-FSL-i.MX8MM-ALPHA2
*   4: BSP-Yocto-FSL-i.MX8MM-PD20.1-rc1
*   5: BSP-Yocto-FSL-i.MX8MM-PD20.1-rc2
*   6: BSP-Yocto-FSL-i.MX8MM-PD20.1-rc3
*   7: BSP-Yocto-FSL-i.MX8MM-PD20.1.0
*   8: BSP-Yocto-FSL-i.MX8MM-PD21.1-rc1
*   9: BSP-Yocto-FSL-i.MX8MM-PD21.1-rc2
*   10: BSP-Yocto-FSL-i.MX8MM-PD21.1-rc3
*   11: BSP-Yocto-FSL-i.MX8MM-PD21.1.0
*   12: BSP-Yocto-NXP-i.MX8MM-PD22.1-rc2
*   13: BSP-Yocto-NXP-i.MX8MM-PD22.1-rc3
*   14: BSP-Yocto-NXP-i.MX8MM-PD22.1.0
*
$ 14
switching to BSP-Yocto-NXP-i.MX8MM-PD22.1.0
$ repo init -m BSP-Yocto-NXP-i.MX8MM-PD22.1.0.xml

...

*********************************************************************
* Please choose one of the available builds:
*
no:                 machine: description and article number
                             distro: supported yocto distribution
                             target: supported build target

 1: phyboard-polis-imx8mm-4: PHYTEC phyBOARD-POLIS i.MX8M Mini 2GB RAM
                             16GB eMMC, Audio
                             PB-02820.A2
                             distro: ampliphy-vendor
                             target: phytec-headless-image
 2: phyboard-polis-imx8mm-4: PHYTEC phyBOARD-POLIS i.MX8M Mini 2GB RAM
                             16GB eMMC, Audio
                             PB-02820.A2
                             distro: ampliphy-vendor-provisioning
                             target: phytec-provisioning-image
 3: phyboard-polis-imx8mm-4: PHYTEC phyBOARD-POLIS i.MX8M Mini 2GB RAM
                             16GB eMMC, Audio
                             PB-02820.A2
                             distro: ampliphy-vendor-rauc
                             target: phytec-headless-bundle
                             target: phytec-headless-image

...

 9: phygate-tauri-l-imx8mm-2: PHYTEC phyGATE-Tauri-L i.MX8M Mini 2GB RAM
                             RS232/RS485 16GB eMMC
                             PB-03420
                             distro: ampliphy-vendor-secure
                             target: phytec-security-bundle
                             target: phytec-security-image
$ 1
add TARGET phytec-headless-image to conf-notes.txt
set MACHINE in local.conf to phyboard-polis-imx8mm-4
set DISTRO in local.conf to ampliphy-vendor

Before you start your work, please check your build/conf/local.conf for
host specific configuration. Check the documentation especially for:
   - proxy settings
   - DL_DIR
   - SSTATE_DIR

To set up your shell environment for some Yocto work, you have to type this
command, including the 'dot':

    $ . sources/poky/oe-init-build-env

Now your environment is nearly configured to build the BSP for the phyBOARD Polis.

Some lines in the local configuration have to be changed:

vi build/conf/local.conf

Afterward, as mentioned in the output, we need to configure temporary build folders. You can just use my configuration examples as the folders will be created for you:

DL_DIR = "${TOPDIR}/yocto-downloads"
SSTATE_DIR = "${TOPDIR}/yocto-sstate-cache"

Find and uncomment the following lines to accept the EULAs:

...

# Newer versions use LICENSE_FLAGS_ACCEPTED !!!

# Uncomment to accept NXP EULA (needed, if any NXP / freescale layer is used)
# EULA can then be found under ../sources/meta-freescale/EULA
ACCEPT_FSL_EULA = "1"
...

Save and exit.

Create your image

Each time you start up the container to run a build you have to prepare the environment:

source sources/poky/oe-init-build-env

The next step is to really start the build. On my machine the initial build runs for about 40 minutes, your results may vary

bitbake phytec-headless-image

After the build all images are available in the build/deploy/images/phyboard-polis-imx8mm-4 folder on your drive.

Exit the container with "exit"

Copy Image to SD card and boot your board

We are using the .sdcard image to boot our board (if there is no .sdcard image available, try looking for a .wic file)

You can use dd to copy the image to your SD card. Be extra careful to use the right device name as it can erase your harddrive. If you are not 100% sure on dd usage, please use a tool like Raspberry Imager to transfer the image to your SD card.

cd deploy/images/phyboard-polis-imx8mm-4
sudo dd if=phytec-headless-image-phyboard-polis-imx8mm-4.sdcard of=/dev/<your_device> bs=1M conv=fsync status=progress

Insert the SD card into your board, verify boot settings as described in the Quickstart and boot up your board with the fresh BSP.

Recovering from build problems

If you encounter problems during the build you can recover by deleting one or all of the following directories:

Yocto/.../build/ bitbake phytec-headless-image -c clean
Yocto/.../build/ bitbake phytec-headless-image -c cleanall
Yocto/.../build/ bitbake phytec-headless-image -c cleansstate