Preparing the Yocto Project environment from scratch


The Yocto Project® (YP) is an open source collaboration project that helps developers create custom Linux-based systems regardless of the hardware architecture.

The project provides a flexible set of tools and a space where embedded developers worldwide can share technologies, software stacks, configurations, and best practices that can be used to create tailored Linux images for embedded and IOT devices, or anywhere a customized Linux OS is needed.

This tutorial will guide you through how to do an initial setup of the Yocto Project® environment and we will be targeting a Raspberry Pi 3 device.

This tutorial will also cover how to re-use existing Yocto Project environments that are available on Mender Hub which enables you to target a large variety of devices.

This is a high-level tutorial and the intention is not to cover the Yocto Project in detail. For detailed information we recommend that you read the Yocto Project Mega-Manual


To follow this tutorial, you will need:

  • A Raspberry Pi 3 device You will only need the device to test the final result and you can complete the majority of the tutorial without an device.
  • A Supported Linux Distribution: You should have a reasonably current Linux-based host system. You will have the best results with a recent release of Fedora, openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project® and officially supported
  • Required Packages for the Build Host:

To install the required packages on a Debian based distribution (Ubuntu etc) run:

sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
     build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
     xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \

Instructions for other Linux distributions (Fedora, CentOS, etc) you can find here.

Setting up the environment from scratch

The environment

There are many more concepts related to the Yocto Project®, and I will not attempt to cover all of them in this tutorial. For the curious reader there is more information here and here.

I would like to highlight two terms for the sake of this tutorial, which are explained below.


Extract from the Yocto Project Mega-Manual

"The Yocto Project’s “Layer Model” is a development model for embedded and IoT Linux creation that distinguishes the Yocto Project from other simple build systems. The Layer Model simultaneously supports collaboration and customization. Layers are repositories that contain related sets of instructions that tell the OpenEmbedded build system what to do. You can collaborate, share, and reuse layers.

Layers can contain changes to previous instructions or settings at any time. This powerful override capability is what allows you to customize previously supplied collaborative or community layers to suit your product requirements"

Majority of the content in layers is recipes. Similar to a cooking recipe which would list the ingredients and contain instructions on how to prepare the meal, the recipes in Yocto layers contain information about packages and the meta data which describes how to build and package a certain component.


Bitbake is the build engine which parses the recipes and executes tasks, and is comparable to the chef who would would read the cooking recipe and execute based on the listed instructions.

Core layers

Lets start preparing the Yocto Project environment. We will start with the core layers needed to be able to work with Yocto.

Create a workspace and change directory:

mkdir -p yocto/sources && cd yocto/sources

The first component we need is Poky. Poky is the Yocto Project reference distribution. It contains the Open-Embedded build system (BitBake and OE-Core) as well as a set of metadata to get you started building your own distribution.

git clone git:// -b warrior
  • warrior is the Yocto release that we intend to use. You can see available releases here

Note that Poky is not a layer, and instead contains a collection of layers which are prefixed with meta,

$ tree -L 1 poky/
├── bitbake
├── documentation
├── meta
├── meta-poky
├── meta-selftest
├── meta-skeleton
├── meta-yocto-bsp
├── oe-init-build-env
├── README.hardware -> meta-yocto-bsp/README.hardware
├── README.poky -> meta-poky/README.poky
├── README.qemu
└── scripts

With this done, we have the core components in place.

Raspberry Pi 3 layers

The Yocto Project’s “Layer Model” is utilized to add support for various hardware. Layers that contain support for a specific hardware are typically called “Board Support Package Layers”.

To support our target device (Raspberry Pi 3) we need to clone the meta-raspberrypi layer:

git clone -b warrior

The meta-raspberrypi layer has an additional dependency on the meta-openembedded layer:

git clone git:// -b warrior

NOTE! meta-openembedded is a collection of layers.

Initial configuration

We can now leave the sources directory:

cd ..

To prepare the build environment we can use a script provided by Poky:

. sources/poky/oe-init-build-env build
  • build is the directory where we would like to setup the build environment. You can change this to your flavor and needs, but for the sake of this tutorial I would recommend you to keep it as is.

Your shell has should have changed directory to build and the oe-init-build-env should have printed some information on your screen.

Running oe-init-build-env will setup some basics for use and include the core layers in our build environment, but to create an environment targeting Raspberry Pi 3 we need to perform some additional steps.

Below we will add a couple of layers to our environment, and by doing this we are including the recipes that are provided by these layers to our build environment. Adding a layer to an existing build environment can have various impacts and it hard to cover them all here, but in the most simple example, we are just adding to our list of available packages and does not actually impact the output unless we explicitly include packages from a certain layer.

One simple example would the meta-python layer which is included below as, adding this layer to your environment will not install any python on your device, but it does add to the list of available packages, making it possible to install e.g python3 and provided modules. More on this in the How to install packages in Yocto Project tutorial.

As already mentioned, the meta-raspberrypi layer has dependencies on layers found in meta-openembedded, so lets start with adding them.

Add meta-oe to our build environment:

bitbake-layers add-layer ../sources/meta-openembedded/meta-oe/

Add meta-multimedia to our build environment:

bitbake-layers add-layer ../sources/meta-openembedded/meta-multimedia/

Add meta-python to our build environment:

bitbake-layers add-layer ../sources/meta-openembedded/meta-python/

Add meta-networking to our build environment:

bitbake-layers add-layer ../sources/meta-openembedded/meta-networking/

Finally add meta-raspberrypi to our build environment:

bitbake-layers add-layer ../sources/meta-raspberrypi

We can list what we have added so far:

bitbake-layers show-layers

The output should be:

layer                 path                                      priority
meta                  /tmp/yocto/sources/poky/meta              5
meta-poky             /tmp/yocto/sources/poky/meta-poky         5
meta-yocto-bsp        /tmp/yocto/sources/poky/meta-yocto-bsp    5
meta-oe               /tmp/yocto/sources/meta-openembedded/meta-oe  6
meta-multimedia       /tmp/yocto/sources/meta-openembedded/meta-multimedia  6
meta-python           /tmp/yocto/sources/meta-openembedded/meta-python  7
meta-networking       /tmp/yocto/sources/meta-openembedded/meta-networking  5
meta-raspberrypi      /tmp/yocto/sources/meta-raspberrypi       9

We have not yet configured the environment to build for Raspberry Pi 3, and the default target is qemux86.

Change target to Raspberry Pi 3:

echo 'MACHINE="raspberrypi3"'>> conf/local.conf

That is it, the environment is ready to build images for Raspberry Pi 3. How to actually build images is covered in the Working with images using Yocto Project tutorial.


In this tutorial we covered the basics on how to setup Yocto Project environment from scratch, targeting Raspberry Pi 3 while also covering some basic terms such as “layers”. Hopefully this will be helpful in getting you started quickly without the need of digging to deep in to the Yocto Project internals.

For further reading I would recommend the following links:

If this tutorial was useful to you, please press like, or leave a thank you note to the contributor who put valuable time into this and made it available to you. It will be much appreciated!

1 Like