Okay, this is me coming back to my roots from a few years back (well, actually just half a year, but leaving a skill unused that long feels like ages). This is a short Yocto tutorial to help me (and you) set up a new Raspberry Pi Yocto environment. We’ll gather the meta layers, pick the target board, and finally build a custom Raspberry Pi Linux distribution.

Yocto is cool#

Yes, it is. It’s insanely good. However with the good parts come also a bit overwhelming ones, like its documentation. For starters it’s much easier to follow somebody’s blog and setup things quickly - like this medium post.

Package Preparations#

The only thing I suggest taking from the official docs as a first step, is to install below packages:

sudo apt install build-essential chrpath cpio debianutils diffstat file gawk gcc git iputils-ping libacl1 liblz4-tool locales python3 python3-git python3-jinja2 python3-pexpect python3-pip python3-subunit socat texinfo unzip wget xz-utils zstd

Things are sligthly different on arch. This is the moment when I regret the decision of choosing Manjaro as THE DISTRO of my private laptop. There’s nothing good about it. Things break constantly with every update, and for the worst, every tutorial assumes Ubuntu and apt, which is not Manjaro at all. With arch and manjaro everything is a material for a story to tell.

Try

sudo pacman -S cpio chrpath diffstat file gawk git acl iputils lz4 glibc-locales python3 python-gitpython python-jinja python-pexpect python-pip python-subunit socat texinfo unzip wget zstd rpcsvc-proto

debianutils remains not installed, as it’s not available on ARCH.

Environment Setup#

Every Yocto project should have its own working directory, my suggestion is to create yocto-rpi and then a source subdirectory, which will contain the cloned meta-layers.

mkdir -p yocto_rpi/source
cd yocto_rpi/source

Clone the meta layers of poky, meta-raspberrypi and meta-openembedded

git clone https://github.com/yoctoproject/poky.git
git clone https://github.com/agherzan/meta-raspberrypi
git clone https://github.com/openembedded/meta-openembedded.git

make sure that all of the meta layers have a branch of your interest checked out, not just master. My suggestion is to go with scarthgap, the current LTS.

The step of setting up the sources should at some point be automatized with the help of a repo tool, described in detail in article How to Handle Multiple Yocto Meta Layers with repo.

Build Configuration#

Yocto will create the build config for you, just source the poky/oe-environment from the yocto_rpi directory

cd ../
source sources/poky/oe-init-build-env

Now, the build directory with some basic config should be there, take a look at build/conf/local.conf and build/conf/bblayers.conf.

local.conf file is a super important config file, anyway, it contains a variable MACHINE ??= "qemux86-64", replace that with MACHINE ?= "raspberrypi4-64" or "raspberrypi5" depending on the type of RPI board you own.

BBLAYERS.CONF#

The generated bblayers.conf file should now look like below, with three layer paths assigned to a BBLAYERS variable:

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

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

BBLAYERS ?= " \
  /home/antoni/Projects/yocto-rpi-manifest-test/sources/poky/meta \
  /home/antoni/Projects/yocto-rpi-manifest-test/sources/poky/meta-poky \
  /home/antoni/Projects/yocto-rpi-manifest-test/sources/poky/meta-yocto-bsp \
  "

These meta-layers paths are full paths that include the home directory user and many more obsolete details. My advice is to keep the paths relative to the parent directory of sources and build, use the TOPDIR variable pointing to the build directory to achieve that. TOPDIR is automatically set by bitbake.

The file with relative paths and all the usual layers would present as below:

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

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

BBLAYERS ?= " \
  ${TOPDIR}/../sources/poky/meta \
  ${TOPDIR}/../sources/poky/meta-poky \
  ${TOPDIR}/../sources/poky/meta-yocto-bsp \
  ${TOPDIR}/../sources/meta-raspberrypi \
  ${TOPDIR}/../sources/meta-openembedded/meta-oe \
  ${TOPDIR}/../sources/meta-openembedded/meta-multimedia \
  ${TOPDIR}/../sources/meta-openembedded/meta-networking \
  ${TOPDIR}/../sources/meta-openembedded/meta-python \
  "

Build a bitbake image#

Now it’s finally the time to launch the build process. Chose one of the images that were displayed just after sourcing the poky environment, core-image-minimal is a good start. Use bitbake to initiate the build:

bitbake core-image-minimal

What you should see right after is below:

$ bitbake core-image-minimal
WARNING: Host distribution "manjaro" has not been validated with this version of the build system; you may possibly experience unexpected failures. It is recommended that you use a tested distribution.
Loading cache: 100% |                                                                                                                                                                                                        | ETA:  --:--:--
Loaded 0 entries from dependency cache.
Parsing recipes: 100% |#######################################################################################################################################################################################################| Time: 0:02:51
Parsing of 920 .bb files complete (0 cached, 920 parsed). 1878 targets, 58 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies

Build Configuration:
BB_VERSION           = "2.8.0"
BUILD_SYS            = "x86_64-linux"
NATIVELSBSTRING      = "manjaro"
TARGET_SYS           = "aarch64-poky-linux"
MACHINE              = "qemuarm64"
DISTRO               = "poky"
DISTRO_VERSION       = "5.0.11"
TUNE_FEATURES        = "aarch64 crc cortexa57"
TARGET_FPU           = ""
meta
meta-poky
meta-yocto-bsp       = "HEAD:792d18b4cb2451b00280641403e6eaf37bd6e53f"

NOTE: Fetching uninative binary shim http://downloads.yoctoproject.org/releases/uninative/4.7/x86_64-nativesdk-libc-4.7.tar.xz;sha256sum=5800d4e9a129d1be09cf548918d25f74e91a7c1193ae5239d5b0c9246c486d2c (will check PREMIRRORS first)
Sstate summary: Wanted 1849 Local 0 Mirrors 0 Missed 1849 Current 0 (0% match, 0% complete)##############################################################################################################                     | ETA:  0:00:01
Initialising tasks: 100% |####################################################################################################################################################################################################| Time: 0:00:17
NOTE: Executing Tasks

The only thing left is to wait, as the initial build process may take a few hours to complete. Once ready, the image should be found somewhere in build/tmp/deploy/images/raspberrypi4-64/ directory under the name of core-image-minimal-raspberrypi4-64.rootfs.wic.bz2.