yocto-reasoning

name	yocto-reasoning
description	Reasoning scaffold for Yocto/BitBake recipe work. Covers recipe vs bbappend, SRC_URI pinning, inherit module, DEPENDS vs RDEPENDS, machine config, sstate cache, and typical failure modes. Use when writing/modifying recipes, debugging bitbake errors, or extending meta-bbb.
origin	custom-bsp

Yocto Reasoning — meta-bbb layer

A reasoning scaffold. For specifics see vault/wiki/yocto/ + docs/05-kernel-config.md.

Layer structure

meta-bbb/
├── conf/
│   ├── layer.conf                       ← BBFILE_COLLECTIONS, BBFILE_PATTERN
│   └── machine/beaglebone-custom.conf   ← extends beaglebone-yocto
├── recipes-kernel/linux/
│   └── linux-yocto_%.bbappend           ← pulls repo-level kernel patches/configs/dts
├── recipes-drivers/<name>/
│   ├── <name>_1.0.bb                    ← out-of-tree module
│   └── files/...                        ← local patches + sources
├── recipes-apps/<name>/
│   └── <name>_1.0.bb                    ← userspace app
└── recipes-core/images/
    └── bbb-image.bb                     ← target image recipe

Recipe vs bbappend — when to use which

Situation	File type
Build your own out-of-tree driver	new .bb
Build your own userspace app	new .bb
Add a patch / config fragment to an existing upstream recipe (linux-yocto)	.bbappend
Override/add files for an existing recipe	.bbappend with FILESEXTRAPATHS:prepend
Add a new dependency to an image	modify bbb-image.bb or write an .inc

The SRC_URI pinning rule

Any git:// or https:// URL in SRC_URI must be pinned:

• SRCREV = "<40-char SHA>" (not a tag; tags can be moved)
• LIC_FILES_CHKSUM = "file://COPYING;md5=<md5>" (computed from actual file in source)

Local file:// patches do NOT need checksums — they are already tracked in the layer.

Never use floating refs (${AUTOREV}, branch names). Reproducibility = license + SHA + LIC_FILES_CHKSUM.

inherit module — out-of-tree kernel modules

SUMMARY = "PWM fan driver"
LICENSE = "GPL-2.0-only"
LIC_FILES_CHKSUM = "file://COPYING;md5=<md5>"

SRC_URI = "file://Makefile file://pwm-fan.c file://COPYING"
S = "${WORKDIR}"

inherit module

inherit module handles: cross-compile setup, do_compile with kernel headers, do_install to /lib/modules/<kernel>/extra/. Do NOT write manual install tasks.

DEPENDS vs RDEPENDS

• DEPENDS = recipes needed at build time (headers, libraries to link against).
• RDEPENDS_${PN} = packages needed at runtime (shared libs, binaries called by scripts).

Kernel modules built via inherit module implicitly DEPEND on virtual/kernel.

do_ task ordering

do_fetch → do_unpack → do_patch → do_configure → do_compile → do_install → do_package → do_package_write_* → do_rootfs (image-level)

To add custom work: do_install:append() { ... } or do_compile:prepend() { ... }. Use :append / :prepend (colon syntax), not legacy _append.

Variable override rules (critical)

Yocto's variable operators matter:

• = simple assign (last wins)
• ?= default (first wins)
• ??= weak default
• += append with space (whitespace-safe)
• := immediate expansion
• :append end-of-parse append (use this for most task/var modifications)
• :prepend end-of-parse prepend

Order of evaluation: conf files → .bbclass → .bb → .bbappend (in layer priority order).

Machine config (beaglebone-custom)

require conf/machine/beaglebone-yocto.conf

PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
PREFERRED_VERSION_linux-yocto = "5.10.%"

KERNEL_DEVICETREE = "am335x-boneblack-custom.dtb"
IMAGE_BOOT_FILES = "MLO u-boot.img zImage am335x-boneblack-custom.dtb"

Common bitbake failures

Error	Fix
Nothing PROVIDES 'virtual/kernel'	MACHINE mis-set in local.conf or layer missing from BBLAYERS
QA Issue: ... installed but not shipped	Add files to FILES:${PN} or delete in do_install:append
LIC_FILES_CHKSUM mismatch	License file changed upstream; recompute md5 via md5sum <file> and update recipe
ERROR: Task ... do_patch failed	Patch context broken; regenerate with devtool modify + devtool finish
ERROR: Nothing RPROVIDES ...	Missing recipe or wrong RDEPENDS

Verify

# What recipe provides this package?
bitbake -e bbb-image | grep "^IMAGE_INSTALL"
oe-pkgdata-util find-path /path/to/file

# Layer list
bitbake-layers show-layers

# All recipes providing X
bitbake-layers show-recipes '*kernel*'

# Dry-run package contents
bitbake -c listtasks <recipe>

See also

• .claude/rules/coding-standards.md §"Yocto / BitBake".
• docs/05-kernel-config.md — kernel config via Yocto.
• vault/wiki/yocto/_index.md — layer knowledge.
• skills/karpathy-discipline/ — think-before-recipe scaffold.