The quick Yocto tutorial


Most yocto tutorials are time-consuming, as the Yocto build process itself is quite slow. This tutorial attempts to avoid this issue, by caching and sharing its precompiled results.

Yocto is a system that generates fully functional Linux images, that are ready to be deployed on computers (either mainstream x86-64 computers or tiny embedded ones).

This tutorial assumes the user is familiar and uses the Linux operating system on an x86-64 computer.

Chapter 1 - A simple build using Yocto

First you must install the prerequisites on the local computer. These steps are included in the official documentation, for most of the mainstream distributions.

Next, you must clone the “poky” repository. This contains the Yocto tools and scripts needed to generate the image. We’ll checkout the “yocto-3.1.11” tag: at the time I’m writing this, it contains the latest minor release of the “dunfell” maintenance branch.

git clone -b yocto-3.1.11

I picked the “dunfell” branch because it’s an LTS release (Long Term Support) - it’s supposed to receive updates at least until April 2024. You can pick other branch/tag from the repository, but you won’t benefit from the cache.

After the git repository is downloaded, we have to “load” its tools into the current shell environment:

source ./poky/oe-init-build-env

This commands also creates the build directory and brings Yocto-specific commands into the shell. Before starting a build we’ll also need to change a few settings in the build/conf/local.conf configuration file.

vim conf/local.conf

You can use another text-editor if you’re not familiar with vim (like nano, mcedit, gedit, etc.). In this file we need to add the mirrors and the cache of precompiled packages. Add the following lines at the end of the file:

INHERIT += "own-mirrors"
SSTATE_MIRRORS = "file://.*"

Save & exit the configuration file. Now you can start your first Yocto build.

The following command starts a “minimal” build using the default hardware target. It will generate a Linux image for x86-64 architecture, meant to be run inside a QEMU emulator.

bitbake core-image-minimal

This will be the most time-consuming step, but fortunately it’ll be over in 30 minutes (depending on you internet speed and computer performance). After it finishes, we’ll have the resulting images in build/tmp/deploy/images/qemux86-64.

To run the image, we’ll use the following command:


After the image finishes booting, you’ll get the login prompt. Use the “root” account with an empty password to log in. You can play around in the console, to check that it works as expected. When you finish, use the shutdown -h now command to close the virtual machine.

Chapter 2 - Some simple customisations

All those customisations should be done from the conf/local.conf file.

One change is to add the “vim” and “mc” packages to the default distribution image. This is done by altering the IMAGE_INSTALL variable to add the packages we are interested in. Add the following line at the end of the local.conf file.

IMAGE_INSTALL_append = " vim mc"

Another change is meant to speed up the compilation stage, by skipping the build of ptest packages. The ptest-packages are like unit-tests, meant for distribution maintainers to check that the package was generated correctly, and has no further use. Add the following line at the end of the local.conf file.

DISTRO_FEATURES_remove = "ptest"

The last change will be to add an SSH server and a package-manager to the generated image. These are called “EXTRA_IMAGE_FEATURES” and can be enabled by adding the following line at the end of the local.conf file.

EXTRA_IMAGE_FEATURES_append = " ssh-server-dropbear package-management"

Now let’s save the file and build a new image.

bitbake core-image-minimal