Creating a new layer¶

A new layer should be added in a few different scenarios:

A new Yocto project is created (such as when a new customer project needs a new layer)
An easily separable, distinct new feature, easily reusable by other projects is added
- An example of this could be a layer for a maps and navigation software, or a new graphical framework (such as Qt, or GTK, etc.)
An existing project needs to be tweaked somehow, such as changing color schemes of an existing HMI for use in an exhibition

Using Poky scripts for generating the layer¶

Poky ships with a script named yocto-layer, which is used to generate the base for a new Yocto layer, including a README file, license information, and a layer configuration file.

The Poky yocto-layer script can be found in <poky layer dir>/scripts/yocto-layer, and can be invoked in the following way:

scripts/yocto-layer create meta-mylayer 9 -o /path/to/sources/meta-mylayer

where the parameters have the following meaning:

create - Create a new layer (as opposed to listing existing layers)
meta-mylayer - Name of the layer to create. It is common practice to prefix layers with meta-.
9 - This is the layer priority. Ensure this priority is higher than the priority of the layer you are building upon. For more information on layer priorities, please see the BBFILE_PRIOTIRY variable of the BitBake user manual 1.
-o /path/to/sources/meta-mylayer - Output path of the layer. This directory will be created, and will contain the layer files.

Modifying the output of `yocto-layer`¶

yocto-layer generates a README template file, which should be filled in before the layer is used. This README will make it easier for users of your layer to know how to integrate it in their builds. In addition to this, a COPYING.MIT license file is added. The license of the layer should be updated if needed.

It is recommended to have a look in conf/layer.conf (also generated by the yocto-layer script), to verify that it looks correct. A cursory look into this file will reveal that recipes are expected to be placed in recipes-<CATEGORY> in the root of your new layer. A list of common recipe categories can be found in poky/meta/recipes.txt, where poky is the base directory of the poky git repository. If you can not find a suitable category in recipes.txt, you are free to invent your own category.

Using the new layer in a build¶

In order to include the new layer in a Yocto build, it must be specified in the bblayers.conf file used by your project. If you already have a bblayers.conf file, you may add your new layer to this file.

If you do not already have a bblayers.conf file, and if this new layer is meant to supply one, you may use the TEMPLATECONF 2 feature of the oe-init-build-env script.

Using `TEMPLATECONF`¶

TEMPLATECONF specifies a directory containing samples for local.conf and bblayers.conf. By supplying these two files with your layer, you will make it easier for developers to get going with your layer.

The conf directory on the root level of your layer is typically used for storing the TEMPLATECONF files. Below are examples of local.conf.sample and bblayers.conf.sample:

local.conf.sample¶

CONF_VERSION = "1"
DL_DIR = "${TOPDIR}/downloads"

MACHINE = "qemux86"
SDKMACHINE = "x86_64"
DISTRO = "poky"

BB_NUMBER_THREADS ?= "${@oe.utils.cpu_count()}"
PARALLEL_MAKE ?= "-j ${@oe.utils.cpu_count()}"

PACKAGE_CLASSES ?= "package_rpm"

CONF_VERSION should be increased each time build/conf changes incompatibly. Keep this until you update build/conf incompatibly.
DL_DIR specifies where to store downloaded files. Keep this as is.
MACHINE specified your target hardware. This is used to find the correct machine configuration file in your layers. qemux86 is a virtulized x86 machine. You will most likely need to change this.
SDKMACHINE specifies the target architecture to produce SDK packages for. This is typically the architecture of your workstation.
DISTRO specifies the distro config you will be using. A common option here is poky to use the poky distribution.
BB_NUMBER_THREADS and PARALLEL_MAKE are used to speed up building by using multiple CPU cores. You may keep these as is.
PACKAGE_CLASSES specifies the output package format. The example will produce rpm packages.

bblayers.conf.sample¶

LCONF_VERSION = "6"

BBPATH = "${TOPDIR}"
YOCTOROOT := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"

BBFILES  ?= ""
BBLAYERS ?= "                                            \
  ${YOCTOROOT}/sources/poky/meta                         \
  ${YOCTOROOT}/sources/poky/meta-yocto                   \
  ${YOCTOROOT}/sources/poky/meta-yocto-bsp               \
  ${YOCTOROOT}/sources/meta-mylayer                      \
  "

LCONF_VERSION one line 1 is used to indicate compatibility issues between local.conf and
bblayers.conf. You can usually leave this at "6", but if bblayers.conf changes incompatibly, then update this variable.
BBPATH on line 3 is used by BitBake to locate the top level of your Yocto build. Keep this as is.
YOCTOROOT resolves to the parent directory of your source and build directories, and is a useful way to avoid absolute paths in bblayers.conf. Keep this as is.
BBFILES should be kept as is, since no extra recipes are supplied in the bblayers.conf (this is done by each individual layer instead).
BBLAYERS is the most important variable in your bblayers.conf, this variable specifies the layers to use for your Yocto build. This variable needs to contain all layers you intend to include.

Including some software in your layer¶

See the target integration section in Yocto Project integration

Note

As always, for additional options and full documentation of BitBake concepts. See the BitBake user manual 1.

Suggested practices¶

What follows is a set of practical advice which help maintaining your own layer.

Using a variable for the `SRC_URI` base¶

When adding a new layer, it's likely that the source code of most of the components being added will be hosted in the same host. If that is the case, it might be a good idea to move the base URL of the repository group out into a separate variable defined in your layer's layer.conf file, and have the recipes use this variable when defining their SRC_URI:

conf/layer.conf¶

# Url of the git server hosting our software
MY_PROJECT_GIT_URL ?= "https://my-company.com/git"

and

Your recipe files¶

SRC_URI = "${MY_PROJECT_GIT_URL}/project.git"

This can save you some later pain if the code gets moved to a new server, because in this way you will not need to modify all the recipes.

Optionally depending on other layers¶

In some cases a layer might have recipes optional dependencies on other layers. For instance, one might want to append on a recipe for a Qt application which will only be built for some Qt specific image. Adding the recipe directly to the layer will cause bitbake to generate errors about dangling appends when building non-Qt images, which would not include any Qt layers. To mitigate this, create a layers directory containing directories named after the layers that is required, qt5 in the Qt application example. Then add all .bb and .bbappend files needed to that layer. Finally in conf/layer.conf make sure that the .bb and .bbappend files in under layers/<layer-dependency>/ are only included in BBPATH if the dependency is resolved, i.e. the layer is present. An example of this can be found in meta-bistro (see conf/layer.conf).

1(1,2): http://www.yoctoproject.org/docs/latest/bitbake-user-manual/bitbake-user-manual.html
2: http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#creating-a-custom-template-configuration-directory