A tiny, tutor-friendly Yocto/QEMU learning lab.

This repository is a small educational workspace for learning how Yocto builds a minimal Linux image and how QEMU can boot it without requiring real embedded hardware.

It is intentionally small, slow-paced, and documented step by step.

The lab currently shows how to:

• prepare a small Ubuntu host for Yocto
• clone Poky at a fixed Yocto tag
• build core-image-minimal
• boot the image with QEMU
• create a custom layer named meta-monkey
• create a custom recipe named hello-monkey
• include that package in a custom image
• boot monkey-image-minimal and run hello-monkey inside QEMU

The custom image is:

monkey-image-minimal

It starts from core-image-minimal and adds:

/usr/bin/hello-monkey

Inside QEMU:

root@qemux86-64:~# which hello-monkey
/usr/bin/hello-monkey

root@qemux86-64:~# hello-monkey
Hello from meta-monkey!
This tiny command was installed by a custom Yocto recipe.

Yocto/Poky builds the Linux image.
BitBake executes recipes and tasks.
QEMU pretends to be the hardware.
runqemu boots the generated image.
meta-monkey contains our custom Yocto metadata.
monkey-image-minimal includes our hello-monkey package.

In monkey terms:

Yocto cooks the banana.
BitBake follows the recipe graph.
QEMU pretends to be the monkey cage.
runqemu puts the banana in the cage.
meta-monkey adds our own tiny monkey trick.

This lab currently uses Poky tag:

yocto-5.2.4

Yocto series:

walnascar

Machine target:

qemux86-64

This lab was tested on Ubuntu 24.04 LTS with the qemux86-64 machine target.

The first cold Yocto build can take hours on a small host. BitBake progress is not linear, and disk usage can grow quickly while images are being built.

Practical guidance for a comfortable learning run:

• 4 CPU cores can work, especially with conservative build settings.
• Less than 16 GiB RAM can work, but swap pressure is possible.
• Have significantly more than 30 GiB free before starting the first build.
• Around 60 GiB free is a safer target for a smoother learning session.
• Keep downloads and sstate-cache when possible.
• See Troubleshooting Yocto builds before deleting generated directories.

These are practical expectations for this lab, not official Yocto minimum requirements.

Install the required host packages first. See:

• Host setup notes
• Host preflight runbook

Clone Poky:

git clone --branch yocto-5.2.4 --depth 1 https://git.yoctoproject.org/poky poky

Initialize the build directory:

source poky/oe-init-build-env build

Add the custom layer:

bitbake-layers add-layer ../meta-monkey

Recommended local settings for small hosts:

BB_NUMBER_THREADS = "2"
PARALLEL_MAKE = "-j2"
INHERIT += "rm_work"

Build the custom image:

bitbake monkey-image-minimal

Boot it with QEMU:

runqemu qemux86-64 monkey-image-minimal nographic

Login as:

root

Test the custom command:

which hello-monkey
hello-monkey

Read the docs in order:

1. Roadmap
2. Host setup notes
3. Host preflight runbook
4. Build and boot core-image-minimal
5. Add meta-monkey and hello-monkey
6. Create monkey-image-minimal
7. Troubleshooting Yocto builds
8. vscode-bitbake workspace walkthrough
9. Cleanup guide for generated Yocto directories

This repository should stay small.

Do not commit generated Yocto artifacts such as:

• poky/
• build/
• downloads/
• sstate-cache/
• tmp/
• generated images
• build artifacts

Those directories can become very large and are intentionally ignored.

This is not a production Yocto distribution.

This is not a board support package.

This is not an optimized industrial embedded Linux setup.

This is not a claim of Yocto expertise.

It is a small learning sandbox.