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
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
$ 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.
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
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.
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
bitbake-layers created the layer for us, it also created an example recipe for us named
example.bb – this is located at
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
What else does creating the new layer do for us?
Let us understand this in the next post! See you soon!