I don't have a physical dev board yet, but I wanted to walk through the Yocto build process once. This records my full path from starting from scratch in an Ubuntu VM to booting with QEMU — including three errors I actually got stuck on.
What Yocto does: it compiles the kernel, bootloader, rootfs, and packages from source into a Linux image that can run on a target board.
Before getting hands-on, using QEMU to emulate x86-64 has two advantages: you don't have to wait for hardware to arrive, and you can walk through the exact same build process end to end. When you later switch to a physical ARM board, the main differences are the BSP layer and the machine configuration.
QEMU testing cannot replace validation on real hardware — Device Tree, GPIO, buses, and vendor drivers still have to be confirmed on a real board.
The VM specs used this time:
| Item | Configuration | Notes |
|---|---|---|
| CPU | 6 cores | Available for the build |
| RAM | 10 GB | Watch memory during parallel compilation |
| Virtual disk | 200 GB | Monitor how the build cache grows |
| OS | Ubuntu 24.04 | Build environment |
To ease memory pressure, I capped parallelism in build/conf/local.conf:
BB_NUMBER_THREADS = "4"
PARALLEL_MAKE = "-j 4"
If the build hits OOM, lower these two numbers further.
mkdir -p ~/yocto
cd ~/yocto
At first I went from memory and used the yocto-6.0 branch — but that branch doesn't exist on the remote:
git clone https://git.yoctoproject.org/poky -b yocto-6.0
# fatal: Remote branch yocto-6.0 not found in upstream origin
So I switched to Poky's scarthgap branch (the Yocto 5.0 series) as the starting point:
cd ~/yocto
git clone https://git.yoctoproject.org/poky -b scarthgap
cd ~/yocto/poky
git branch --show-current
# scarthgap
This command sets up the environment variables BitBake needs and switches the working directory to build:
cd ~/yocto/poky
source oe-init-build-env build
Verify the environment is correct:
pwd # should be in build/
bitbake --version
echo "$BUILDDIR"
Edit conf/local.conf and check the machine setting:
MACHINE = "qemux86-64"
MACHINE decides which target hardware to build for. Here we're using QEMU's x86-64 emulation target.
bitbake core-image-minimal
The first build has to download, unpack, and compile a large number of components, so it takes far longer than later incremental builds. The actual time depends on the CPU, disk speed, network, and image contents.
ls -lh tmp/deploy/images/qemux86-64/
runqemu qemux86-64
The cause is simple: the yocto-6.0 branch doesn't exist on the Poky remote. Yocto versions are named with codenames (kirkstone, scarthgap, and so on), not numbers. Switching to scarthgap fixed it.
BitBake reported an error while checking the host tools:
ERROR: The following required tools (as specified by HOSTTOOLS)
appear to be unavailable in PATH: lz4c
After installing the lz4 package, the system only has lz4, not lz4c. Let's check the actual situation:
sudo apt install -y lz4
which lz4
dpkg -L lz4 | grep -E '/(lz4|lz4c)$'
If you confirm only /usr/bin/lz4 exists, you can create a compatible name:
sudo ln -s /usr/bin/lz4 /usr/local/bin/lz4c
which lz4c
The symlink is only a compatibility workaround. If the build process relies on arguments specific to an older lz4c, you still need to verify that separately.
This is a fairly common situation on Ubuntu 24.04:
ERROR: User namespaces are not usable by BitBake,
possibly due to AppArmor.
BitBake's isolation mechanism needs to create a user namespace, and AppArmor's configuration may block non-privileged users from doing so. First check the actual state:
sysctl kernel.apparmor_restrict_unprivileged_userns
unshare -Ur true
echo $?
How to read the results:
1: the restriction is enabled on the system.unshare -Ur true returns 0: the current user can create a user namespace.Operation not permitted: it was denied — you need the kernel log to work out why.Once you've confirmed the sysctl is 1, you can temporarily relax it for testing inside your own dev VM:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
This setting relaxes the restriction on non-privileged programs creating user namespaces and may affect the security isolation of other programs. It's only recommended as a temporary diagnostic in a controlled dev VM — don't disable it permanently without evaluating the impact. Also, don't use sudo bitbake to work around the problem — that produces root-owned build files, which are even more of a hassle to deal with permissions for later.
Check the environment in order, then retry the build:
# verify version and environment
cd ~/yocto/poky
git branch --show-current
source oe-init-build-env build
# verify settings
grep -E '^(MACHINE|BB_NUMBER_THREADS|PARALLEL_MAKE)' conf/local.conf
# verify tools and restrictions
which lz4c
sysctl kernel.apparmor_restrict_unprivileged_userns
unshare -Ur true; echo $?
# retry
bitbake core-image-minimal
If it still fails, keep the first ERROR and its context — that makes the cause much easier to work out.
nproc # number of CPU cores
free -h # memory and swap
df -h / # free disk space
bitbake --version # BitBake version
grep '^MACHINE' conf/local.conf # current MACHINE
journalctl -k -b --no-pager | tail -100 # kernel log (look for OOM)
sudo bitbake to work around the problem — it produces root-owned build files.