A practical guide to BitBake

If you read this tutorial you probably know already that BitBake is used as a build tool, primary by the OpenEmbedded and the Yocto project, to build Linux distributions. You might also have noticed that working with BitBake has a somewhat steep learning curve. This document was made to flatten this curve.

This document does not tell you everything about BitBake, this is in short not possible, but it tries to explain some of the fundamental functionalities that BitBake uses. Understanding these basics should help if you ever start to write your own BitBake recipes.

The tutorial shows how to create the smallest possible project and extend it step by step to show and explain how BitBake works

Thanks to Tritech for giving me some time to prepare the basic foundation for this document back in 2014. Since then, this tutorial has evolved, but without the very first version this document would not exist.

A lot of thanks to the people that report issues and typos to the issue tracker for this site!

If you find bugs, unclear sections, typos or simply have suggestions please use the issue tracker at:
https://bitbucket.org/a4z/bitbakeguide/issues
No registration required.

Also feel free to use the Disqus comment function at the end of the document.

When working with BitBake it helps to understand the following:
Basically BitBake is a Python program which, driven by user created configuration, can execute user created tasks for user specified targets, so called recipes.

The installation is very simple:

We can do this by running

This is basically the same as the yocto init script does.
The yocto init script does also creates a build folder, we will do that later.

First we check if everything works and bitbake is installed.
To do that run the following bitbake command:

It should print something like:

Beside the online docs, documentation comes also with the source code.

In a terminal, cd into the bitake-$version/doc directory and run

to create doc/bitbake-user-manual/bitbake-user-manual.html.

The official user documentation can be read in parallel to this tutorial, for example, to look up additional info if required. In any case, you should read the official docs after reading this tutorial.

The yocto project documentation has a bitbake section for the version it uses in the release.

Usually a BitBake project is organized in folders with configuration and meta data, called layers, and a build folder.

The minimal configuration will look like this:

The build directory will be our working directory, it can have what ever name you like, but it is a good practice to start the name with build.

The name meta-tutorial follows the convention of layer names. We will read more about that later.

These 4 files

need to be created next.

In a terminal change into the just created build directory, which is our working directory.
We always run bitbake from the build directory so that bitbake can find the relative conf/bblayers.conf file.

Now simply run the bitbake without any arguments.

If our setup is correct bitbake will report:

This is not very useful at all, but a good start.

And this is a good opportunity to introduce a nice and useful command flag, which is: verbose some debug output.

To see it in action run

The output you will see might look similar this one:

Since we have no recipe and target world, bitbake exits with an error. This is OK for now and we will fix this in the next chapter.

Did you notice that BitBake create a tmp directory?

BitBake caches meta data information in a directory, the cache. This help to speed up subsequent execution of commands.

We can fix the missing cache by simply adding a variable to bitbake.conf.
Therefore we edit the meta-tutorial/conf/bitbake.conf file and add at the end:

This is OK for now.

The next step is to add a recipe. This requires 2 steps:

BitBake needs to know about which recipes a layer provides.
We edit our meta-tutorial/conf/layer.conf file and tell BitBake to load all recipe files by using a common pattern.

We make now use of the variable previously defined in build/conf/bblayers.conf. A recipe file has the extension *.bb, and if we respect the common pattern we can simply add all recipes to BitBake with one line.

Usually recipes have their own folder and are collected in groups, which means put recipes that are somehow related into the same directory.

Now, since BitBake knows where to find recipes, we can actually add our first one.

Following the common pattern we create the folders meta-tutorial/recipes-tutorial/first and create the first recipe in there. Recipe-files also have a common name pattern which is {recipe}_{version}.bb.

Our first recipe will just print a log message. We put it into the first group, we will call it first, and it has the version 0.1.

So our first recipe in the first group is:

If everything is done correct we can ask bitbake to list the available recipes.

and we can run from the build directory

Now check tmp/work/first-0.1-r1/temp, there are a lot of interesting files, for example:

Let’s create a different build function and share it.
We can do this by creating a class in the tutorial layer.
Therefore we create a new file called meta-tutorial/classes/mybuild.bbclass.

As in base.class, we add a build task. It is again a simple shell function.
mybuild_do_ prefix is for following the conventions, classname_do_functionname for a task in a class.

For the addtask statement bitbake adds the do_ prefix to the function name, if it was not given. This is, why in the example above, addtask build is used. You can also write addtask do_build, for bitbake it is the same.

EXPORT_FUNCTIONS makes the build function available to users of this class.
If we did not have this line it would not be possible to override the build function later.

For now this is enough to use this class with our second recipe.

Time to build a second recipe which shall use the build task defined in mybuild.
Say that this target needs to run a patch function before the build task.
And as an additional challenge second shall also demonstrate some python usage.

Following bitbakes naming conventions we add a new recipe folder and add the file meta-tutorial/recipes-tutorial/second/second_1.0.bb to it.

The new file wll look like this.

Now we have an example that uses python functions.

Having now two recipes we are able to use and explore additional bitbake command options.

We can get information about recipes and their tasks and control what BitBake will execute.

We have now several options on running builds or specified tasks for our recipes.

You can play with the commands and see what happens.
The console output will tell you what was executed.

Adding a new layer can be done with the following steps:

The tool to explore layer configurations is the bitbake-layers command.

The bitbake-layers command has a variety of useful options, the help text says it all.

To explore, for example, which layers exists, you can run

But before this will produce any useful output for our project we need to adopt our layers configurations.

We need to add some information to our layer configuration.

We start with meta-tutorial/conf/layer.conf and add

The used variables have an excellent description in the BitBake user manual, so there is no need to repeat this text here.

The patterns should be clear, we define the layer name and use this name to suffix some other variables.
This mechanism, using user defined domain suffixes in BitBake variable names, is used by BitBake on several locations.

Next we change meta-two/conf/layer.conf in the same way.

If we now run bitbake-layers show-layers it will report

A project like yocto is composed out of very many layers. To ensure used layer are compatible with a project version, a project can define a layer series name, and layers can specify to be compatible to one, or multiple, layer series.

In practice, for a yocto project, each release defines its release name as its layer series core name. Layers that are tested for this release can add the compatibility name in its config. If a layer is added that does not have the compatibility name specified, bitbake will tell about this by showing a warning.

We can easily verify this. So far there is no core layer series name specified in our tutorial. Running, for example, bitbake-layers show-recipes will give 5 warnings.

The first 4 warning referee to the fact that the tutorial project has no layer series compatibility specified. The fifths warning is because layer two is empty, what will fix this in the next chapter. First, lets add a layer series name and specify that the 2 layers in the tutorial project are compatible.

You might have noticed that we also specified the LAYERDEPENDS_two variable in the layer.conf file of our second layer, meta-two.

By doing so we inform bitbake that this layer has a dependency to the tutorial layer. We will see in the next chapter, when we add more content to the meta-two layer, why this is the case.

To realize our configure/build chain we create a class that inherits the mybuild class and simply adds a configure task as a dependency of the build task.

We create this as another class, which we will then use to demonstrate a class and a recipe which make use of inheritance.

We can now simply use this in our third recipe and use confbuild.

This recipe inherits the confbuild class.

If we run now bitbake third it will execute the configure and build tasks for third.

An append file can be used to add functions to an existing recipe. The append happens via matching of the recipe file name. The content of the append file gets added to a recipe with the same name.

To be able to use append files the layer needs to be set up to load also them in addition to normal recipes.
Therefore we change our layer configuration and add loading of *.bbappend file to the BBFILES variable.

Now we want to reuse and extend the existing first recipe.

What we want is running a patch function before running the build task, so we need to create the corresponding bbappend file and add our changes.
Therefore we need to create the meta-two/recipes-base/first/ folder and the first_0.1.bbappend file.

If we now list the tasks for the first recipe, we will see that it also has a patch task.

Running bitbake first will now run both tasks, patch and build.

BitBake has two directives to include files.

It is worth mentioning that the include and require file name is relative to any directory in BBPATH.

Global variables can be set by the user and existing recipes can use them.

A typical recipe mostly consists only of variables that are used to set up functions defined in classes which the recipe inherits.

To have an idea how this work create

and use this class in a recipe

Running bitbake varbuild will produce log files that shows that the build task respects the variable value which the recipe has set.

This is a very typical way of using BitBake. The general task is defined in a class, like for example download source, configure, make and others, and the recipe sets the needed variables for the task.