linux-yocto

name	linux-yocto
description	Use when configuring, building, or debugging a Yocto Project-based Linux distribution for embedded targets. Covers BitBake, bblayers.conf, local.conf, recipe files (.bb / .bbappend), layers, image recipes, devtool, SDK generation, and common BSP layer patterns for automotive IVI, HUD, and RSE targets.
argument-hint	<recipe-or-layer> [write|build|debug]

Yocto Project — Embedded Linux Distribution

Practices for building custom Linux images with the Yocto Project for embedded automotive targets (IVI, HUD, RSE).

Source of truth:

• Yocto Project Documentation
• BitBake User Manual

---

When to Use This Skill

• Building a custom Linux root filesystem for an embedded board.
• Writing or modifying a BitBake recipe to add/change a package.
• Creating a BSP layer for a new hardware target.
• Generating an SDK for cross-compilation.

---

Workspace Layout

poky/               # Yocto reference distribution (contains BitBake + OE-Core)
meta/               # OE-Core layer (included in poky)
meta-poky/          # Poky distro configuration
meta-openembedded/  # Extra packages (meta-oe, meta-networking, ...)
meta-<vendor>/      # Board vendor BSP layer
meta-<project>/     # Project-specific customizations
build/              # Build directory (created by oe-init-build-env)
  conf/
    bblayers.conf   # Which layers are included
    local.conf      # Build variables (MACHINE, DISTRO, parallelism, ...)
  tmp/              # Build output (sstate cache, sysroots, images)
    deploy/
      images/<MACHINE>/   # Final kernel, dtb, rootfs images

---

Initial Setup

# Source the environment script — creates build/ if needed
source poky/oe-init-build-env build/

# After sourcing, you are in build/ and can run BitBake

---

conf/bblayers.conf

BBLAYERS ?= " \
  /path/to/poky/meta \
  /path/to/poky/meta-poky \
  /path/to/meta-openembedded/meta-oe \
  /path/to/meta-myboard \
  /path/to/meta-project \
"

# Add a layer via command
bitbake-layers add-layer /path/to/meta-mylayer

# Show all layers and their priorities
bitbake-layers show-layers

---

conf/local.conf — Key Variables

# Target machine (matches a .conf file in a layer's conf/machine/)
MACHINE = "myboard"

# Distribution policy
DISTRO = "poky"

# Parallelism
BB_NUMBER_THREADS = "8"
PARALLEL_MAKE = "-j 8"

# Package format
PACKAGE_CLASSES = "package_ipk"

# Extra packages to install in all images
IMAGE_INSTALL:append = " my-package another-package"

# Enable systemd
DISTRO_FEATURES:append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"

---

Recipe Files (.bb)

# meta-project/recipes-example/my-app/my-app_1.0.bb

SUMMARY = "My automotive sensor application"
DESCRIPTION = "Reads CAN bus sensor data and publishes to D-Bus"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://LICENSE;md5=abc123..."

SRC_URI = "git://github.com/example/my-app.git;branch=main;protocol=https"
SRCREV = "abc1234def5678..."

S = "${WORKDIR}/git"

inherit cmake

# CMake options
EXTRA_OECMAKE = "-DENABLE_CAN=ON"

# Files to install
do_install() {
    install -d ${D}${bindir}
    install -m 0755 ${B}/my-app ${D}${bindir}/my-app
}

Key variables:

Variable	Purpose
S	Source directory (extracted source)
B	Build directory
D	Destination directory (staging root for install)
${bindir}	/usr/bin
${sbindir}	/usr/sbin
${libdir}	/usr/lib
${sysconfdir}	/etc
${systemd_unitdir}	/lib/systemd

---

.bbappend — Modifying Existing Recipes

# meta-project/recipes-example/my-app/my-app_%.bbappend
# The % wildcard matches any version

# Append extra source files
SRC_URI:append = " file://0001-fix-timeout.patch"

# Append install steps
do_install:append() {
    install -d ${D}${sysconfdir}/my-app
    install -m 0644 ${WORKDIR}/my-app.conf ${D}${sysconfdir}/my-app/
}

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

---

Image Recipes

# meta-project/recipes-core/images/my-ivi-image.bb

require recipes-core/images/core-image-minimal.bb

SUMMARY = "IVI minimal production image"

IMAGE_INSTALL:append = " \
    my-app \
    can-utils \
    dbus \
"

IMAGE_FEATURES:append = " ssh-server-openssh"

# Build the image
bitbake my-ivi-image

Images are placed in build/tmp/deploy/images/<MACHINE>/.

---

Common BitBake Commands

# Build a recipe
bitbake my-app

# Build only a specific task
bitbake my-app -c compile
bitbake my-app -c devshell    # opens an interactive shell in the build environment

# Clean a recipe's work directory
bitbake my-app -c clean

# Clean and rebuild from scratch (removes sstate as well)
bitbake my-app -c cleansstate

# Show all tasks for a recipe
bitbake my-app -c listtasks

# Show which recipe provides a package
bitbake -s | grep my-app

# Show variable value as expanded by BitBake
bitbake -e my-app | grep ^WORKDIR

# Show all layers and recipes
bitbake-layers show-recipes

---

devtool — Modifying Recipes Interactively

# Check out a recipe's source for editing
devtool modify my-app

# After editing, build and test
devtool build my-app
devtool build-image my-ivi-image

# Generate a patch from your changes and update the recipe
devtool update-recipe my-app

# Finish — moves changes back to the layer, cleans workspace
devtool finish my-app meta-project

---

SDK Generation

# Build and populate the extensible SDK (eSDK)
bitbake my-ivi-image -c populate_sdk

# Installer is placed in:
# build/tmp/deploy/sdk/<distro>-<host>-<machine>-toolchain-<version>.sh

Install and use:

./poky-glibc-x86_64-my-ivi-image-aarch64-myboard-toolchain-*.sh
source /opt/poky/<version>/environment-setup-aarch64-poky-linux
# Now CROSS_COMPILE, CC, CXX, PKG_CONFIG_SYSROOT_DIR, etc. are set

---

Creating a BSP Layer

# Use bitbake-layers to scaffold
bitbake-layers create-layer /path/to/meta-myboard

Minimal BSP layer structure:

meta-myboard/
  conf/
    layer.conf          # Layer config — BBPATH, BBFILES, layer deps
    machine/
      myboard.conf      # MACHINE definition
  recipes-kernel/
    linux/
      linux-myboard_%.bbappend  # Kernel .bbappend for the BSP
  recipes-bsp/
    u-boot/
      u-boot_%.bbappend

conf/machine/myboard.conf:

#@TYPE: Machine
#@NAME: My Board
require conf/machine/include/arm/arch-arm64.inc

KERNEL_IMAGETYPE = "Image"
UBOOT_MACHINE = "myboard_defconfig"
SERIAL_CONSOLES = "115200;ttyAMA0"

MACHINE_FEATURES = "usbgadget usbhost vfat"
IMAGE_FSTYPES = "ext4 wic"

---

Prerequisites

• Linux host machine (Ubuntu 20.04 LTS or Debian 11 recommended).
• Cross-compilation toolchain: arm-linux-gnueabihf-gcc or aarch64-linux-gnu-gcc.
• Target board with serial console access (USB-to-UART adapter).
• ssh access to target (optional but recommended).

Step-by-Step Workflows

Step 1: Set up the build environment

Run source oe-init-build-env; configure MACHINE and DISTRO in conf/local.conf.

Step 2: Add layers

Run bitbake-layers add-layer <layer-path>; verify with bitbake-layers show-layers.

Step 3: Write or modify a recipe

Create <name>_<version>.bb or .bbappend; define SRC_URI, do_install, and FILES.

Step 4: Build the image

Run bitbake <image-name>; use bitbake -e <recipe> to debug variable values.

Step 5: Deploy to target

Flash the generated image (wic, ext4, or tar.gz) to the target storage medium.

Troubleshooting

• ERROR: Nothing PROVIDES 'xxx' — the required layer is missing; add it with bitbake-layers add-layer; check BBFILE_COLLECTIONS.
• Recipe fetch fails (404) — the SRC_URI tarball URL has moved; update the URI and SRC_URI[sha256sum] checksum.
• do_compile fails with cross-compiler error — ensure inherit cross-compilation or TOOLCHAIN is correct; check DEPENDS for missing native tools.
• Image boots but app is missing — add the package name to IMAGE_INSTALL:append in local.conf or the image recipe.

Pre-Commit Checklist

• LIC_FILES_CHKSUM present and correct in every new .bb.
• SRCREV pinned to a specific commit hash — not a branch name.
• .bbappend uses FILESEXTRAPATHS:prepend when adding local files.
• do_install creates all needed directories with install -d.
• IMAGE_INSTALL:append uses a leading space: " package-name".
• New layer has a conf/layer.conf with correct LAYERVERSION and LAYERDEPENDS.
• bitbake <recipe> -c cleansstate && bitbake <recipe> passes from scratch.

---

References

• Yocto Project Documentation
• BitBake User Manual
• OpenEmbedded Layer Index
• devtool Quick Reference