What You Will Learn

Prerequisites

Understanding BitBake Image Targets

BitBake does not build “a Linux system” in the abstract — it builds whatever image recipe you name on the command line, and that recipe pulls in every package it depends on, transitively, until BitBake has a complete dependency graph rooted at your target. When you type a build command, you are really telling BitBake: “resolve this recipe’s full dependency tree, and build every node in it, starting from whatever is missing.”

A small set of image recipes cover almost every beginner use case. Here is how they compare on a modern Yocto release:

For a first build, always reach for core-image-minimal. It exercises your entire toolchain and BSP layer without pulling in graphics stacks that can take hours on modest hardware.

Running the Build

With your environment sourced, kicking off a build is a single command:

$ bitbake core-image-minimal

The first invocation is the expensive one. BitBake has to fetch source for every recipe in the dependency graph, build a full cross-toolchain from scratch, then use that toolchain to cross-compile every package, and finally assemble a root filesystem image from the resulting packages. On a typical development laptop this can run well over an hour; on a CI build server with a shared sstate-cache it can drop to minutes. Do not interrupt a first build — let BitBake populate its shared-state cache, because every build after that reuses whatever hasn’t changed.

While the build runs, BitBake prints task-level progress such as do_fetch, do_compile, and do_package for each recipe. Watching this output teaches you the build pipeline faster than any diagram can — you can literally see the toolchain get built before the kernel, and the kernel get built before the root filesystem is assembled.

Where Your Build Artifacts Land

Once the build finishes, everything of interest lives under your build directory’s tmp subdirectory. Two subfolders matter most to a beginner:

The deploy/images/<machine> folder is the one you actually care about day to day — it holds the flashable or bootable output of the entire build. The deploy/licenses folder matters more than most beginners realize: if you ever ship a product built on this image, that folder is your starting point for license compliance review.

Booting Your Image in QEMU

Yocto builds an internal copy of QEMU as part of the build, so you never need to install a distro QEMU package or worry about version mismatches between your host tools and your target emulation. The wrapper script that drives this internal QEMU is runqemu.

$ runqemu qemuarm

By default this opens a graphical framebuffer window and shows you the kernel boot log in real time, ending at a login prompt. Watching that boot log scroll by — udev starting, the root filesystem mounting, init entering its target runlevel — is genuinely useful debugging practice, because when something goes wrong in a real BSP bring-up later, this is exactly the log you will be reading.

Poky (reference distro) boot complete
target login: root
#

You can log in as root with no password on these development images — never do this on anything you actually ship. If you don’t have or don’t want a graphical window (headless servers, SSH sessions, CI runners), run headless instead:

$ runqemu qemuarm nographic

In this mode the boot log and console appear directly in your terminal, and you exit QEMU with Ctrl+A then X rather than closing a window. This is the mode you’ll use constantly once you move past the “does it boot” stage and into real driver bring-up, because it’s scriptable and works over SSH.

runqemu takes many more options than shown here — network configuration, serial-only consoles, custom kernel command-line arguments, and more:

$ runqemu help

A Worked Example: Confirming a Driver Change Took Effect

A common beginner workflow in this free linux kernel development course is: modify a kernel config or a device tree, rebuild, and confirm the change actually reached the running system. Here’s a minimal, original example that does exactly that using a trivial kernel command-line marker.

# Add a custom boot marker via the kernel command line
$ runqemu qemuarm bootparams="ep_marker=hello"

# Once booted, confirm it reached the running kernel
# target login: root
# cat /proc/cmdline

Expected output:
console=ttyAMA0 root=/dev/vda rw ep_marker=hello

Seeing ep_marker=hello echoed back in /proc/cmdline confirms the full pipeline worked end to end — your build, your bootloader, and your kernel all agree on what was passed. This exact pattern (inject something small and identifiable, then verify it downstream) is one you’ll reuse constantly once you start writing and testing your own device drivers.

Common Mistakes and Troubleshooting

Best Practices

Performance Considerations

Build parallelism (BitBake’s own task parallelism and the underlying compiler’s job count) has the single biggest effect on build time on capable hardware. An under-provisioned tmpfs or a slow disk for the build directory is usually the next biggest bottleneck — the build directory performs an enormous amount of small file I/O.

Summary and Key Takeaways

That completes the build-and-run milestone of this free embedded Linux course. From here, everything else — writing your own recipes, adding drivers, customizing the root filesystem — builds directly on the workflow you just practiced: change something, rebuild, boot it in QEMU, and verify.

Frequently Asked Questions