Yocto: Part 5 – Creating & adding a new layer to your image

In the previous posts about Yocto, we talked about a variety of things like what Yocto is, how you download it, build base images and so on. If these topics interest you, please go and check out these posts here.

• Part 1 – A Definitive Introduction
• Part 2 – Setting up Ubuntu host
• Part 3 – Build & run your first ever image!
• Part 4 – Building a basic image for Raspberry Pi

In this post, we cover a rather basic but very important topic that is often the starting point for you to customize your image. We talk about creating and adding a new layer to your image.

Layers – A refresher

In the introduction, we talked about the layered nature of the Yocto build system and how it enables maximum re-use of software as well as allows you to easily migrate from one hardware platform to the other. The idea of layers is that you can easily bundle your secret sauce (read “your own source code”) in your own layer as well as over-ride some configurations for the same recipe sitting in a layer below yours. For example – you could modify the packages that get installed in a base image that already exists in meta-oe by adding your software to it or customize the linux kernel configuration for a particular image and so on.

We will now learn how to create our own layer.

Creating a new layer

The easiest and the most recommended method to create a new layer is using the bitbake-layers script. This script is already available for you once you have sourced the oe-build-init-env script inside poky/.

The bitbake-layers script is pretty versatile and does a lot more than just creating the layer. To see what it can do, we will first init our build environment and then look at the help documentation available to us. These commands have to be run while inside poky/ folder.

$ source oe-init-build-env
$ bitbake-layers --help

You should see output as below.

NOTE: Starting bitbake server...
usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ...

BitBake layers utility

optional arguments:
  -d, --debug           Enable debug output
  -q, --quiet           Print only errors
  -F, --force           Force add without recipe parse verification
  --color COLOR         Colorize output (where COLOR is auto, always, never)
  -h, --help            show this help message and exit

subcommands:
  <subcommand>
    add-layer           Add one or more layers to bblayers.conf.
    remove-layer        Remove one or more layers from bblayers.conf.
    flatten             flatten layer configuration into a separate output directory.
    show-layers         show current configured layers.
    show-overlayed      list overlayed recipes (where the same recipe exists in another layer)
    show-recipes        list available recipes, showing the layer they are provided by
    show-appends        list bbappend files and recipe files they apply to
    show-cross-depends  Show dependencies between recipes that cross layer boundaries.
    layerindex-fetch    Fetches a layer from a layer index along with its dependent layers, and adds them to conf/bblayers.conf.
    layerindex-show-depends
                        Find layer dependencies from layer index.
    create-layer        Create a basic layer

Use bitbake-layers <subcommand> --help to get help on a specific command

As you can see, this script can help us not just to create a layer but also to add a layer to our configuration, remove a layer from the build configuration, show the currently added layers and also a few more useful operations like showing us the recipes that are a part of the build or from a particular layer and so on.

Let us check what layers are currently a part of our configuration.

$ bitbake-layers show-layers

This should print out an output something like below.

NOTE: Your output may be different depending on the builds you have done in the past. This is just an indicative output.

NOTE: Starting bitbake server...
layer                 path                                      priority
==========================================================================
meta                  /home/shashank/code/yocto/poky/meta       5
meta-poky             /home/shashank/code/yocto/poky/meta-poky  5
meta-yocto-bsp        /home/shashank/code/yocto/poky/meta-yocto-bsp  5

Step 1 – Choose the location for your layer

If you have already read Part 2 and Part 3, you already know that our folder path looks something like this. However, if yours is different, just make the necessary changes in the below commands so that your paths are consistent.

• yocto/
  • meta-openembedded
  • meta-raspberrypi
  • poky/
    • bitbake
    • build
    • meta
    • ….

It is generally to good idea to have your own layer placed inside the yocto/ folder such that is it along other non-poky layers that you have added. Also, it is considered good practice to have the layer name start with meta- although it is not mandatory.

We will create a layer named meta-ke inside yocto/ folder.

Step 2 – Create the layer

Suppose, we are currently in the poky/build/ directory. We will execute the below commands.

$ bitbake-layers create-layer ../../meta-ke

The folder structure should now look like this.

• yocto/
  • meta-openembedded
  • meta-raspberrypi
  • meta-ke
  • poky/
    • bitbake
    • build
    • meta
    • ….

Adding the layer to build configuration

Now that we have successfully created our new layer, let us now add it to our configuration. In the future, we shall add our own recipes to this layer and create our own customized images. More on this later.

We shall use the bitbake-layers script again for adding this layer to our build configuration.

$ bitbake-layers add-layer ../../meta-ke

To confirm that this addition was successful, we can run the bitbake-layers script with the show-layers argument. We should see our layer added to the output.

layer                 path                                      priority
==========================================================================
meta                  /home/shashank/code/yocto/poky/meta       5
meta-poky             /home/shashank/code/yocto/poky/meta-poky  5
meta-yocto-bsp        /home/shashank/code/yocto/poky/meta-yocto-bsp  5
meta-ke               /home/shashank/code/yocto/meta-ke         6

Try building the recipe inside new layer

When bitbake-layers created the layer for us, it also created an example recipe for us named example.bb – this is located at meta-ke/recipes-example/example/.

Let us now try to bake this recipe. If all goes well, we should see build stage prints. A successful bake tells us that the layer operations went well and we can now use this layer for all our image builds in the future!

$ bitbake example

You should see output like below during the build process. If you had already done an image build in the past, this should be relatively quick.

NOTE: Executing Tasks
***********************************************
*                                             *
*  Example recipe created by bitbake-layers   *
*                                             *
***********************************************

This emanates from the do_display_banner() function inside example.bb.

Hmm… how did bitbake know what to do?!

How does bitbake know what example is?

Why did you not need to specify which layer bitbake should look for to locate the recipe named example ?

What else does creating the new layer do for us?

Let us understand this in the next post! See you soon!