← Back to Home

Building Yocto Linux Without a Dev Board

2026.10.11 · Yocto · 7 min read

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.

Why Start with QEMU

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.

Environment Setup

The VM specs used this time:

ItemConfigurationNotes
CPU6 coresAvailable for the build
RAM10 GBWatch memory during parallel compilation
Virtual disk200 GBMonitor how the build cache grows
OSUbuntu 24.04Build 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.

Build Steps

1. Create a working directory

mkdir -p ~/yocto
cd ~/yocto

2. Download the Poky source

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

3. Initialize the build environment

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"

4. Set the target machine

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.

5. Start the build

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.

6. Check the output

ls -lh tmp/deploy/images/qemux86-64/

7. Test with QEMU

runqemu qemux86-64

Three Errors I Actually Got Stuck On

① Branch name does not exist

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.

② Missing lz4c

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.

③ BitBake cannot use user namespaces

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:

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.

Next Steps

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.

A Few Useful Commands

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)

Key Takeaways