How to add a new layer and a new recipe in Yocto

Document created by gusarambula Employee on Jun 15, 2016Last modified by gusarambula Employee on Jun 28, 2016
Version 1Show Document
  • View in full screen mode

This is a simple document  explaining the basics of creating a new layer within a Yocto BSP. We will be using the latest i.MX6 Linux BSP as reference, but the same logics apply to any Yocto Project BSP including the Community BSP.

 

If you are new to Yocto it is recommended to go through the following very informative Training which is focused on the FSL Community BSP but covers the basics of Yocto step-by-step in a very clear and concise manner.

Yocto Training - HOME

 

Requirements

- L4.1.15 BSP Release for the i.MX6 family of processors installed on the host. For more information on requirements for the Host please refer to the Yocto User’s Guide available as part of the Linux BSP Document Bundle (available on the link below)

http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/i.mx-applications-processors/embedded-linux-for-i.mx-applications-processors:IMXLINUX?code=IMXLINUX

 

-tree tool for the host, to see the directory format of the different layers. You may install it with the following command:

sudo apt-get install tree

 

- We will work with the bitbake environment so this needs to be initialized in our terminal.

 

Introduction to layers in Yocto

Layers in Yocto allow us to organize the long list of providers and to easily customize for our target hardware while reusing a lot of tools already available. It also makes it easy to distribute our customizable source code trough a unique layer.

 

Once your environment is setup you can see the layers that compose the BSP using the command:

bitbake-layers show-layers

 

Show-Layers.jpg

The layers that constitute out BSP will be displayed along with the path and priority of each.

 

Layer Priority: Each layer has a priority, which is used by bitbake to decide which layer takes precedence if there are recipe files with the same name in multiple layers. A higher numeric value represents a higher priority.

 

We can see that the poky and open embedded layers have a lower priority than those than the BSP and SDK layers as the later sit on top of the former. The general layout of a BSP is shown on the image below.

 

yoctoproject-layers.png

 

If you would like to have a better look at the distinctive Layers that make up the Yocto BSP Release and the FSL Community Release please look at the Yocto Project Layers Mind Map available on the following link:

YOCTO PROJECT LAYERS MIND MAP

 

Adding an empty layer and a new recipe

There are a couple of scripts available as part of the Open embedded tools that allows for easy creation of a new layer and recipe.

 

Layers are basically a group of directories and meta data in configuration and recipe files (which contains metadata as text), so you may create these directories and meta data files by hand. However, it’s always easier to use the new layer script in order to create the required structure and then fill in with our customized configuration.

 

cd <BSP_DIR>/sources
./poky/scripts/yocto-layer create <NEW_LAYER_NAME>

 

We’ll name the new layer “new-layer” as shown below:

./poky/scripts/yocto-layer create new-layer

 

We’ll be asked to enter le layer priority, we’ll keep the default 6 but you may want a higher priority depending on your application.

You may opt for an example recipe to be created on your new layer.  We’ll leave this example recipe with the default settings.

 

New-Layer_Created.jpg

You may see the structure of the new layer by using the following command:

tree -L 4 ./meta-new-layer

 

Basic requirements of a layer

- It is not a must but it’s strongly recommended to have the name of the layer start with “meta-“, the Poky new layer script uses this naming convention.

- A README with information regarding what’s contained in the layer and any dependencies

- A COPYING file with the copyright and use notice for the hardware in the new layer.

- A conf folder which contains the layer’s configuration (.conf) files.

 

Adding the layer to our BSP

Once the layer has been created it’s necessary to add it to the list of Layers that make up the BSP so Bitbake can locate it and parse the metadata contained within it, in other words, you must make the build system aware of your new layer.

 

In order to enable your layer you need to add the layer’s path to the BBLAYERS variable in the conf/bblayers.conf file which is found on the build directory. Please note that you will need to add your layer to each build directory in which you want to use it. We can add the following line to add our new layer.

 

BBLAYERS += " ${BSPDIR}/sources/meta-new-layer "

 

After doing so we’ll see that our layer is now listed when we run show-layers in bitbake-layers.

bitbake-layers show-layers

New-Layer_Created_Added.jpg

 

Adding a new recipe

The new layer script also creates a basic recipe. It is recommended to look for recipes similar to what we need and use them as a template or starting point, as part of the benefits of Yocto is to be able to reuse a lot of open sourced code and resources.

 

If there are many versions of the same recipe the default behavior is to use the recipe contained in the highest priority layer even if it’s not the higher version of the recipe. If you would want to force bitbake to use a certain version you may use the following variable on the local.conf file.

 

PREFERRED_VERSION_recipename

 

Main requirements of a recipe:

SRC_URI which points to the location of the source code

SRC_REV if applicable it would correspond to a particular commit or branch from the source code repository

LICENSE a variable that defines the type of license to bitbake

LIC_FILES_CHKSUM should point to a file within the source tree that corresponds to the md5 check-sum of the license file so it can be verified.

 

Adding an append to a recipe

You may also select the option to have the script create an append file. The append files allow us to change an existing recipe.

The name of the file must be the same as the original recipe plus the append suffix (.bbappend) and should be located on the same path as the original recipe but in our own layer.

 

The append file can be described as a piece of code or metadata that is added to the end of the original recipe. If there are more than one append files for a particular recipe all of them will be joined in reverse priority, that is, the highest priority layer’s bbappend will be added last.

 

Appendix.
Useful References

FSL Community BSP

Yocto Training - HOME

Yocto Project Board Support Package Developer's Guide

2 people found this helpful

Attachments

    Outcomes