Setup and Building

Supported Operating Systems

The Yocto Project website outlines the following requirements:

  • At least 90 Gbytes of free disk space, though much more will help to run multiple builds and increase performance by reusing build artifacts.
  • At least 8 Gbytes of RAM, though a modern modern build host with as much RAM and as many CPU cores as possible is strongly recommended to maximize build performance.
  • 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.28 or greater
  • Python 3.8.0 or greater.
  • gcc 8.0 or greater.
  • GNU make 4.0 or greater

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


Everything necessary 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 desired branch or tag. At the time of writing the latest LTS release is kirkstone. 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 .


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-build-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 build for specific hardware (a specific MACHINE). For example, to use the OST images, the meta-ost 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-ost

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

Note that many layer repositories will have different branches for different yocto releases. For example, meta-openembedded has a kirstone branch to be used with the kirstone yocto releases. Note: use the kirkstone branch and not a tag.

Build Configuration

When running oe-init-env a conf folder was 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 previously (if any). Some repositories such as meta-ost contain multiple layers. In these cases each layers must be added separately. For example, meta-ost/meta-ost and meta-ost/meta-ost-ros rather than just meta-ost as shown below.

   /home/ubuntu/yocto/poky/meta \
   /home/ubuntu/yocto/poky/meta-poky \
   /home/ubuntu/yocto/poky/meta-yocto-bsp \
   /home/ubuntu/yocto/meta-openembedded/meta-oe \
   /home/ubuntu/yocto/meta-ost/meta-ost \

The paths of the entries above must match your actual paths.


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_PROVIDER_virtual/kernel to the desired kernel. By default, yocto provides a kernel as linux-yocto.

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

MACHINE = "<machine>"
DISTRO = "ost-devel"

This will build a development image. If you would rather build a production image, change DISTRO to ost-distro. The difference between the 2 distro's are documented in the „ost-distro vs. ost-devel“ section in meta-ost.

Internal Mirrors

Bitbake has the ability to use external mirrors both for downloading package sources and the shared state cache (sstate-cache) to speed up builds.

The downloads and sstate-cache generated by the CI builds for meta-ost are provided internally.

OST INTERNAL ONLY: To configure bitbake to use the internal mirror, check the internal docs .

Running 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 ost-image

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.

Results will be placed in build/tmp/deploy/, e.g. images will be in build/tmp/deploy/images.