A Quick Guide to Getting Started With The Yocto Project

Iain Menzies-Runciman

I really like the Yocto Project. As someone who builds Embedded Linux distributions, it makes my life so much easier.

However, if you are just coming into the world of Yocto it is very easy to get overwhelmed with the sheer quantity of things that it seems like you need to know about.

The truth is – you don’t!

You can actually start very small and then grow your project as you learn more.

Eating The Elephant

How do you eat an elephant? One bite at a time!

When you have something as big and complex as the Yocto Project, it is just too big to grasp in one sitting. I have been using it for many years now and I am still discovering brilliant new features.

Start Small

The first thing to do is create your project. I have based this on my standard template for a new project – How to layout the structure of a Yocto Project.

You will need to be on a relatively up to date version of one of the main Linux distributions i.e. Ubuntu, Debian, Fedora. Other distributions like Mint may work but they have not been explicitly tested by the Yocto Project team.

You will also need at least 50Gb of free disk space – thought I would recommend nearer 100Gb to be comfortable.

Install the Tools

For a Ubuntu/Debian system

sudo apt install bc gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev python3-subunit mesa-common-dev zstd liblz4-tool file locales libacl1 libncurses-dev libssl-dev git 

sudo locale-gen en_US.UTF-8

Create your Project Working Directory

mkdir –p ~/wip/my_project
cd ~/wip/my_project
git init

Create the directories to hold your layers

mkdir -p layers/project
mkdir layers/third-party

Clone Poky – The Reference Distribution

I use git submodules, but that is my preference.

For the current (Oct. 2024) Long Term Supported (LTS) Version

git submodule add -b scarthgap git://git.yoctoproject.org/poky layers/third-party/poky

Create a Start Script

Being lazy – I do not want to have to type longs commands to start my build system, so I create a little start script.

In ~/wip/my_project (where you should be if you are following the instructions), create a script start-yocto.sh

#!/bin/bash --init-file

source ./layers/third-party/poky/oe-init-build-env ./build

Make sure it is executable!

Run this script each time you want to build anything, as it will initialise your environment correctly and put you into the correct build directory.

Run the script now and you will be able to start your first build.

Edit your Layer Configuration File

To ensure that BitBake (the build tool) finds your layers correctly, edit build/conf/bblayers.conf to look like this

# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"

# YOCTOROOT will be updated with the correct path once build-env is sourced
YOCTOROOT = "${TOPDIR}/../layers"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
  ${YOCTOROOT}/third-party/poky/meta \
  ${YOCTOROOT}/third-party/poky/meta-poky \
  ${YOCTOROOT}/third-party/poky/meta-yocto-bsp \
"

Build your First Image

Create a minimal image with the command

bitbake core-image-minimal

Wait…

This is where many people think that building a Yocto Project is slow. The first time you build an image, BitBake has a lot of work to do:

  • Download the source for every package you are using (this is why you need a lot of storage space)
  • Configure each package
  • Compile all the packages – including the native toolchain that will be used to compile everything for your target
  • Create a Image file
  • Install of the packages into the image.

However, the next time you run a build, BitBake only has to do that for anything that has changed. It takes about 2 hours for the first build on my system, but then about 25 seconds for the next run (assuming I have not changed too much)

Test the Image

At this point, you have built an image for a QEMU (Quick Emulator) x86-64 target. You can run your image with the command

runqemu qemux86-64

Login as root with no password.

If you want to learn more about running QEMU, see the Using the Quick EMUlator (QEMU) chapter in the Yocto Project Development Tasks Manual.

Exit QEMU by either clicking on the shutdown icon or by typing Ctrl-C in the QEMU transcript window from which you evoked QEMU.

Next Steps

The next things you are going to want to do are find out about

  • Adding additional layers
  • Creating your own layer
  • Creating your own image
  • Adding your own recipe
  • Appending an existing recipe
  • Creating your own distibution