1. Setup

1.1. References

This guide is based on the NXP/Freescale Yocto Project User’s Guide. See it here.

The instructions for setting up and building Linux in the Yocto Project were adopted to our products.

A list of helpful bitbake commands can be found here:

NXP/Freescale - Useful bitbake commands

A cheat sheet for bitbake:

Bitbake Cheat Sheet

1.2. Requirements

For Yocto a Linux Host Machine is needed. The supported distributions are listed at the official Yocto documentation.

If you’re running such a machine, you should be fine, else we recommend to use VirtualBox to run a virtual machine. We recommend to use an Ubuntu 16.04 instance. Get a working-ready virtual machine image from osboxes.org.

See their guide to run the virtual machine image.

An important consideration is the hard disk space required for the virtual appliance. It is recommended that at least 120 GiB is provided, 500 GiB would be better.

1.3. Host packages

The Yocto framework requires (build) dependencies that need to be available on the host system for the builds.

To meet minimal version requirements you should have the following installed:

  • Git or greater
  • tar 1.27 or greater
  • Python 3.4.0 or greater

If your system does not meet these requirements see this.

To get the right packages for your build host, have a look at the official Yocto project documentation.

Essential Yocto Project host packages are:

sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
build-essential chrpath socat libsdl1.2-dev

1.4. Setting up git

If not already done, setup git with the commands below:

git config --global user.name "Your Name"
git config --global user.email "Your Email"
git config --list

1.5. Setting up the repo utility [1]

Repo is a tool built on top of Git that makes it easier to manage projects that contain multiple repositories, which do not need to be on the same server. Repo complements very well the layered nature of the Yocto Project, making it easier for users to add their own layers to the BSP.

To install the “repo” utility, perform these steps:

  1. Create a bin folder in the home directory:
mkdir ~/bin (this step may not be needed if the bin folder already exists)
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
  1. Add the following line to the ~/.bashrc file to ensure that the ~/bin folder is in your PATH variable:
export PATH=~/bin:$PATH

1.6. Yocto Project Setup

The BSP Release directory contains a sources directory, which contains the recipes used to build, one or more build directories, and a set of scripts used to set up the environment. The Yocto Project layers are downloaded to the sources directory. This sets up the recipes that are used to build the project. The following example shows how to download the BSP recipe layers defined in our repository. For this example, a directory called karo-yocto-sumo is created for the project (usually under a directory like $HOME/projects/ is recommend).

Use the branch imx-linux-sumo. The directory karo-bsp-tx8m is just an example and can be choosen free:

mkdir karo-bsp-tx8m
cd karo-bsp-tx8m
repo init --no-clone-bundle -u https://github.com/karo-electronics/karo-nxp-bsp -b imx-linux-sumo
repo sync --no-clone-bundle

When this process is completed, the source code is checked out into the directory sources under the working directory (in example above karo-yocto-sumo).

You should update the codebase periodically, which can be performed via the following command:

repo sync --no-clone-bundle

After a prolonged timespan an update is strongly recommended.

If errors occur during repo initialization, try deleting the .repo directory and running the repo initialization command again.

1.7. Configuring the build

We provide a script, karo-nxp-release.sh, that simplifies the setup for our machines. To use the script, the name of the specific machine to be built for needs to be specified as well as the desired graphical backend. The script sets up a directory and the configuration files for the specified machine and backend. [1] It also adds our layer to the bblayers.conf file.

There are different configurations you can choose from.

  • DISTRO configurations:
DISTRO= Description
fsl-imx-x11 X11 graphics are not supported on i.MX 8
fsl-imx-wayland Wayland weston graphics
fsl-imx-xwayland Wayland graphics and X11. X11 applications using EGL are not supported
fsl-imx-fb Frame Buffer graphics - no X11 or Wayland. Frame Buffer is not supported on i.MX 8
  • A list of supported MACHINE configurations:
    • tx8m-1610-mipi-mb - RECOMMENDED For TX8M machine on 10.1” Development Kit board.
    • tx8m-1610 - For TX8M machine on any board.

Use this command to setup your build directory (specify the distro you want to use, the machine, and the build directory):

DISTRO=<distro> MACHINE=<machine> source karo-nxp-release.sh -b <build-dir>

When the script has run, your current directory should have changed to the <build-dir> you chose before.


DISTRO=fsl-imx-wayland MACHINE=tx8m-1610-mipi-mb source karo-nxp-release.sh -b build

1.8. U-Boot version

Inside your build-directory in conf/local.conf you can set the variable UBOOT_CONFIG. This sets which u-boot should be built. If you leave it unset, “default” is built.

UBOOT_CONFIG = Description
default Our U-Boot with default environment to write inside the eMMC and boot your module.
noenv Our U-Boot with an empty environment.
mfg Our U-Boot with enabled fastboot protocol. (e.g. for using uuu)
secure-boot Our U-Boot with secure-boot enabled.


For programming TX8M with uuu (see Flashing Images), it is necessary to build both, default and mfg U-Boot.

1.9. Graphics acceleration for QT

If you want to use graphics acceleration in the current fsl-image-qt5 image, you should enable the QT5 kernel features. This will enable the usage of NXP’s defconfig.

To enable these, add the following line into your build-directory to local.conf:

KERNEL_FEATURES_append = "qt5"


Your kernel size will expand around the double size.

1.10. Building the image


Before starting a build, you should consider enabling the SSTATE CACHE to speedup the build process.

See Enable sstate cache 1.

Here are the different images you can build:

Image Description Provided by layer
core-image-minimal See https://layers.openembedded.org/layerindex/recipe/579/ Poky
core-image-base See https://layers.openembedded.org/layerindex/recipe/584/ Poky
core-image-sato See https://layers.openembedded.org/layerindex/recipe/658/ Poky
fsl-image-machine-test An FSL Community i.MX core image with console environment - no GUI interface. meta-freescale-distro
fsl-image-validation-imx Builds an i.MX image with a GUI without any Qt content. meta-fsl-bsp-release/imx/meta-sdk
fsl-image-qt5-validation-imx Builds an opensource Qt 5 image. These images are only supported for i.MX SoC with hardware graphics. They are not supported on the i.MX 6UltraLite, i.MX 6UltraLiteLite, and i.MX 7Dual. meta-fsl-bsp-release/imx/meta-sdk
fsl-image-qt5 Fsl-image-gui with QT 5.9.  
meta-toolchain-qt5 QT 5 Toolchain SDK.  
fsl-image-gui Full image with demos and tests, used for testing with graphics, no QT  

Build the image with the following command inside your <build-dir>:

bitbake <image>

1.11. Restarting a build environment [1]

If a new terminal window is opened or the machine is rebooted after a build directory is set up, the setup environment script should be used to set up the environment variables and run a build again. The full fsl-setup-release.sh is not needed.

You can simply run:

source setup-environment <build-dir>

1.12. Image Deployment

After a build is complete, the created image resides in the tmp/deploy/images sub-directory. An image is, for the most part, specific to the machine set in the environment setup. Each image build creates a U-Boot, a kernel, and an image type based on the IMAGE_FSTYPES defined in the machine configuration file.

The following files are created for Ka-Ro TX modules:

Filename Content
imx-boot-<machine>-<version>.bin U-Boot binaries
Image-<version>-<machine>.bin Kernel image
modules-<machine>.tgz Kernel modules
<image>-<machine>.tar.bz2 RFS
*.dtb Devicetree blob

To continue with these images have a look at Flashing Images.

[1](1, 2, 3) Copied from the official NXP Yocto Project User’s Guide, mentioned above.