Search by Tags

OpenEmbedded (core)

Article updated at 16 Jun 2020
Compare with Revision

Subscribe for this article updates

This document describes how to build our BSP V2.x/3.x from scratch using OpenEmbedded core (oe-core).

OpenEmbedded ( is a build framework which creates kernel images, root filesystem images and installable packages from source code. (OpenEmbedded for the sake of this document is a synonym for Yocto).

OpenEmbedded comes in two flavours, OpenEmbedded classic, and the newer OpenEmbedded core. Our Linux images V1.x are based on OpenEmbedded (classic) while the images starting from V2.0 use OpenEmbedded core.

OpenEmbedded uses meta information (called recipes) for downloading/compiling/deploying of software packages on a x86/x86_64 Linux build host for a target device. This meta information is structured into so-called layers. Layers are directory trees with recipes which provide similar functionality, e.g. meta-lxde which provides recipes to build packages for the LXDE desktop.

Toradex Version Distribution OpenEmbedded/Yocto Codename Yocto Project Release
2.1 Ångström v2013.06 dylan 1.4
2.2 Ångström v2013.12 dora 1.5
2.3 Ångström v2014.06 daisy 1.6
2.4 Ångström v2014.12 dizzy 1.7
2.5 Ångström v2015.06 fido 1.8
2.6 / 2.6.1 Ångström v2015.12 jethro 2.0
2.7 Ångström v2016.12 morty 2.2
2.8 Ångström v2017.12 rocko 2.4
3.0 Poky based thud 2.6
4.0.0 (intent 2020) Poky based zeus 3.0


For our Linux image starting from V2.0 we use OpenEmbedded core. Layers from are used together with a number of other layers.

oe-core installation and configuration (and the later build) will setup the following directory structure

+-- build
¦   +-- conf
¦   +-- downloads
¦   +-- tmp
¦   +-- sstate-cache
¦   +-- deploy
+-- layers
    +-- meta-browser
    +-- meta-freescale
    (... other layers)
    +-- openembedded-core

All meta data is stored under the 'layers' tree, under the 'build' tree is the configuration of what is to be built, the downloaded sources and intermediate output, generated packages, SDKs, and the final images are put under 'deploy'.
Under 'build' only conf/* needs to be preserved. The other content under 'build' can be regenerated by bitbake.

Note: This layout has changed over time:

  • The 'layers' directory was called 'stuff'.
  • The 'tmp' directory was called 'tmp-glibc' or 'out-glibc' or 'out-eglibc'.
  • The 'deploy' directory was a subdirectory of 'oe-core' or 'out-glibc'.


To build the whole OpenEmbedded image a powerful host machine is highly recommended. If the host system is a multi-core machine, you can configure the Yocto Project build system to significantly decrease the time needed to build images. There should be a minimum of 60 GBytes of free disk space. For some images, a 32-bit image with 4 GBytes of memory is enough, but in order to build applications such as the WebKit web engine, a 64-bit machine with 8 GBytes of RAM is recommended.

As for the operating environment, a supported Linux distribution (i.e. recent releases of Fedora, openSUSE, CentOS, Debian, or Ubuntu) is required. The OpenEmbedded wiki provides a required software list for several Linux distributions. Make sure your Distribution is supported and that required software is installed:

OpenEmbedded (Getting started) (do not proceed with 'Setup instructions' available on the same page!)

Should you choose Ubuntu or another distro which uses dash as the default shell we recommend to change this to bash. (Google for 'ubuntu bash update-alternatives')

Toradex BSP (meta-toradex) builds require some additional packages, mainly to compile the flashing utilities as 32-bit executables:

Fedora 28
Fedora 24 and later for releases prior to V2․7
Fedora 22 to 28
Fedora 20 and 21
Ubuntu 18․04 64-bit
Ubuntu 16․04 64-bit
Ubuntu 15․10 64-bit
Ubuntu 15․10 32-bit
Ubuntu 14․04 64-bit
Ubuntu 14․04 32-bit

Warning: Please note that Ubuntu 18.10 is not yet supported by OpenEmbedded, using it may lead to unexpected behaviour.


V2.1 and Later Images


Since OpenEmbedded requires several git repositories to be available to build our images, starting with V2.1 images we are using a utility called 'repo'. The repo manifest manages the various git repositories and their branches. (more on repo: )

Install the repo bootstrap binary:

mkdir ~/bin
export PATH=~/bin:$PATH
curl > ~/bin/repo
chmod a+x ~/bin/repo

Alternatively, in Ubuntu, 'repo' may be installed as part of the 'phablet-tools' package.

Repo uses Git. Make sure you have it installed and user name and e-mail configured. Below is an example for Debian-based systems:

sudo apt install git
git config --global "John Doe"
git config --global

Create a directory for your oe-core setup to live in and clone the meta information. For the Vx.y... Image use the branch LinuxImageVx.y..., e.g. for the V2.5 Image use the branch LinuxImageV2.5, starting with BSP 3.0 we skip the V e.g. use LinuxImage3.0 instead.

The stable branch version is 2.8 that is based on rocko.

$ mkdir oe-core
$ cd oe-core
$ repo init -u -b LinuxImageV2.8
$ repo sync

The latest branch version is 3.0 that is based on thud.

$ repo init -u -b LinuxImage3.0 -m default.xml
$ repo sync

Source the file 'export' to setup the environment. On first invocation, this also copies a sample configuration to build/conf/*.conf.

. export

Note: Sourcing 'export' configures the shell environment for the current shell session. It must be entered whenever a new shell session is opened for use with OpenEmbedded.


Adapt build/conf/local.conf to your needs.

Set MACHINE to the module type you are planning to build for. Our BSP layers provide the following machines:

Machine Name
apalis-t30 (In BSP releases prior to 3.0)
colibri-t20 (In BSP releases prior to 3.0)
colibri-t30 (In BSP releases prior to 3.0)
colibri-vf (In BSP releases prior to 3.0)

e.g. set in local.conf

MACHINE ?= "colibri-imx6"

Note: You can explicitly override the MACHINE setting on the cmdline, set the variable MACHINE when calling the bitbake command (e.g. MACHINE=apalis-imx6 bitbake...)

If you have lots of disk space and want to browse the unpacked sources, consider commenting the 'INHERIT += "rm_work"' line.

If you already have a download directory with sources from a previous oe setup consider moving that directory into oe-core/build/download or change local.conf to point to your common download location. DL_DIR.

If you want to build for a machine based on an NXP based SoM some downloads require you to read and accept the NXP®/Freescale EULA available in layers/meta-freescale/EULA. You have to state your acceptance by adding the following line to your local.conf file:
If this line is missing the relevant packages will produce an ERROR similar to: ERROR: To use 'imx-vpu' you need to accept the NXP®/Freescale EULA at 'layers/meta-freescale/EULA'. Please read it and in case you accept it, write: ACCEPT_FSL_EULA = "1" in your local.conf.

Setup is finished, continue with the Building chapter.

Update an Existing Configuration

Please also consult the release notes.

To update the installation you first update the repo manifest to the version you want to work with and then sync all layers. Check the known issues section below before starting the update.

If you did local changes to the individual layers merge conflicts may occur which you will have to resolve in the respective layer.

Update to the HEAD Revision

e.g. use LinuxImage3.0 to update to the BSP 3.0 image version. Use LinuxImageV2.x e.g. LinuxImageV2.8 in BSP releases prior to 3.0).

repo init -b LinuxImage3.0
repo sync

Update to a Specific Version by Using its Tag

A list of available tags can be found in the manifest repository:

repo init -b refs/tags/Apalis-iMX8_Console-Image_3.0b1.40-20190612
repo sync

Known Issues

If your repo command succeeds, you can directly proceed with the instructions in the chapter Building below.

Updates from older versions
Repo Sync Issues
Bitbake Build Issues

V2.0 Images

To configure V2.0 builds, see OpenEmbedded (core) Configuration for V2.0 Images.


#setup the environment
cd oe-core
. export

Build the image, bitbake automatically logs console output to timestamped files in build/tmp/log/cooker/$MACHINE/.

Note: With oe-core you need to be in the directory 'build' when you execute bitbake. Note: This will at first build take hours, download lots of stuff and fill 'build/tmp', so have at least 60 GByte free. Note: Check available demo image recipes in layers/meta-toradex-demos/recipes-images/images/

bitbake -k console-tdx-image

Build a single package and all the things it depends on.

bitbake samba

Building an SDK for your image (See also Linux SDKs)

bitbake console-tdx-image -c populate_sdk

The output can be found here:

  • For images, u-boot, uImage, rootfs, deployable tarball: build/deploy/images/${MACHINE}/
  • For SDKs: build/deploy/sdk/
  • For ipk packages: build/deploy/ipk//*.ipk


Toradex Easy Installer Image Format (Apalis TK1, Apalis/Colibri iMX6, Apalis/Colibri iMX8, Colibri iMX6ULL, Colibri iMX7)

The image tarball, (e.g. Colibri-iMX6_LXDE-Image-Tezi_2.7-20180104.tar) has the same structure as our pre-built ones we provide for download.
To update your Colibri module with a newly built image follow the update procedure documented in the Toradex Easy Installer article.

Legacy Image Format

Note: We dropped building legacy image with BSP 3.0.

The image tarball, (e.g. Colibri-iMX6_LXDE-Image_2.7-20180104.tar.bz2) has the same structure as our pre-built ones we provide for download.
To update your Colibri module with a newly built image follow the update procedures documented in the flashing articles for i.MX6 , i.MX7 , Tegra and Vybrid.

If you built an alternative image target like core-image-minimal one can just replace the rootfs from e.g. our Colibri_T20_LinuxImageV2.7Beta1_20170112.tar.bz2 tarball with the one from your core-image-minimal build and update your module as usual. Note however that Toradex images newer than 03.2013 determine the module type from the rootfs/etc/issue file. On newer images use ' -h' and then '-m' parameter to force a module type. For older images add a line so that our script can determine the correct module type e.g.:

sudo sh -c 'echo "" >> etc/issue'
sudo sh -c 'echo "Colibri_T20" >> etc/issue'

Use one of the following strings: "Apalis_iMX6", "Apalis_T30", "Apalis_TK1", "Colibri_iMX6",
"Colibri_iMX7", "Colibri_T20", "Colibri_T30", "Colibri_VF"

Package Manager

To deploy ipk packages into a running image copy the relevant ipk files onto the module and use the opkg package manager to install it. If the package has dependencies which are not yet installed you will have to install them as well.

opkg install file1.ipk file2.ipk

Failing Builds

An OpenEmbedded build sometimes fails.

This is what I normally do when a task fails:

  • Reading through the error messages.
  • Restarting bitbake without deleting anything and see if it happens again.
  • Clean the task which failed and then restart building the image, e.g. if python-native fails

    $ bitbake -c clean python-native
    $ bitbake angstrom-lxde-image

  • Clean the task which failed, including deleting cached output and then restart building the image

    $ bitbake -c cleansstate python-native
    $ bitbake angstrom-lxde-image

  • Clean the task which failed, including deleting cached output and the downloaded files and then restart building the image

    $ bitbake -c cleanall python-native
    $ bitbake angstrom-lxde-image

  • Check the layer which provides the recipe if a newer commit exists which addresses the problem.

  • If there are a lot of issues with fetching sources you could try to first only download all needed sources.

    bitbake -c fetchall angstrom-lxde-image

Notes on older versions

Some Useful Bitbake Commands

If you do an unattended build, '-k' tells bitbake to keep going with independent packages after an error occurred.

bitbake -k console-tdx-image

If you need to dig into what recipes and settings are used the following command outputs a bunch of environment settings and infos about what is going on:

bitbake -e virtual/kernel
bitbake -e virtual/kernel | grep ^WORKDIR

If you want to see all tasks which exist for a given recipe:

bitbake -c listtasks virtual/kernel

First steps into your custom build

OpenEmbedded can be quite defying and hard to use. In the following documentation, we covered some basic functionality that is likely you will have to go through need during your development: Hello World integration into OpenEmbedded

Additional Layers

Recipes for even more software are available in additional layers. e.g. The java layer provides recipes related to java. Most layers are registered at They provide a web interface to find layers or individual recipes:

Note that just because a layer or a recipe exists, that does not mean that these recipes will compile/execute. The layers/recipe might have a version conflict with what we use or might have never been used with or intended for the Arm architecture.

Refer to the following sections to see examples on how to add a new layer to our setup.

Adding the Qt Layer

Please refer to How to set up Qt Creator to cross-compile for embedded Linux.

Adding the Java Layer

There is a layer which adds recipes related to Java to the oe-core setup.
Define the layer version and add the repository meta data:

cd oe-core/layers

# repository version known to work with V2.0 images

# repository version known to work with V2.1 images

# repository version known to work with V2.4 images

# repository version known to work with V2.5 images

# repository version known to work with V2.6 images

# repository version known to work with V2.7 images

# repository version known to work with V2.8 images

git clone --no-checkout
cd meta-java; git checkout -b mywork $META_JAVA; cd ..

Add the layer to build/conf/bblayers.conf

--- build/conf/bblayers.conf~   2012-10-19 17:39:36.000000000 +0200
+++ build/conf/bblayers.conf    2013-04-22 18:31:58.278660259 +0200
@@ -17,6 +17,7 @@
   ${TOPDIR}/../layers/meta-openembedded/meta-multimedia \
   ${TOPDIR}/../layers/oe-tworaz/meta-lxde \
   ${TOPDIR}/../layers/meta-browser \
+  ${TOPDIR}/../layers/meta-java \

 # These layers hold machine specific content, aka Board Support Packages

Note that this will build OpenJDK without xawt, the Abstract Window Toolkit giving one framework for a graphical user interface. In order to build with xawt you will have to patch recipes-core/openjdk/openjdk-7*/icedtea-jdk-nio-use-host-cc.patch.

--- a/recipes-core/openjdk/openjdk-7-75b13/icedtea-jdk-nio-use-host-cc.patch
+++ b/recipes-core/openjdk/openjdk-7-75b13/icedtea-jdk-nio-use-host-cc.patch
@@ -49,26 +49,3 @@ Index: openjdk/jdk/make/java/nio/Makefile

  .PHONY: sources
-Index: openjdk/jdk/make/sun/Makefile
---- openjdk/jdk/make/sun/Makefile      2013-07-25 09:10:09.000000000 -0700
-+++ openjdk/jdk/make/sun/Makefile      2013-10-01 21:32:01.625839149 -0700
-@@ -55,7 +55,7 @@
-     endif
-   endif
-   HEADLESS_SUBDIR = headless
--  XAWT_SUBDIR     = xawt gtk
-+  XAWT_SUBDIR     = 
- endif
- ifeq ($(PLATFORM), macosx)
-@@ -87,7 +87,7 @@
- endif
- SUBDIRS_desktop    = audio $(RENDER_SUBDIR) image \
-                      $(LWAWT_PRE_SUBDIR) $(DISPLAY_LIBS) $(DGA_SUBDIR) $(LWAWT_SUBDIR) \
--                     jawt font jpeg cmm $(DISPLAY_TOOLS) beans 
-+                     font jpeg cmm $(DISPLAY_TOOLS) beans
- SUBDIRS_management = management
- SUBDIRS_misc       = $(ORG_SUBDIR) rmi $(JDBC_SUBDIR) tracing
- SUBDIRS_tools      = native2ascii serialver tools jconsole
\ No newline at end of file

To use the layer either add openjdk-7-jre and openjdk-7-demo packages to your image recipe or build the openjdk-7 recipe and install the openjdk-7-jre...ipk and openjdk-7-demo...ipk packages and their dependencies.

Run a demo application on the module

java -jar /usr/lib/jvm/java-7-openjdk/demo/jfc/Font2DTest/Font2DTest.jar

Working with the Package Manager

Use Angstrom Feeds

Note: Starting with BSP 3.0 we dropped Angstrom in favour of a Poky based distribution. So for BSP 3.0 based images no feeds are available.

The Angstrom distribution provides packages for certain architectures and versions of OpenEmbedded which you can test and use as follows.

Download the list of packages in the available feeds, if a configured feed is not available it will print an error message:

opkg update

Listing available packages, search the list:

opkg list
opkg list | grep jpeg

Install a package and its dependencies:

opkg install nano

Note that using 'opkg upgrade' likely leads to an unusable system. Due to the closed source X11 drivers the whole of X11 must use a matching version. opkg upgrade will update some X11 components to a non-compatible version resulting in X11 unable to start.

Note: Starting with V2.7 beta 1 we modified libc to work on Apalis/Colibri T20/T30 despite us relying on an ancient Linux kernel version from NVIDIA's L4T. Please make sure to hold on to our libc version as follows to avoid it getting replaced leading to FATAL: kernel too old:

root@colibri-t30:~# opkg flag hold libc6
Setting flags for package libc6 to hold.

What Package Provides a File

The following script can be used on a module to search what package provides a given file.

PKGS=`opkg list-installed | sed 's/^\(.*\)\s-\s.*/\1/g'`
for pkg in $PKGS
        CNT=`opkg files $pkg | grep -c $FILE`
        if [ $CNT -ne 0 ]
                echo $pkg

Further reading

The Yocto Documentation, particularly the Complete Documentation Set and the Bitbake User Manual provides a lot of information.
Two books we can recommend are:
Embedded Linux Development with Yocto Project
Embedded Linux Projects Using Yocto Project Cookbook

Webinar: Building Embedded Linux Images with the Yocto Project