Adding New Device Configurations

By default, Boot to Qt for embedded Linux supports several Yocto meta layers. If you are developing software for a hardware that is not supported by default, you can add a new Yocto meta layer to your Boot to Qt for embedded Linux environment.


A new Yocto meta layer can be added to the Boot to Qt for embedded Linux environment only if you have the Yocto meta layer available for your hardware. Thus you should be familiar with the Yocto tools and the concept of recipes. For more information, see the Yocto Project documentation.

To get started, you need the following:

Creating a New Yocto Meta Layer

The integration of the new device support to Boot to Qt is done in a new meta layer. The new meta layer needs to contain information of all BSP (Board Support Package) meta layers that provide Yocto support for the selected devices. Also, the meta layer can provide required recipes and configurations that support running the Boot to Qt software stack on a target device.

To create a new blank layer, you can use the bitbake-layers command or you can use an existing Boot to Qt BSP layer as a template. For more information, see https://code.qt.io/cgit/yocto/meta-boot2qt-renesas.git/.


The Repo tool from Google is used to handle all the meta layers that are required to build Boot to Qt for the selected device. The Repo tool uses a manifest file that defines which meta layers are downloaded and which versions are used. The manifest file in a new Boot to Qt BSP layer needs to add dependencies first to the main Boot to Qt layer and then to all new layers that are needed for the device.

For example for Renesas boards, the conf/manifest.xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
  <remote fetch="git://code.qt.io/yocto" name="qt"/>
  <remote fetch="git://github.com/renesas-rcar" name="renesas"/>
  <remote fetch="git://git.linaro.org/openembedded" name="linaro"/>

  <project name="meta-boot2qt"
    <!-- link init script to the build dir -->
    <linkfile dest="b2qt-init-build-env" src="b2qt-init-build-env"/>
    <!-- add boot2qt's manifest file as a local manifest -->
    <linkfile dest=".repo/local_manifests/boot2qt.xml" src="scripts/manifest.xml"/>

<!-- add device specific layers -->
<project name="meta-renesas"
<project name="meta-linaro"

In the example, <project name="meta-boot2qt"> defines some special instructions for the meta-boot2qt layer that should be used in all new Boot to Qt BSP layers. They enable the Repo tool to correctly fetch also the meta layers that are defined in the meta-boot2qt layer's manifest file.

bblayers.conf.sample File

All the meta layers need to be included in the bitbake build. Therefore a new BSP layer should define a bblayers.conf.sample file that consist of all the meta layers used in the build. Note that some of the layers are defined by meta-boot2qt, but they still need to be part of the configurations.

For all the Renesas boards, the conf/bblayers.conf.sample file is as follows:

BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE')) + '/../..')}"
    ${BSPDIR}/sources/poky/meta \
    ${BSPDIR}/sources/poky/meta-poky \
    ${BSPDIR}/sources/meta-renesas/meta-rcar-gen3 \
    ${BSPDIR}/sources/meta-linaro/meta-optee \
    ${BSPDIR}/sources/meta-openembedded/meta-oe \
    ${BSPDIR}/sources/meta-openembedded/meta-python \
    ${BSPDIR}/sources/meta-openembedded/meta-networking \
    ${BSPDIR}/sources/meta-openembedded/meta-initramfs \
    ${BSPDIR}/sources/meta-openembedded/meta-multimedia \
    ${BSPDIR}/sources/meta-boot2qt/meta-boot2qt \
    ${BSPDIR}/sources/meta-boot2qt/meta-boot2qt-distro \
    ${BSPDIR}/sources/meta-boot2qt-renesas \
    ${BSPDIR}/sources/meta-mingw \
    ${BSPDIR}/sources/meta-qt5 \

Hardware Specific Configurations

The new Yocto meta layer may require some hardware specific configurations. The configurations can be defined to affect all the devices that are built with the layer or they can be targeted to a specific device. The configuration file in conf/distro/include/b2qt.inc can be used to define configurations that are needed by all the device variants supported by the layer. The conf/distro/include/{MACHINE}.conf files can be used to define configurations that are specific to a selected device.

Typically, a hardware specific configuration file defines boot configurations, adaptations of the BSP layer to Boot to Qt, and other configurations that might be required. For example, see QBSP Yocto Recipes and Classes.


As any other Yocto meta layer, the new Boot to Qt BSP layer can contain new recipes and .bbappend files to existing recipes.

Testing the New Yocto Meta Layer

Initializing the build environment from the new Boot to Qt BSP layer differs somewhat from the normal use of the meta-boot2qt layer. You need to use the Repo tool as follows:

repo init -u /path/to/the/new/layer/meta-boot2qt-vendor-support -m conf/manifest.xml -b <branch>
repo sync
./b2qt-init-build-env init --bsp meta-boot2qt-vendor-support

export MACHINE=<your new machine>
. ./setup-environment.sh

On the first line, you specify the location of the Boot to Qt BSP layer. It must be a git repository but it can be a local path or a network path. You also define a manifest file and a branch to use from the layer.

With repo sync the Repo tool fetches all the meta layers that are defined in the manifest and sets up the meta-boot2qt ready to be initialized using the b2qt-init-build-env command. It has an extra argument --bsp which defines the name of the Boot to Qt BSP player. The name must match the name that is used in the bblayers.conf.sample file.

The setup-environment.sh script then uses the Boot to Qt BSP layer for the bblayers.conf.sample file and also for the local.conf.sample file if it is available.

Manifest Repository

The Google Repo tool is usually used with a separate manifest repository that contains only the manifest XML file describing all the needed Yocto meta layers. Qt provides such a repository in https://code.qt.io/cgit/yocto/boot2qt-manifest.git/. This repository provides manifests for all the Boot to Qt releases, but can also have manifests for 3rd party vendor supported releases.

The manifest repository approach can be used in addition to or instead of having the manifest file directly in the new Boot to Qt BSP layer. Usage of the manifest repository is similar, only there is no need to use the ./b2qt-init-build-env script.

The manifest needs to have all the layers defined, not only the new ones. The configuration for meta-boot2qt also looks somewhat different:

<project name="meta-boot2qt"
  <linkfile dest="setup-environment.sh" src="scripts/setup-environment.sh"/>

The new Boot to Qt BSP layer also needs to be defined, with the <linkfile> configuration specifically added to support correct initialization from the Boot to Qt BSP layer:

<project name="meta-boot2qt-renesas"
  <linkfile dest="sources/templates" src="conf"/>

Initializing the build environment from the manifest repository would look like:

repo init -u git://code.qt.io/yocto/boot2qt-manifest -b renesas -m v5.14.0.xml
repo sync

export MACHINE=h3ulcb
. ./setup-environment.sh

Available under certain Qt licenses.
Find out more.