The Yocto Project website outlines the following requirements:
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://git.yoctoproject.org/poky
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:
core-image-minimal
core-image-sato
meta-toolchain
meta-ide-support
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
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://git.openembedded.org/meta-openembedded -b <yocto-release> git clone https://gitlab.ost.ch/tech/inf/public/meta-ost -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.
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.
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.
BBLAYERS ?= " \ /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.
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 .
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.