Setting up the Build Environment

Supported Operating Systems

The Yocto Project website outlines the following requirements:

  • 50 Gbytes of free disk space
  • Runs a supported Linux distribution (i.e. recent releases of Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux distributions that support the Yocto Project, see the „Supported Linux Distributions“ section in the Yocto Project Reference Manual. For detailed information on preparing your build host, see the „Preparing the Build Host“ section in the Yocto Project Development Tasks Manual.
  • Git or greater
  • tar 1.27 or greater
  • Python 3.4.0 or greater.

Note that Yocto is not compatible with the Windows Subsystem for Linux (WSL)


Everything needed to build a basic image can be downloaded from the yocto project git server. Yocto projects are self contained and can therefore live anywhere on the filesystem. This guide will assume that everything related to the build will live in a directory called yocto in the ubuntu user's home directory, i.e. /home/ubuntu/yocto/.

mkdir  ~/yocto
cd ~/yocto
git clone -b <release> git://

Where <release> corresponds to the branch or tag needed. At the time of writing the latest release is yocto-3.0.1. Note that while checking out a branch also works, checking out a particular tag is recommended to produce reproducible builds. Check the poky repository for all available releases .

Set up

Bitbake, yocto's build system, let's the user pick their own directory to store all output in. This includes (among others) downloads, packages configuration files, and the final image(s). This means that the same poky download can be used for multiple independent builds (for different hardware for example). The first thing to do is to create that directory, usually called build, inside the yocto directory.

mkdir ~/yocto/build

Now the yocto directory should contain poky and build. Next, initialize the build environment using the following command (we are still in ~/yocto):

. poky/oe-init-env build

Note the space between the dot and poky. This should result in output similar to the sample below.

### Shell environment set up for builds. ###

You can now run 'bitbake <target>'

Common targets are:

You can also run generated qemu images with a command like 'runqemu qemux86'

Other commonly useful commands are:
 - 'devtool' and 'recipetool' handle common recipe tasks
 - 'bitbake-layers' handles common layer tasks
 - 'oe-pkgdata-util' handles common target package tasks

Adding Additional Layers

Often it is necessary to add further layers to the build to customize the resulting image, or buil dofr specific hardware (a specific MACHINE). For example, to use the NTB/OST images, the meta-ntb layers need to be added to the build.

While layers can be included from any directory, it makes sense to keep all the layers in one place. In this case they will be kept in the parent directory, next to the poky folder.

To clone meta-ntb

# get out of 'build' directory
cd ..
# clone layers
git clone git:// -b <yocto-release>
git clone

Note that many layer repositories will have different branches for different yocto releases. For example, meta-openembedded has a dunfell branch to be used with the dunfell yocto releases.

Build Configuration

When running oe-init-env a conf folder is created inside the build directory: build/conf in this case. This folder contains two files: local.conf and bblayers.conf.

Adding Custom Layers

bblayers.conf contains the full path of all layers that are referenced during the build inside the BBLAYERS variable. If additional layers are needed, they need to be added to the list for bitbake to find them and their recipes.

This is the place to add the path to the custom layers that were cloned previosly (if any). Some repositories such as meta-ntb contain multiple layers. In these cases each layers must be added seperately. For example, meta-ntb/meta-ntb and meta-ntb/meta-ntb-ros rather than just meta-ntb as shown below.

   /home/ubuntu/yocto/poky/meta \
   /home/ubuntu/yocto/poky/meta-poky \
   /home/ubuntu/yocto/poky/meta-yocto-bsp \
   /home/ubuntu/vanilla-yocto/meta-openembedded/meta-oe \
   /home/ubuntu/vanilla-yocto/meta-ntb/meta-ntb \
   /home/ubuntu/vanilla-yocto/meta-ntb/meta-ntb-ros \


local.conf contains configuration settings and modifications relevant to this build. The most common setting to set is the MACHINE, i.e. the hardware platform you want to build the image for. By default yocto builds for genericx86_64, which should run on a normal (64bit) PC. Another possibility is to add additional packages to the image using CORE_IMAGE_INSTALL_append.

Another thing that may come in handy is manually setting the kernel used. This can be achieved by setting PREFERRED_PRVIDER_virtual/kernel to the desired kernel. By default, yocto provides a kernel as linux-yocto.

For a typical build using meta-ntb the following should be appended to local.conf

MACHINE = "<machine>"
DISTRO = "ntb-distro"

Additionally, meta-ntb uses the NTB_DEVBUILD Variable to build a development image rather than a production image. A development image can be built by adding NTB_DEVBUILD = „1“ to local.conf. Otherwise (including NTB_DEVBUILD not being set at all), a production image will be built.

Runnning a Build

Packages and images can be built by running bitbake <recipe-name>. Note that images are just recipes as far as bitbake is concerned. To build the default image run:

bitbake core-image-minimal

Bitbake also has the ability to run commands that are part of a recipe. For example, to remove build output from a recipe run

bitbake <recipe-name> -c clean

-c tells bitbake to only run a particular command rather than building the package(s) in the recipe. In this case that command is clean, another example is fetch to fetch the necessary sources required by the recipe.