Yocto [1] is a distribution builder. The tool helps users create customized images. A custom image is particularly tempting in the embedded environment, where hardware resources are limited.

In the Beginning

Yocto builds images based on recipes. The user can modify the recipe to determine how the system should be structured – you can even specify which compiler will be used for compiling the source code.

Yocto comes with a reference distribution called Poky, which includes many ready-made recipes and is based on OpenEmbedded [2]. A tool called bitbake lets you combine the Poky layer with a hardware-specific board support layer.

One of Yocto's strengths is the many layers available from the start, including layers from most board manufacturers and also from numerous open source projects. Figure 1 shows the extensive and searchable OpenEmbedded Layer Index [3]. Yocto also has an excellent manual [4] that explains all aspects in detail.

Figure 1: The OpenEmbedded Layer Index.

The easiest way to get started with your own image is by downloading poky and meta-raspberrypi and cloning the Git repositories (Listing 1). The convention is to place all layers below poky. It is important to always clone the same branch name of each layer, e.g. Warrior. Warrior is the name of the current Poky version. The layer names usually start with meta-. In fact, Poky contains a large number of meta-* directories, because it consists of several layers.

After cloning, you need to create a suitable environment by running the following command:

source oe-init-build-env

This command also updates the PATH variable so that the Yocto tools can be called from anywhere. The command creates a build directory with a conf subdirectory. conf contains two interesting files: bblayers.conf, a list of the layers used, and local.conf, instructions for Yocto on how to build the image.

In the bblayers.conf file, edit the line with meta-yocto-bsp and enter the location of the cloned meta-raspberrypi layer. In local.conf, add the following line:

MACHINE ?= "raspberrypi3"

This line tells Yocto which hardware model the build will be for. Look online for a list of the models supported by the Raspberry Pi layer [5].

Initially Minimal

To check if everything is set up correctly, build a core-image-minimal with the following call from the build directory:

bitbake core-image-minimal

Do not be put off by the time and space required for this action. Yocto builds an image that contains a small Linux system, as well as all the tools needed to build the distribution, such as a compiler. The next build call then works incrementally; in other words, later steps do not need to rebuild the tools created in a previous step.

When the build process is done, examine the build directory. You will find four new subdirectories: cache, downloads, sstate-cache, and tmp. The most interesting of these subdirectories is tmp, in which the resulting image takes its place. Below downloads are downloaded files, and sstate-cache and cache serve the build process as cache storage. In more complex scenarios, several computers can share sstate-cache.

The tmp directory has a number of subdirectories, one of which is called deploy. The deploy directory contains all packages used for the platform and their licenses, as well as the generated image. The core-image-minimal-raspberrypi3.rpi-sdimg file in the tmp/deploy/images/raspberrypi3/ directory is a link to the last successful build.

With the help of the dd command, you can easily transfer the image to an SD card. Be very careful with dd, which overwrites the copy target. Make doubly sure that the correct output device is specified so that you don't accidentally overwrite the operating system.

After plugging in the SD card, search the dmesg output for messages from the last device added; the name of the device appears in the output. You can then specify the device name in the dd command using the of= option:

sudo dd if=core-image-minimal-raspberrypi3.rpi-sdimg of=/dev/mmcblk0 bs=1MB

The if= option refers to the input file, and bs= is the block size.

Once the microSD card is ready, you can insert it into a Raspberry Pi, connect the keyboard and monitor, and boot. Afterwards, you can log in as root without a password.

Customizing the Image

Once the basic image is created, you can customize and extend it. This is a three-step process: First, a new layer is created, then you create a recipe for a new application you wish to integrate, and then a new image recipe.

For the first step, the new layer, run the following command in the poky subdirectory:

bitbake-layers create-layer meta-lm

This command creates the new layer with a sample recipe. Then add this layer to the list in bblayers.conf, which can either be done manually or with the bitbake-layers command:

cd <I>Path/to/Build<I>
bitbake-layers add-layer ../meta-lm

The new layer doesn't do anything until you add a recipe. In the present case, the recipe is a simple small C program in "Hello World" style: lm-hello.c (Listing 2).

Create a lm-hello directory below recipes-lm and remove the sample recipe. In the new lm-hello directory, you need a lm-hello_1.0.bb file with the contents of Listing 3. The file extension bb stands for BitBake Recipe; the underscore in the filename must be followed by a version number, which will be used later when bitbake builds a package based on the recipe.

The file itself consists of variable declarations and functions. The variables SUMMARY and SECTION act as metadata describing the content. LIC_FILES_CHKSUM contains an MD5 checksum of the license file to ensure that the content has not changed since the recipe was written.

A reference to the source code follows, here in the form of a URI (SRC_URI) and a specific revision (SRCREV) of a Git repository. In this way, different versions of a recipe can exist, each referring to a different revision. The version number of the package is specified by PV; in this case, the number comes from the version identifier in the filename.

The following lines apply to settings for the build process. The lm-hello project is based on a makefile. Yocto can use a variety of build systems, including CMake, Autotools, and custom files. To support them, the file exports the variables EXTRA_OEMAKE and TARGET_CC_ARCH. These variables ensure that the right compiler with the right flags is used.

Whenever bitbake processes a recipe, it goes through a series of steps. This recipe can use default values for most of these steps, except for the installation step. It needs a custom function that first creates a bin directory (${bindir}) below the stage area (${D}), where it then installs the binary of lm-hello.

As soon as the recipe is prepared, you can test it outside an image with bitbake:

cd Path/to/Build
bitbake lm-hello

The result is a package instead of an image. This package can be found at build/tmp/deploy/rpm.

Two things are particularly noteworthy. First, even the simplest recipe always produces three packages at once: An installation package without an appendix in the filename, a development package with dev in the name, and a debug package identifiable by dbg in the name.

Second, the packages are always located in a CPU-specific subdirectory of build/tmp/deploy/rpm (in the example, this is cortexa7t2hf_neon_vfpv4) and not in a subdirectory named after the board. This means that the package can be used on all computers with the same CPU. The bitbake -g option will help you find dependencies associated with the package. (See the box entitled "Finding Dependencies.")

lm-hello cortexa7t2hf_neon_vfpv4 1.0+git0 +6c2970ab52

bitbake -g lm-hello