ES: Configuring a Yocto Build

Configuring a Yocto build correctly is the foundation of a successful embedded Linux project. Yocto's configuration system is file-based, flexible, and well-structured. Knowing what each configuration file does and where build artifacts end up is essential for efficient development.

Initialising the Build Environment

Every Yocto session begins by sourcing the oe-init-build-env script (OpenEmbedded Initialising Build Environment):

source oe-init-build-env

This script:

• Sets up all required environment variables for the build
• Creates a default build directory called build (if it does not exist)
• Changes the working directory to the build directory

To use a custom build directory name (recommended when working with multiple targets):

source oe-init-build-env rpi-build

The Build Directory Structure

Before Building

Initially, the build directory contains only a conf/ subdirectory with three configuration files:

build/
└── conf/
    ├── local.conf          # Target machine and build settings
    ├── bblayers.conf       # List of layers to include
    └── templateconf.cfg    # Path to template configuration directory

After Building

After a successful build, the directory expands significantly:

build/
├── conf/               # Configuration files (unchanged)
├── downloads/          # All downloaded source archives
├── tmp/                # Most build artifacts
│   ├── work/           # Per-recipe build and staging directories
│   └── deploy/         # Final deployable files
│       ├── images/     # Bootloader, kernel, root filesystem
│       │   └── <machine-name>/
│       ├── rpm/        # RPM packages from the build
│       └── licenses/   # License files extracted from each package

Configuration Files

local.conf

local.conf is the primary configuration file for a build. It specifies the target hardware and controls build behaviour.

The most critical setting is MACHINE, which tells Yocto what hardware to build for:

MACHINE ?= "qemuarm"

Other common settings:

# Target machine
MACHINE ?= "qemuarm"

# Number of parallel build jobs
BB_NUMBER_THREADS ?= "4"
PARALLEL_MAKE ?= "-j4"

# Disk space management
INHERIT += "rm_work"

# Add extra packages to the image
IMAGE_INSTALL:append = " nano htop"

Always verify that MACHINE is set to your target before building:

MACHINE ?= "qemuarm"         # QEMU emulated ARM
MACHINE ?= "raspberrypi3"    # Raspberry Pi 3
MACHINE ?= "beaglebone"      # BeagleBone Black

bblayers.conf

bblayers.conf defines which layers are included in the build. BitBake reads recipes from all listed layer directories.

A minimal bblayers.conf:

LCONF_VERSION = "6"

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

BBLAYERS ?= " \
    /home/user/poky/meta \
    /home/user/poky/meta-poky \
    /home/user/poky/meta-yocto-bsp \
    "

BBLAYERS_NON_REMOVABLE ?= " \
    /home/user/poky/meta \
    /home/user/poky/meta-poky \
    "

The BBLAYERS_NON_REMOVABLE variable protects the core layers from accidental removal.

templateconf.cfg

This file contains the path to a directory with template conf files. It is used when initialising a new build directory to pre-populate it with sensible defaults.

Running a Build

With the build environment initialised and local.conf configured:

bitbake core-image-minimal

Running the Image with QEMU

By default, Yocto builds QEMU-compatible images. To run the generated image:

runqemu qemuarm

For a headless (no graphics) session:

runqemu qemuarm nographic

You must source `oe-init-build-env` in the current terminal before running `runqemu`, as it depends on the environment variables set by that script.

Understanding Build Output

deploy/images/

The most important output directory. For each MACHINE, it contains:

tmp/work/

Contains the build and staging area for every recipe. Useful for debugging build failures — you can inspect the exact files and commands used for each package.

downloads/

All downloaded source archives are stored here. On subsequent builds, Yocto reuses these cached downloads rather than re-fetching from the network.

Key Configuration Workflow

Configure Yocto Build:
1. source oe-init-build-env [build-dir]
        |
        v
2. Edit conf/local.conf
   - Set MACHINE
   - Adjust threads/jobs
   - Add packages
        |
        v
3. Edit conf/bblayers.conf
   - Add required layers
        |
        v
4. bitbake core-image-minimal
        |
        v
5. Check output in tmp/deploy/images/<machine>/
        |
        v
6. runqemu <machine>  (for QEMU targets)
   OR flash to hardware

Final Thoughts

Yocto's configuration system is straightforward once you understand the separation of concerns:

• local.conf controls what you build (machine, features, packages)
• bblayers.conf controls where BitBake finds recipes (layers)

Getting these two files right is the foundation of every successful Yocto build.