Building your first image

Before building our first image, we need to decide what type of image we want to build. This recipe will introduce some of the available Yocto images and provide instructions to build a simple image.

Getting ready

Poky contains a set of default target images. You can list them by executing the following commands:

$ cd /opt/yocto/poky
$ ls meta*/recipes*/images/*.bb

A full description of the different images can be found on the Yocto Project Reference Manual. Typically, these default images are used as a base and customized for your own project needs. The most frequently used base default images are:

• core-image-minimal: This is the smallest BusyBox-, sysvinit-, and udev-based console-only image
• core-image-full-cmdline: This is the BusyBox-based console-only image with full hardware support and a more complete Linux system, including bash
• core-image-lsb: This is a console-only image that is based on Linux Standard Base compliance
• core-image-x11: This is the basic X11 Windows-system-based image with a graphical terminal
• core-image-sato: This is the X11 Window-system-based image with a SATO theme and a GNOME Mobile desktop environment
• core-image-weston: This is a Wayland protocol and Weston reference compositor-based image

You will also find images with the following suffixes:

• dev: These images are suitable for development work, as they contain headers and libraries.
• sdk: These images include a complete SDK that can be used for development on the target.
• initramfs: This is an image that can be used for a RAM-based root filesystem, which can optionally be embedded with the Linux kernel.

How to do it...

To build an image, we need to configure the MACHINE we are building it for and pass its name to BitBake. For example, for the qemuarm machine, we would run the following:

$ cd /opt/yocto/poky/qemuarm
$ MACHINE=qemuarm bitbake core-image-minimal

Or we could export the MACHINE variable to the current shell environment with the following:

$ export MACHINE=qemuarm

But the preferred and persistent way to do it is to edit the conf/local.conf configuration file to change the default machine to qemuarm:

- #MACHINE ?= "qemuarm"
+ MACHINE ?= "qemuarm"

Then you can just execute the following:

$ bitbake core-image-minimal

How it works...

When you pass a target recipe to BitBake, it first parses the following configuration files:

• conf/bblayers.conf: This file is used to find all the configured layers
• conf/layer.conf: This file is used on each configured layer
• meta/conf/bitbake.conf: This file is used for its own configuration
• conf/local.conf: This file is used for any other configuration the user may have for the current build
• conf/machine/<machine>.conf: This file is the machine configuration; in our case, this is qemuarm.conf
• conf/distro/<distro>.conf: This file is the distribution policy; by default, this is the poky.conf file

And then BitBake parses the target recipe that has been provided and its dependencies. The outcome is a set of interdependent tasks that BitBake will then execute in order.

There's more...

Most developers won't be interested in keeping the whole build output for every package, so it is recommended to configure your project to remove it with the following configuration in your conf/local.conf file:

INHERIT += "rm_work"

But at the same time, configuring it for all packages means that you won't be able to develop or debug them.

You can add a list of packages to exclude from cleaning by adding them to the RM_WORK_EXCLUDE variable. For example, if you are going to do BSP work, a good setting might be:

RM_WORK_EXCLUDE += "linux-yocto u-boot"

Remember that you can use a custom template local.conf.sample configuration file in your own layer to keep these configurations and apply them for all projects so that they can be shared across all developers.

Once the build finishes, you can find the output images on the tmp/deploy/images/qemuarm directory inside your build directory.

By default, images are not erased from the deploy directory, but you can configure your project to remove the previously built version of the same image by adding the following to your conf/local.conf file:

RM_OLD_IMAGE = "1"

You can test run your images on the QEMU emulator by executing this:

$ runqemu qemuarm core-image-minimal

The runqemu script included in Poky's scripts directory is a launch wrapper around the QEMU machine emulator to simplify its usage.