BSP 4.0.0 (deferred)

Attention: 4.0.0 is deferred, learn more on this blog post.

Prerequisites

A Yocto Project build requires intensive computing power and specific software packages.

Computer for the Yocto Project Build

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

Operating System and Build Dependencies

Yocto Project Release 3.0.3 is officialy supported by the Yocto Project. The following Linux distributions are supported and you must use one of them on your development PC to build our BSPs:

• Supported Linux distributions

You must install the required Yocto build dependencies on your host PC: - Yocto build dependencies

Attention: make sure to follow only the steps on the Yocto Mega Manual to install the build dependencies. Do not go any further into the environment setup.

Virtual Machines, Containers and Cloud Builds

Toradex does not go on about doing a Yocto Project build on a VM, Container, or a public cloud provider as AWS or Azure. Nevertheless, it is possible. Therefore if you feel like doing it, you may consider studying your options. Find some generic remarks for a simplified overview:

• VM: Since a Yocto Project build is resource-intensive, it may not be a good idea to use a VM.
• Container: it has a negligible performance penalty. Pay attention to using bind-mounts or volumes to keep persistent data; otherwise, you may lose time on every build. Containers theoretically allow you to do a Yocto Project build from a Windows PC.
• Cloud: the cloud has powerful machines that make it possible to run a full Yocto Project build in less than half an hour if you disregard setup and pre-requisites installation time. Similar to containers, you should plan how to store the output of a build. Also, don't forget to evaluate the cost of this approach!

Repo and Git

Since OpenEmbedded requires several git repositories to build our images, starting with V2.1 images, we use a utility called 'repo'. The repo manifest manages the various git repositories and their branches. (more on repo: http://code.google.com/p/git-repo/)

Install the repo bootstrap binary:

$  mkdir ~/bin
$  export PATH=~/bin:$PATH
$  curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/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 user.name "John Doe"
$ git config --global user.email johndoe@example.com

Installation

This section has two major sub-sections you have to choose:

• First-time Configuration: if you are doing a build for the first time.
• Update an Existing Configuration: if you have a build already set up and want to update it.

First-time Configuration

Create a directory for your OE-Core setup to live in and clone the meta-information:

$ mkdir ${HOME}/oe-core
$ cd ${HOME}/oe-core
$ repo init -u https://git.toradex.com/toradex-manifest.git -b LinuxImage4.0 -m default.xml
$ repo sync

Source the file export to setup the environment. On the 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. You must enter this command whenever you open a new shell session for use with OpenEmbedded.

Adjust the settings in the local.conf file

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

The MACHINE variable specifies the target device for the image. Set this variable to the module type you are planning to build for.

Our BSP layers provide the following machines:

Note: Apalis iMX8X is phased out, and it is not available for purchase anymore. The latest supported BSP and TorizonCore version is 5.4.0.

e.g. set in local.conf

    MACHINE ?= "colibri-imx6"

Note: You can explicitly override the MACHINE setting on the command line. To do that, 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 on 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 standard 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:

ACCEPT_FSL_EULA = "1"

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.

When the setup finishes, continue with the Building chapter.

Update an Existing Configuration

If you need 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

Note: e.g. use LinuxImage4.0 to update to the BSP 4.0 image version.

A list of available branches can be found in the repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/heads

$ repo init -b LinuxImage4.0
$ repo sync

Update to a Specific Version by Using its Tag

If you need to update to a specific version, a list of available tags can be found in the manifest repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/tags

As an example:

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

Known Issues During repo Setup

If your repo command succeeds, you can directly proceed with the instructions in the chapter Building below. See additional known issues notes at the end of this page.

    error: Unable to find d29dee17d9a95f2ec6b641c234870f3ccbe24102 under http://git.openembedded.org/meta-openembedded
    Cannot obtain needed blob d29dee17d9a95f2ec6b641c234870f3ccbe24102

    error: Unable to find 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f under http://git.linaro.org/git-ro/openembedded/meta-linaro.git
    Cannot obtain needed commit 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f

    fatal: loose object 8807fd141bb73d6b405eff223b3b105613bc809a (stored in /home/user/oe-core/.repo/projects/layers/meta-openembedded.git/objects/88/07fd141bb73d6b405eff223b3b105613bc809a) is corrupt
    error: http://git.openembedded.org/meta-openembedded did not send all necessary objects

$ cd .repo/projects/layers/meta-openembedded.git
$ git gc

$ rm -rf .repo/projects/layers/meta-openembedded.git
$ rm -rf .repo/project-objects/meta-openembedded.git

$ repo sync -j1

$ sudo sysctl -w net.ipv4.tcp_window_scaling=0

    <remote fetch="git://git.openembedded.org" name="oe"/>
    <remote fetch="git://git.linaro.org/openembedded" name="linaro"/>

Building

This section goes on about build steps.

Setup the Environment

Every time you open a new terminal, go to the OpenEmbedded directory and setup the environment:

$ . export

Directory Structure

OE-Core installation, configuration, and build will setup the following directory structure:

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

• layers: stores metadata, as machine and distro information, but also the recipes for building all components of an embedded Linux image.
• build: keeps build configuration, downloaded source codes, intermediate build output, generated packages (IPK, DEB, RPM), SDKs.
  • conf: this is the only subdirectory that you must preserve under build. All other subdirectories are regenerated when you start a new build if they don't exist yet.
  • deploy: the final images, ready to install (flash) into a computer on module.

Openembedded uses several places for configurations.

• General files from e.g. bitbake folder.
• Distro (from Layer/conf/distro/<distro-name>.conf)
• Machine (from Layer/conf/machine/<machine-name>.conf)
• Local Build (from <build-directory>/conf/local.conf)

Distro

A Linux distribution (often abbreviated as distro) is a software collection based upon the Linux kernel. It comprises the Linux Kernel, tools, libraries and additional software.

The following are options of distribution available on Toradex's BSP Layers for Yocto Project:

Warning: For all i.MX8 based machines we use e.g. the downstream kernel.

upstream: marks that the kernel built will be close to mainline and that the userspace uses mainlinish/opensource userspace drivers (Mostly graphical components, e.g. Vivante closed source vs. etnaviv). Note that each <machine>.conf decides what that mainline kernel will be.

PREEMPT_RT: Toradex also provides a real-time kernel recipe for use in an OpenEmbedded-Core (Yocto Project) build, and related distros that use it. See the Real-Time Linux article for more information about the PREEMPT_RT patch.

The default distro is tdx-xwayland. You can select other distro by modifying the DISTRO macro on the oe-core/buildconf/local.conf file.

See the configuration files of the distro on the layers/meta-toradex-distro/conf/distro/ directory.

Build an Image

Ater choosing a specific distro, we will select our Image. A collection of software contained in the distro the Image.

Toradex provides reference images. You can use them as a base for your distribution, don't use them as-is because they are not ready to be deployed in production (not hardened, etc.). The available image recipes are located in layers/meta-toradex-demos/recipes-images/images/, also in our Git repository - just make sure to select the correct branch!

On 4.0.0, you are recommended to use the following image:

To build the image :

$ bitbake console-tdx-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/

If you are executing an unattended build, -k tells bitbake to keep going with independent packages even after an error occurred:

$ bitbake -k <image>

Bitbake Commands

See in this section other useful bitbake commands.

Build a Single Package

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

$ bitbake samba

Build an SDK

Building an SDK for your image, pass the parameter -c populate_sdk (See also Linux SDKs)

$ bitbake <image> -c populate_sdk

Build the Linux kernel

There is a virtual recipe for building the Linux kernel for your machine regardless of its version:

$ bitbake virtual/kernel

Additional Logs

Warning: the number of messages to stdout is huge!

If you need to dig into what recipes and settings are used for, the following command outputs a bunch of environment settings and info about what is going on, use the parameter -e:

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

Available Tasks for a Recipe

If you want to see all tasks which exist for a given recipe, use the parameter -c listtasks:

$ bitbake -c listtasks virtual/kernel

Build Artifacts

The output artifacts 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/<package-arch>/*.ipk

Deploying the image on the board

The output image 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/<package-arch>/*.ipk

Get the deployable tarball image from the directory pointed in the previous section.

The image tarball, (e.g. Colibri-iMX6_LXDE-Image-Tezi_2.7-20180104.tar) has the same structure as the ones Toradex provides pre-built for download.

To update your computer on a module with a newly built image, follow the procedure documented in the Toradex Easy Installer article.

First Steps Into Your Custom Build

The Yocto Project can be quite defying and hard to use. In the following documentation, we cover some basic functionality that is likely you will have to go through during your development:

• Hello World integration into OpenEmbedded

It does not replace the official Yocto Project documentation, though. At the end of this page, we provide links to it, and you will most likely need to study it to some degree.

Failing Builds

An OpenEmbedded build sometimes fails. Below some recommended steps to follow 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 restarts building the image, e.g. if python-native fails

$ bitbake -c clean python-native
$ bitbake <image>

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

$ bitbake -c cleansstate python-native
$ bitbake <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 <image>

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

• If there are many issues with fetching sources, you could first try to download all needed sources.

$ bitbake -c fetchall <image>

Check the legacy section at the end of this page to find out about failing builds on older BSP versions.

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 openembedded.org. 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 of 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

Please refer to Java Virtual Machine.

Working with the Package Manager

Starting with BSP 3.0, we dropped the Ångström Distribution in favor of a Poky based distribution. For BSP 3.0 and newer based images, you cannot install packages from an online feed, only packages you build. However, if you use TorizonCore, you can use a container that makes it possible to use Debian feeds.

Further Reading

The Yocto Project 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

Known Issues During repo Setup

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

BSP 3.0

Prerequisites

A Yocto Project build requires intensive computing power and specific software packages.

Computer for the Yocto Project Build

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

Operating System and Build Dependencies

Yocto Project Release 2.6 is officialy supported by the Yocto Project. The following Linux distributions are supported and you must use one of them on your development PC to build our BSPs:

• Supported Linux distributions

You must install the required Yocto build dependencies on your host PC:

• Yocto build dependencies

Attention: make sure to follow only the steps on the Yocto Mega Manual to install the build dependencies. Do not go any further into the environment setup.

Virtual Machines, Containers and Cloud Builds

Toradex does not go on about doing a Yocto Project build on a VM, Container, or a public cloud provider as AWS or Azure. Nevertheless, it is possible. Therefore if you feel like doing it, you may consider studying your options. Find some generic remarks for a simplified overview:

• VM: Since a Yocto Project build is resource-intensive, it may not be a good idea to use a VM.
• Container: it has a negligible performance penalty. Pay attention to using bind-mounts or volumes to keep persistent data; otherwise, you may lose time on every build. Containers theoretically allow you to do a Yocto Project build from a Windows PC.
• Cloud: the cloud has powerful machines that make it possible to run a full Yocto Project build in less than half an hour if you disregard setup and pre-requisites installation time. Similar to containers, you should plan how to store the output of a build. Also, don't forget to evaluate the cost of this approach!

Repo and Git

Since OpenEmbedded requires several git repositories to build our images, starting with V2.1 images, we use a utility called 'repo'. The repo manifest manages the various git repositories and their branches. (more on repo: http://code.google.com/p/git-repo/)

Install the repo bootstrap binary:

$  mkdir ~/bin
$  export PATH=~/bin:$PATH
$  curl https://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/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 user.name "John Doe"
$ git config --global user.email johndoe@example.com

Installation

This section has two major sub-sections you have to choose:

• First-time Configuration: if you are doing a build for the first time.
• Update an Existing Configuration: if you have a build already set up and want to update it.

First-time Configuration

Create a directory for your OE-Core setup to live in and clone the meta-information:

$ mkdir ${HOME}/oe-core
$ cd ${HOME}/oe-core
$ repo init -u http://git.toradex.com/toradex-bsp-platform.git -b LinuxImage3.0 -m default.xml
$ repo sync

Source the file export to setup the environment. On the 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. You must enter this command whenever you open a new shell session for use with OpenEmbedded.

Adjust the settings in the local.conf file

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

The MACHINE variable specifies the target device for the image. Set this variable to the module type you are planning to build for.

Our BSP layers provide the following machines:

Note: The BSP 3.0 is a LTS Release. That does not apply for modules on Early Access and Sample state, as per our Product Change Notifications (PCN), which was the case for the iMX8 modules at the time of the BSP 3.0 Release. That said, BSP 3.0 is not recommended for our iMX8 Products - Verdin iMX8MM, Colibri iMX8X, Apalis iMX8, and Apalis iMX8X.

e.g. set in local.conf

    MACHINE ?= "colibri-imx6"

Note: You can explicitly override the MACHINE setting on the command line. To do that, 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 on 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 standard 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:

ACCEPT_FSL_EULA = "1"

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.

When the setup finishes, continue with the Building chapter.

Update an Existing Configuration

If you need 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

Note: e.g. use LinuxImageV3.0 to update to the BSP 3.0 image version.

A list of available branches is available in the repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/heads

$ repo init -b LinuxImageV3.0  -m default.xml
$ repo sync

Update to a Specific Version by Using its Tag

If you need to update to a specific version, a list of available tags is available in the manifest repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/heads

As an example:

$ repo init -b refs/tags/Apalis-iMX6_Console-Image_3.0b1.40-20190612  -m default.xml
$ repo sync

Known Issues During repo Setup

If your repo command succeeds, you can directly proceed with the instructions in the chapter Building below. See additional known issues notes at the end of this page.

    error: Unable to find d29dee17d9a95f2ec6b641c234870f3ccbe24102 under http://git.openembedded.org/meta-openembedded
    Cannot obtain needed blob d29dee17d9a95f2ec6b641c234870f3ccbe24102

    error: Unable to find 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f under http://git.linaro.org/git-ro/openembedded/meta-linaro.git
    Cannot obtain needed commit 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f

    fatal: loose object 8807fd141bb73d6b405eff223b3b105613bc809a (stored in /home/user/oe-core/.repo/projects/layers/meta-openembedded.git/objects/88/07fd141bb73d6b405eff223b3b105613bc809a) is corrupt
    error: http://git.openembedded.org/meta-openembedded did not send all necessary objects

$ cd .repo/projects/layers/meta-openembedded.git
$ git gc

$ rm -rf .repo/projects/layers/meta-openembedded.git
$ rm -rf .repo/project-objects/meta-openembedded.git

$ repo sync -j1

$ sudo sysctl -w net.ipv4.tcp_window_scaling=0

    <remote fetch="git://git.openembedded.org" name="oe"/>
    <remote fetch="git://git.linaro.org/openembedded" name="linaro"/>

Building

This section goes on about build steps.

Setup the Environment

Every time you open a new terminal, go to the OpenEmbedded directory and setup the environment:

$ ${HOME}/cd oe-core
$ . export

Directory Structure

OE-Core installation, configuration, and build will setup the following directory structure:

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

• layers: stores metadata, as machine and distro information, but also the recipes for building all components of an embedded Linux image.
• build: keeps build configuration, downloaded source codes, intermediate build output, generated packages (IPK, DEB, RPM), SDKs.
  • conf: this is the only subdirectory that you must preserve under build. All other subdirectories are regenerated when you start a new build if they don't exist yet.
  • deploy: the final images, ready to install (flash) into a computer on module.

Openembedded uses several places for configurations.

• General files from e.g. bitbake folder.
• Distro (from Layer/conf/distro/<distro-name>.conf)
• Machine (from Layer/conf/machine/<machine-name>.conf)
• Local Build (from <build-directory>/conf/local.conf)

Distro

A Linux distribution (often abbreviated as distro) is a software collection based upon the Linux kernel. It comprises the Linux Kernel, tools, libraries and additional software.

Openembedded / Yocto gets the distribution policy from a configuration file which is set by the DISTRO variable in local.conf.

This policy for example defines the libc variant, the init system, the ARM vs. THUMB instruction set, or package manager used. Also it can set distro features which the individual recipes can then evaluate to configure their build, e.g. if polkit is used/available or what display server protocol is available.

Toradex provides several distribution policy files based on the Poky one. We provide distro variants for different kernel configurations and graphics stack, summarized in the table below. Even though all distributions set the policy for the graphics stack, for example Weston/Wayland + XWayland or X11, not all images include the graphics libraries: for instance, the Console Image is a console-only image.

If you want to know exactly what is defined for each distro, follow the links as they point to the relevant configuration files.

The X11 variants are supported for the modules based on NVIDIA Tegra K1 and NXP i.MX 6/6ULL/7 SoCs. The Weston/Wayland + XWayland variants are supported for the modules based on NXP i.MX 8/8X based SoCs.

BSP 3 is the last release for which we provide binary images based on X11. From BSP 5 onwards they are replaced with Weston/Wayland + XWayland.
Learn more about the PREEMPT_RT patch on Real-Time Linux.

upstream: marks that the kernel built will be close to mainline and that the userspace uses mainlinish/opensource userspace drivers (Mostly graphical components, e.g. Vivante closed source vs. etnaviv). Note that each <machine>.conf decides what that mainline kernel will be.

rt: Toradex also provides real-time kernel flavours for use in an OpenEmbedded-Core (Yocto Project) build, and related distros that use it. See the Real-Time Linux article with Real-Time Linux article, Yocto Recipe for more information.

The default distro is tdx-xwayland. You can select other distro by modifying the DISTRO variable on the oe-core/buildconf/local.conf file.

See the configuration files of the distro on the layers/meta-toradex-distro/conf/distro/ directory.

Build an Image

A image recipe list all packages which have to be built and installed into the final root file system. The build system will take care that any known dependent package will also be installed.

Toradex provides a reference image built on top of the distribution variants. Below we list the image variants and their description and some remarkable features. If you want to know exactly all the features, follow the links as they point to the relevant Yocto recipes.

You can use them as a base for your distribution. Don't use them as-is because they are not ready to be deployed in production (not hardened, etc.). The available image recipes are located in layers/meta-toradex-demos/recipes-images/images/, also in our Git repository - just make sure to select the correct branch!

After you choose the image from the table above, you can build it:

$ bitbake <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/

If you are executing an unattended build, -k tells bitbake to keep going with independent packages even after an error occurred:

$ bitbake -k <image>

Bitbake Commands

See in this section other useful bitbake commands.

Build a Single Package

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

$ bitbake samba

Build an SDK

Building an SDK for your image, pass the parameter -c populate_sdk (See also Linux SDKs)

$ bitbake <image> -c populate_sdk

Build the Linux kernel

There is a virtual recipe for building the Linux kernel for your machine regardless of its version:

$ bitbake virtual/kernel

Additional Logs

Warning: the number of messages to stdout is huge!

If you need to dig into what recipes and settings are used for, the following command outputs a bunch of environment settings and info about what is going on, use the parameter -e:

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

Available Tasks for a Recipe

If you want to see all tasks which exist for a given recipe, use the parameter -c listtasks:

$ bitbake -c listtasks virtual/kernel

Build Artifacts

The output artifacts 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/<package-arch>/*.ipk

Install the Image on the Board

Get the deployable tarball image from the directory pointed in the previous section.

The image tarball, (e.g. Colibri-iMX6_LXDE-Image-Tezi_2.7-20180104.tar) has the same structure as the ones Toradex provides pre-built for download.

To update your computer on module with a newly built image, follow the procedure documented in the Toradex Easy Installer article.

First Steps Into Your Custom Build

The Yocto Project can be quite defying and hard to use. In the following documentation, we cover some basic functionality that is likely you will have to go through during your development:

• Hello World integration into OpenEmbedded

It does not replace the official Yocto Project documentation, though. At the end of this page, we provide links to it, and you will most likely need to study it to some degree.

Failing Builds

An OpenEmbedded build sometimes fails. Below some recommended steps to follow 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 restarts building the image, e.g. if python-native fails

$ bitbake -c clean python-native
$ bitbake <image>

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

$ bitbake -c cleansstate python-native
$ bitbake <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 <image>

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

• If there are many issues with fetching sources, you could first try to download all needed sources.

$ bitbake -c fetchall <image>

Check the legacy section at the end of this page to find out about failing builds on older BSP versions.

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 openembedded.org. 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 of 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

Please refer to Java Virtual Machine.

Working with the Package Manager

Starting with BSP 3.0, we dropped the Ångström Distribution in favor of a Poky based distribution. For BSP 3.0 and newer based images, you cannot install packages from an online feed, only packages you build. However, if you use TorizonCore, you can use a container that makes it possible to use Debian feeds.

Further Reading

The Yocto Project 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

Known Issues During repo Setup

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

BSP 2.8

Prerequisites

A Yocto Project build requires intensive computing power and specific software packages.

Computer for the Yocto Project Build

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

Operating System and Build Dependencies

Yocto Project Release 2.4 is officialy supported by the Yocto Project. The following Linux distributions are supported and you must use one of them on your development PC to build our BSPs:

• Supported Linux distributions

Warning: please note that the supported version of Ubuntu for this BSP is 16.04 LTS. If you use a newer version, there is no guarantee that things will work!

You must install the required Yocto build dependencies on your host PC:

• Yocto build dependencies

Attention: make sure to follow only the steps on the Yocto Mega Manual to install the build dependencies. Do not go any further into the environment setup.

Virtual Machines, Containers and Cloud Builds

Toradex does not go on about doing a Yocto Project build on a VM, Container, or a public cloud provider as AWS or Azure. Nevertheless, it is possible. Therefore if you feel like doing it, you may consider studying your options. Find some generic remarks for a simplified overview:

• VM: Since a Yocto Project build is resource-intensive, it may not be a good idea to use a VM.
• Container: it has a negligible performance penalty. Pay attention to using bind-mounts or volumes to keep persistent data; otherwise, you may lose time on every build. Containers theoretically allow you to do a Yocto Project build from a Windows PC.
• Cloud: the cloud has powerful machines that make it possible to run a full Yocto Project build in less than half an hour if you disregard setup and pre-requisites installation time. Similar to containers, you should plan how to store the output of a build. Also, don't forget to evaluate the cost of this approach!

Repo and Git

Since OpenEmbedded requires several git repositories to build our images, starting with V2.1 images, we use a utility called 'repo'. The repo manifest manages the various git repositories and their branches. (more on repo: http://code.google.com/p/git-repo/)

Install the repo 1 bootstrap binary:

Note: for BSP 2.8 it is recommended to install repo 1, since the BSP depends on Python 2.7, Ubuntu 16.04 LTS only has up-to Python 3.5 by default, and repo 2 depends on Python >= 3.6.

repo 2 seems to work, though it prints a warning stating that "repo: warning: your Python 3 version is no longer supported; Please upgrade to Python 3.6+.", therefore use repo 2 at your own discretion. See instructions on the tab for BSP 3 in this article.

$  mkdir ~/bin
$  export PATH=~/bin:$PATH
$  curl https://storage.googleapis.com/git-repo-downloads/repo-1 > ~/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 user.name "John Doe"
$ git config --global user.email johndoe@example.com

Installation

This section has two major sub-sections you have to choose:

• First-time Configuration: if you are doing a build for the first time.
• Update an Existing Configuration: if you have a build already set up and want to update it.

First-time Configuration

Create a directory for your OE-Core setup to live in and clone the meta-information:

$ mkdir ${HOME}/oe-core
$ cd ${HOME}/oe-core
$ repo init -u http://git.toradex.com/toradex-bsp-platform.git -b LinuxImageV2.8
$ repo sync

Source the file export to setup the environment. On the 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. You must enter this command whenever you open a new shell session for use with OpenEmbedded.

Adjust the settings in the local.conf file

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

The MACHINE variable specifies the target device for the image. Set this variable to the module type you are planning to build for.

Our BSP layers provide the following machines:

e.g. set in local.conf

    MACHINE ?= "colibri-imx6"

Note: You can explicitly override the MACHINE setting on the command line. To do that, 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 on 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 standard 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:

ACCEPT_FSL_EULA = "1"

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.

When the setup finishes, continue with the Building chapter.

Update an Existing Configuration

If you need 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

Note: e.g. use LinuxImageV2.8 to update to the BSP 2.8 image version.

A list of available branches is available in the repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/heads

$ repo init -b LinuxImageV2.8
$ repo sync

Update to a Specific Version by Using its Tag

If you need to update to a specific version, a list of available tags is available in the manifest repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/heads

As an example:

$ repo init -b refs/tags/Colibri-iMX6_LXDE-Image_2.8b7.-20200610
$ repo sync

Known Issues During repo Setup

If your repo command succeeds, you can directly proceed with the instructions in the chapter Building below. See additional known issues notes at the end of this page.

    error: Unable to find d29dee17d9a95f2ec6b641c234870f3ccbe24102 under http://git.openembedded.org/meta-openembedded
    Cannot obtain needed blob d29dee17d9a95f2ec6b641c234870f3ccbe24102

    error: Unable to find 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f under http://git.linaro.org/git-ro/openembedded/meta-linaro.git
    Cannot obtain needed commit 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f

    fatal: loose object 8807fd141bb73d6b405eff223b3b105613bc809a (stored in /home/user/oe-core/.repo/projects/layers/meta-openembedded.git/objects/88/07fd141bb73d6b405eff223b3b105613bc809a) is corrupt
    error: http://git.openembedded.org/meta-openembedded did not send all necessary objects

$ cd .repo/projects/layers/meta-openembedded.git
$ git gc

$ rm -rf .repo/projects/layers/meta-openembedded.git
$ rm -rf .repo/project-objects/meta-openembedded.git

$ repo sync -j1

$ sudo sysctl -w net.ipv4.tcp_window_scaling=0

    <remote fetch="git://git.openembedded.org" name="oe"/>
    <remote fetch="git://git.linaro.org/openembedded" name="linaro"/>

Building

This section goes on about build steps.

Setup the Environment

Every time you open a new terminal, go to the OpenEmbedded directory and setup the environment:

$ ${HOME}/cd oe-core
$ . export

Directory Structure

OE-Core installation, configuration, and build will setup the following directory structure:

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

• layers: stores metadata, as machine and distro information, but also the recipes for building all components of an embedded Linux image.
• build: keeps build configuration, downloaded source codes, intermediate build output, generated packages (IPK, DEB, RPM), SDKs.
  • conf: this is the only subdirectory that you must preserve under build. All other subdirectories are regenerated when you start a new build if they don't exist yet.
  • deploy: the final images, ready to install (flash) into a computer on module.

Openembedded uses several places for configurations.

• General files from e.g. bitbake folder.
• Distro (from Layer/conf/distro/<distro-name>.conf)
• Machine (from Layer/conf/machine/<machine-name>.conf)
• Local Build (from <build-directory>/conf/local.conf)

Distro

Toradex uses the Angstrom distribution and helps to maintain it. To learn more about features please check the meta-angstrom layer.

Build an Image

A image recipe list all packages which have to be built and installed into the final root file system. The build system will take care that any known dependent package will also be installed.

Toradex provides a reference image built on top of the distribution. Below we list the image variants and their description and some remarkable features. If you want to know exactly all the features, follow the links as they point to the relevant Yocto recipes.

You can use them as a base for your distribution. Don't use them as-is because they are not ready to be deployed in production (not hardened, etc.). The available image recipes are located in layers/meta-toradex-demos/recipes-images/images/, also in our Git repository - just make sure to select the correct branch!

After you choose the image from the table above, you can build it:

$ bitbake <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/

If you are executing an unattended build, -k tells bitbake to keep going with independent packages even after an error occurred:

$ bitbake -k <image>

Bitbake Commands

See in this section other useful bitbake commands.

Build a Single Package

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

$ bitbake samba

Build an SDK

Building an SDK for your image, pass the parameter -c populate_sdk (See also Linux SDKs)

$ bitbake <image> -c populate_sdk

Build the Linux kernel

There is a virtual recipe for building the Linux kernel for your machine regardless of its version:

$ bitbake virtual/kernel

Additional Logs

Warning: the number of messages to stdout is huge!

If you need to dig into what recipes and settings are used for, the following command outputs a bunch of environment settings and info about what is going on, use the parameter -e:

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

Available Tasks for a Recipe

If you want to see all tasks which exist for a given recipe, use the parameter -c listtasks:

$ bitbake -c listtasks virtual/kernel

Build Artifacts

The output artifacts 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/<package-arch>/*.ipk

Install the Image on the Board

Get the deployable tarball image from the directory pointed in the previous section.

The image tarball, (e.g. Colibri-iMX6_LXDE-Image-Tezi_2.7-20180104.tar) has the same structure as the ones Toradex provides pre-built for download.

To update your computer on module with a newly built image, follow the procedure documented in the Toradex Easy Installer article.

First Steps Into Your Custom Build

The Yocto Project can be quite defying and hard to use. In the following documentation, we cover some basic functionality that is likely you will have to go through during your development:

• Hello World integration into OpenEmbedded

It does not replace the official Yocto Project documentation, though. At the end of this page, we provide links to it, and you will most likely need to study it to some degree.

Failing Builds

An OpenEmbedded build sometimes fails. Below some recommended steps to follow 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 restarts building the image, e.g. if python-native fails

$ bitbake -c clean python-native
$ bitbake <image>

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

$ bitbake -c cleansstate python-native
$ bitbake <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 <image>

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

• If there are many issues with fetching sources, you could first try to download all needed sources.

$ bitbake -c fetchall <image>

Check the legacy section at the end of this page to find out about failing builds on older BSP versions.

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 openembedded.org. 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 of 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

Please refer to Java Virtual Machine.

Working with the Package Manager

Working with the Package Manager

Sometimes you may want to build a single package with OpenEmbedded and install it on a running system, instead of building and re-flashing the entire image. A package manager makes it possible and our reference images come with Opkg, a lightweight package manager when compared to those often used in desktop distros, like apt-get for example.

Note: Starting with BSP 3.0 we dropped the Ångström Distribution in favour of a Poky based distribution. So for BSP 3.0 and newer based images you cannot install packages from an online feed, only packages you build. However, if you use TorizonCore you can use a container that makes it possible to use feeds from Debian.

Install a Package

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 that are not yet installed you will have to install them as well.

# opkg install file1.ipk file2.ipk

What Package Provides a File

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

#!/bin/sh
FILE=vpu_fw_imx6q.bin
PKGS=`opkg list-installed | sed 's/^\(.*\)\s-\s.*/\1/g'`
for pkg in $PKGS
do
        CNT=`opkg files $pkg | grep -c $FILE`
        if [ $CNT -ne 0 ]
        then
                echo $pkg
        fi
done

Further Reading

The Yocto Project 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

Known Issues During repo Setup

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

BSP 2.3

Prerequisites

A Yocto Project build requires intensive computing power and specific software packages.

Computer for the Yocto Project Build

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

Operating System and Build Dependencies

Yocto Project Release 1.6 is officialy supported by the Yocto Project. The following Linux distributions are supported and you must use one of them on your development PC to build our BSPs:

• Supported Linux distributions

Warning: please note that the supported versions of Ubuntu for this BSP are 12.04 LTS and 14.04 LTS. If you use a newer version, there is no guarantee that things will work!

You must install the required Yocto build dependencies on your host PC:

• Yocto build dependencies

Attention: make sure to follow only the steps on the Yocto Mega Manual to install the build dependencies. Do not go any further into the environment setup.

Also, here are some extra dependencies you may need:

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install g++-4.8-multilib
sudo apt-get install chrpath curl dosfstools gawk g++-multilib gcc-multilib lib32z1-dev libcrypto++9:i386 libcrypto++-dev:i386 liblzo2-dev:i386 lzop libsdl1.2-dev libstdc++-4.8-dev:i386 libusb-1.0-0:i386 libusb-1.0-0-dev:i386 texinfo uuid-dev:i386
cd /usr/lib; sudo ln -s libcrypto++.so.9.0.0 libcryptopp.so.6

sudo apt-get install chrpath curl dosfstools gawk g++ gcc libcrypto++9 libcrypto++-dev liblzo2-dev lzop libsdl1.2-dev libstdc++-4.8-dev libusb-1.0-0 libusb-1.0-0-dev texinfo uuid-dev zlib1g
cd /usr/lib; sudo ln -s libcrypto++.so.9.0.0 libcryptopp.so.6

sudo yum install cryptopp-devel.i686 curl glibc-devel.i686 libstdc++-static.i686 libusb-devel.i686 libuuid-devel.i686 lzo-devel.i686 lzop zlib-devel.i686
cd /usr/lib; sudo ln -s libusb-1.0.so.0.1.0 libusb-1.0.so # fixes /usr/bin/ld: cannot find -lusb-1.0

Virtual Machines, Containers and Cloud Builds

Toradex does not go on about doing a Yocto Project build on a VM, Container, or a public cloud provider as AWS or Azure. Nevertheless, it is possible. Therefore if you feel like doing it, you may consider studying your options. Find some generic remarks for a simplified overview:

• VM: Since a Yocto Project build is resource-intensive, it may not be a good idea to use a VM.
• Container: it has a negligible performance penalty. Pay attention to using bind-mounts or volumes to keep persistent data; otherwise, you may lose time on every build. Containers theoretically allow you to do a Yocto Project build from a Windows PC.
• Cloud: the cloud has powerful machines that make it possible to run a full Yocto Project build in less than half an hour if you disregard setup and pre-requisites installation time. Similar to containers, you should plan how to store the output of a build. Also, don't forget to evaluate the cost of this approach!

Repo and Git

Since OpenEmbedded requires several git repositories to build our images, starting with V2.1 images, we use a utility called 'repo'. The repo manifest manages the various git repositories and their branches. (more on repo: http://code.google.com/p/git-repo/)

Install the repo 1 bootstrap binary:

Note: for BSP 2.3 it is recommended to install repo 1, since the BSP depends on Python 2.7, Ubuntu 14.04 LTS only has up-to Python 3.5 by default, and repo 2 depends on Python >= 3.6.

repo 2 seems to work, though it prints a warning stating that "repo: warning: your Python 3 version is no longer supported; Please upgrade to Python 3.6+.", therefore use repo 2 at your own discretion. See instructions on the tab for BSP 3 in this article.

$  mkdir ~/bin
$  export PATH=~/bin:$PATH
$  curl https://storage.googleapis.com/git-repo-downloads/repo-1 > ~/bin/repo
$  chmod a+x ~/bin/repo

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 user.name "John Doe"
$ git config --global user.email johndoe@example.com

Installation

This section has two major sub-sections you have to choose:

• First-time Configuration: if you are doing a build for the first time.
• Update an Existing Configuration: if you have a build already set up and want to update it.

First-time Configuration

Create a directory for your OE-Core setup to live in and clone the meta-information:

$ mkdir ${HOME}/oe-core
$ cd ${HOME}/oe-core
$ repo init -u http://git.toradex.com/toradex-bsp-platform.git -b LinuxImageV2.3
$ repo sync

Source the file export to setup the environment. On the 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. You must enter this command whenever you open a new shell session for use with OpenEmbedded.

Adjust the settings in the local.conf file

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

The MACHINE variable specifies the target device for the image. Set this variable to the module type you are planning to build for.

Our BSP layers provide the following machines:

e.g. set in local.conf

    MACHINE ?= "colibri-imx6"

Note: You can explicitly override the MACHINE setting on the command line. To do that, 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 on 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 standard 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:

ACCEPT_FSL_EULA = "1"

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.

When the setup finishes, continue with the Building chapter.

Update an Existing Configuration

If you need 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

Note: e.g. use LinuxImageV2.3 to update to the BSP 2.3 image version.

A list of available branches is available in the repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/heads

$ repo init -b LinuxImageV2.3
$ repo sync

Update to a Specific Version by Using its Tag

If you need to update to a specific version, a list of available tags is available in the manifest repository: https://git.toradex.com/cgit/toradex-bsp-platform.git/refs/heads

As an example:

$ repo init -b repo init -b refs/tags/Colibri_T20_LinuxImageV2.3_20150320
$ repo sync

Known Issues During repo Setup

If your repo command succeeds, you can directly proceed with the instructions in the chapter Building below. See additional known issues notes at the end of this page.

    error: Unable to find d29dee17d9a95f2ec6b641c234870f3ccbe24102 under http://git.openembedded.org/meta-openembedded
    Cannot obtain needed blob d29dee17d9a95f2ec6b641c234870f3ccbe24102

    error: Unable to find 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f under http://git.linaro.org/git-ro/openembedded/meta-linaro.git
    Cannot obtain needed commit 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f

    fatal: loose object 8807fd141bb73d6b405eff223b3b105613bc809a (stored in /home/user/oe-core/.repo/projects/layers/meta-openembedded.git/objects/88/07fd141bb73d6b405eff223b3b105613bc809a) is corrupt
    error: http://git.openembedded.org/meta-openembedded did not send all necessary objects

$ cd .repo/projects/layers/meta-openembedded.git
$ git gc

$ rm -rf .repo/projects/layers/meta-openembedded.git
$ rm -rf .repo/project-objects/meta-openembedded.git

$ repo sync -j1

$ sudo sysctl -w net.ipv4.tcp_window_scaling=0

    <remote fetch="git://git.openembedded.org" name="oe"/>
    <remote fetch="git://git.linaro.org/openembedded" name="linaro"/>

Building

This section goes on about build steps.

Setup the Environment

Every time you open a new terminal, go to the OpenEmbedded directory and setup the environment:

$ ${HOME}/cd oe-core
$ . export

Directory Structure

OE-Core installation, configuration, and build will setup the following directory structure:

    oe-core/
    +-- build
    ¦   +-- conf
    ¦   +-- downloads
    ¦   +-- out-eglibc
    ¦       +-- deploy
    ¦   +-- sstate-cache
    ¦   +-- deploy
    +-- stuff
        +-- meta-browser
        +-- meta-freescale
        (... other layers)
        +-- openembedded-core

• stuff: stores metadata, as machine and distro information, but also the recipes for building all components of an embedded Linux image.
• build: keeps build configuration, downloaded source codes, intermediate build output, generated packages (IPK, DEB, RPM), SDKs.
  • conf: this is the only subdirectory that you must preserve under build. All other subdirectories are regenerated when you start a new build if they don't exist yet.
  • out-eglibc/deploy: the final images, ready to install (flash) into a computer on module.

Openembedded uses several places for configurations.

• General files from e.g. bitbake folder.
• Distro (from Layer/conf/distro/<distro-name>.conf)
• Machine (from Layer/conf/machine/<machine-name>.conf)
• Local Build (from <build-directory>/conf/local.conf)

Distro

Toradex uses the Angstrom distribution and helps to maintain it. To learn more about features please check the meta-angstrom layer.

Build an Image

A image recipe list all packages which have to be built and installed into the final root file system. The build system will take care that any known dependent package will also be installed.

Toradex provides a reference image built on top of the distribution. Below we list the image variants and their description and some remarkable features. If you want to know exactly all the features, follow the links as they point to the relevant Yocto recipes.

You can use them as a base for your distribution. Don't use them as-is because they are not ready to be deployed in production (not hardened, etc.). The available image recipes are located in layers/meta-toradex-demos/recipes-images/images/, also in our Git repository - just make sure to select the correct branch!

After you choose the image from the table above, you can build it:

$ bitbake <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/

If you are executing an unattended build, -k tells bitbake to keep going with independent packages even after an error occurred:

$ bitbake -k <image>

Bitbake Commands

See in this section other useful bitbake commands.

Build a Single Package

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

$ bitbake samba

Build an SDK

Building an SDK for your image, pass the parameter -c populate_sdk (See also Linux SDKs)

$ bitbake <image> -c populate_sdk

Build the Linux kernel

There is a virtual recipe for building the Linux kernel for your machine regardless of its version:

$ bitbake virtual/kernel

Additional Logs

Warning: the number of messages to stdout is huge!

If you need to dig into what recipes and settings are used for, the following command outputs a bunch of environment settings and info about what is going on, use the parameter -e:

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

Available Tasks for a Recipe

If you want to see all tasks which exist for a given recipe, use the parameter -c listtasks:

$ bitbake -c listtasks virtual/kernel

Build Artifacts

The output artifacts can be found here:

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

Install the Image on the Board

Get the deployable tarball image from the directory pointed in the previous section.

To update your computer on module with a newly built image, follow the procedure documented in the articles:

• Flashing Embedded Linux to Tegra Modules
• Flashing Embedded Linux to iMX6 Modules
• Flashing Embedded Linux to Vybrid Modules

First Steps Into Your Custom Build

The Yocto Project can be quite defying and hard to use. In the following documentation, we cover some basic functionality that is likely you will have to go through during your development:

• Hello World integration into OpenEmbedded

It does not replace the official Yocto Project documentation, though. At the end of this page, we provide links to it, and you will most likely need to study it to some degree.

Failing Builds

An OpenEmbedded build sometimes fails. Below some recommended steps to follow 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 restarts building the image, e.g. if python-native fails

$ bitbake -c clean python-native
$ bitbake <image>

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

$ bitbake -c cleansstate python-native
$ bitbake <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 <image>

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

• If there are many issues with fetching sources, you could first try to download all needed sources.

$ bitbake -c fetchall <image>

Check the legacy section at the end of this page to find out about failing builds on older BSP versions.

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 openembedded.org. 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 of 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

Please refer to Java Virtual Machine.

Working with the Package Manager

Sometimes you may want to build a single package with OpenEmbedded and install it on a running system, instead of building and re-flashing the entire image. A package manager makes it possible and our reference images come with Opkg, a lightweight package manager when compared to those often used in desktop distros, like apt-get for example.

Note: Starting with BSP 3.0 we dropped the Ångström Distribution in favour of a Poky based distribution. So for BSP 3.0 and newer based images you cannot install packages from an online feed, only packages you build. However, if you use TorizonCore you can use a container that makes it possible to use feeds from Debian.

Install a Package

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 that are not yet installed you will have to install them as well.

# opkg install file1.ipk file2.ipk

What Package Provides a File

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

#!/bin/sh
FILE=vpu_fw_imx6q.bin
PKGS=`opkg list-installed | sed 's/^\(.*\)\s-\s.*/\1/g'`
for pkg in $PKGS
do
        CNT=`opkg files $pkg | grep -c $FILE`
        if [ $CNT -ne 0 ]
        then
                echo $pkg
        fi
done

Further Reading

The Yocto Project 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

Known Issues During repo Setup

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

Legacy

For our Linux image starting from V2.0 we use OpenEmbedded-Core.

The directory structure presented on the previous section 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.

Yocto Build Dependencies

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

Attention: the Yocto Project already documents the required dependencies and supported OS for a specific Yocto version. We stopped to document it ourselves and instead we point to the official Yocto docs. This section is kept solely for reference, but it is not updated and you are recommended to not follow it.

sudo dnf install systemd-container
sudo dnf -y --releasever=27 --nogpg --installroot=<path to containers rootfs> --disablerepo='*' --enablerepo=fedora install systemd dnf fedora-release vim-minimal
sudo systemd-nspawn -D <path to containers rootfs>
dnf update
dnf groupinstall "Development Libraries" "Development Tools"
dnf install SDL-devel bzip2 ccache chrpath gcc-c++ patch tar texinfo wget which xterm python git make diffstat cpio file perl-Thread-Queue
dnf install cryptopp-devel.i686 glibc-devel.i686 libusb-devel.i686 libuuid-devel.i686 lzo-devel.i686 lzop zlib-devel.i686
dnf install findutils perl-bignum
dnf install libstdc++-static libstdc++-static.i686 --best
cd /lib; ln -s libusb-1.0.so.0.1.0 libusb-1.0.so
useradd <username>

sudo systemd-nspawn -bD <path to containers rootfs>

sudo dnf install cryptopp-devel.i686 glibc-devel.i686 libusb-devel.i686 libuuid-devel.i686 lzo-devel.i686 lzop zlib-devel.i686
sudo dnf install libstdc++-static libstdc++-static.i686 --best
sudo dnf install perl-bignum # fixes Can't locate bigint.pm
cd /lib; ln -s libusb-1.0.so.0.1.0 libusb-1.0.so # fixes /usr/bin/ld: cannot find -lusb-1.0

sudo dnf -y --releasever=21 --nogpg --installroot=<path to containers rootfs> --disablerepo='*' --enablerepo=fedora install systemd dnf fedora-release vim-minimal
sudo systemd-nspawn -D <path to containers rootfs>
dnf update
dnf groupinstall "Development Libraries" "Development Tools"
dnf install SDL-devel bzip2 ccache chrpath gcc-c++patch tar texinfo wget which xterm
dnf install cryptopp-devel.i686 glibc-devel.i686 libstdc++-static.i686 libusb-devel.i686 libuuid-devel.i686 lzo-devel.i686 zlib-devel.i686
cd /lib; ln -s libusb-1.0.so.0.1.0 libusb-1.0.so
useradd <username>

sudo systemd-nspawn -D <path to containers rootfs> -u <username>

sudo yum install cryptopp-devel.i686 curl glibc-devel.i686 libstdc++-static.i686 libusb-devel.i686 libuuid-devel.i686 lzo-devel.i686 lzop zlib-devel.i686
cd /usr/lib; sudo ln -s libusb-1.0.so.0.1.0 libusb-1.0.so # fixes /usr/bin/ld: cannot find -lusb-1.0

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install g++-5-multilib
sudo apt-get install curl dosfstools gawk wget git-core diffstat unzip texinfo g++-multilib gcc-multilib build-essential chrpath socat cpio python python3 python3-pip python3-pexpect python3-git python3-jinja2 lib32z1-dev libcrypto++6:i386 libcrypto++-dev:i386 liblzo2-dev:i386 lzop xz-utils debianutils iputils-ping libegl1-mesa xterm libsdl1.2-dev libstdc++-5-dev:i386 libusb-1.0-0:i386 libusb-1.0-0-dev:i386 uuid-dev:i386

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install g++-5-multilib
sudo apt-get install curl dosfstools gawk g++-multilib gcc-multilib lib32z1-dev libcrypto++9v5:i386 libcrypto++-dev:i386 liblzo2-dev:i386 lzop libsdl1.2-dev libstdc++-5-dev:i386 libusb-1.0-0:i386 libusb-1.0-0-dev:i386 uuid-dev:i386 texinfo chrpath
cd /usr/lib; sudo ln -s libcrypto++.so.9.0.0 libcryptopp.so.6

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install g++-4.9-multilib
sudo apt-get install curl dosfstools gawk g++-multilib gcc-multilib lib32z1-dev libcrypto++9v5:i386 libcrypto++-dev:i386 liblzo2-dev:i386 lzop libsdl1.2-dev libstdc++-4.9-dev:i386 libusb-1.0-0:i386 libusb-1.0-0-dev:i386 uuid-dev:i386 texinfo chrpath
cd /usr/lib; sudo ln -s libcrypto++.so.9.0.0 libcryptopp.so.6

sudo apt-get install curl dosfstools gawk g++ gcc libcrypto++9v5 libcrypto++-dev liblzo2-dev lzop libsdl1.2-dev libstdc++-4.9-dev libusb-1.0-0 libusb-1.0-0-dev uuid-dev zlib1g
cd /usr/lib; sudo ln -s libcrypto++.so.9.0.0 libcryptopp.so.6

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install g++-4.8-multilib
sudo apt-get install chrpath curl dosfstools gawk g++-multilib gcc-multilib lib32z1-dev libcrypto++9:i386 libcrypto++-dev:i386 liblzo2-dev:i386 lzop libsdl1.2-dev libstdc++-4.8-dev:i386 libusb-1.0-0:i386 libusb-1.0-0-dev:i386 texinfo uuid-dev:i386
cd /usr/lib; sudo ln -s libcrypto++.so.9.0.0 libcryptopp.so.6

sudo apt-get install chrpath curl dosfstools gawk g++ gcc libcrypto++9 libcrypto++-dev liblzo2-dev lzop libsdl1.2-dev libstdc++-4.8-dev libusb-1.0-0 libusb-1.0-0-dev texinfo uuid-dev zlib1g
cd /usr/lib; sudo ln -s libcrypto++.so.9.0.0 libcryptopp.so.6

Known Issues During repo Setup

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

error: Cannot fetch meta-openembedded.git (GitError: --force-sync not enabled; cannot overwrite a local work tree. If you're comfortable with the possibility of losing the work tree's git metadata, use `repo sync --force-sync stuff/meta-openembedded` to proceed.)

cd ../oe-core
repo sync --force-sync stuff/meta-openembedded

cd stuff/meta-toradex
git fetch trdx
git checkout 789432b52eff002a9e9bce2b28e3ea54a44168fe

cd stuff/openembedded-core
git fetch oe
git cherry-pick -x 51008a21629561c8d40a7addcddde6c2be176e90

cd stuff/meta-toradex
git fetch trdx
git checkout 60485153fa555caf71a2f92a7eb7585b8d1d7f27

cd stuff/meta-linaro
cat <<EOF > eglibc.patch
diff --git a/meta-linaro-toolchain/recipes-core/eglibc/eglibc_linaro-2.19.bb b/meta-linaro-toolchain/recipes-core/eglibc/eglibc_linaro-2.19.bb
index b85181b..990d650 100644
--- a/meta-linaro-toolchain/recipes-core/eglibc/eglibc_linaro-2.19.bb
+++ b/meta-linaro-toolchain/recipes-core/eglibc/eglibc_linaro-2.19.bb
@@ -6,7 +6,7 @@ MMYY = "14.04"
 RELEASE = "20\${MMYY}"
 PR = "r\${RELEASE}"

-SRC_URI = "http://cbuild.validation.linaro.org/snapshots/eglibc-\${PV}-\${RELEASE}.tar.bz2 \\
+SRC_URI = "https://snapshots.linaro.org/openembedded/sources/eglibc-\${PV}-\${RELEASE}.tar.bz2 \\
            file://eglibc-svn-arm-lowlevellock-include-tls.patch \\
            file://IO-acquire-lock-fix.patch \\
            file://mips-rld-map-check.patch \\
EOF
patch -p1 < eglibc.patch

DISTRO_FEATURES_append_arm = " ld-is-gold"

Can't use 'defined(@array)' (Maybe you should just omit the defined()?) at /home/user/oe-core_V2.5/build/out-glibc/work/armv7at2hf-vfp-neon-angstrom-linux-gnueabi/gtk+/2.24.25-r0/build/demos/gtk-demo/geninclude.pl line 43.

cd stuff/openembedded-core
git cherry-pick -x 5c20144fd6d936becc419ae4e4b091b5bbfd2f1c
git cherry-pick -x 00c501866a2de14f8e1c1c99a0ca36b799f8b123

Legacy Image Format

Attention: We dropped building legacy images 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 'update.sh -h' and then '-m' parameter to force a module type. For older images add a line so that our update.sh 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"

Failing Builds

For builds, before V2.1 I had at least one installation where bitbake consistently failed on some task because there was garbage in the ccache. Deleting $HOME/.ccache helped, alternatively you can disable the feature by commenting the CCACHE line in build/conf/local.conf. Also deleting the parser cache helps sometimes. $OEHOME/output/cache

The native readline build fails on some machines. An issue for which I do not have a clean solution. The workaround which works is to install readline on the build machine and add an entry to build/conf/local.conf that it need not be built: ASSUME_PROVIDED += "readline-native"

Working with the Package Manager

Using Ångström Distribution Feeds - Up To BSP 2.8

Note: Starting with BSP 3.0 we dropped the Ångström Distribution in favour of a Poky based distribution. So for BSP 3.0 based images, no feeds are available.

The Ångström 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.