This post is part of the series about my personal BeagleBone Black project. The Yocto tutorial already shows, under "Further Topics", how to create your own layer with bitbake-layers create-layer, write a recipe, and extend the kernel via a .bbappend including a device-tree change. That’s plenty for a hobby project — but once a real product with multiple hardware revisions, multiple software variants, and a team behind it is involved, the single-layer approach hits its limits. This post covers what typically gets added at that point.

Why a single layer isn’t enough

A single meta-mybbb layer mixes three things that actually vary independently:

  • Hardware-specific — pinmux, device-tree changes, which kernel drivers are needed (changes per board revision)

  • Distro policy — which init manager, which C library, which security hardening (changes per product line, not per board)

  • Application logic — the actual application and its dependencies (changes most frequently, independent of hardware and distro)

The established Yocto convention splits this into three layer types:

Layer typeContent

meta-<product>-bsp

Board support: machine definitions, kernel `.bbappend`s, device tree

meta-<product>-distro

Distro policy file (DISTRO_FEATURES, init manager choice, C library)

meta-<product>

Application recipes, image definitions

This three-way split isn’t worth it for every project — for a single board with one firmware variant, the single-layer approach from the main Yocto tutorial is often the more pragmatic choice. The split pays off once at least two of the three dimensions (hardware, distro, application) vary independently of each other.

Layer priorities and dependencies in detail

Each layer’s conf/layer.conf defines more than just the layer name:

BBPATH .= ":${LAYERDIR}"
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"

BBFILE_COLLECTIONS += "mybbb-bsp"
BBFILE_PATTERN_mybbb-bsp = "^${LAYERDIR}/"
BBFILE_PRIORITY_mybbb-bsp = "8"

LAYERDEPENDS_mybbb-bsp = "core ti-bsp"
LAYERSERIES_COMPAT_mybbb-bsp = "scarthgap"
ParameterMeaning

BBFILE_PRIORITY

Decides which layer "wins" when .bbappend`s collide on the same recipe — higher number = higher priority. Your own layers should have a higher priority than `meta-ti/meta-beagleboard so upstream changes don’t overwrite your own customizations

LAYERDEPENDS

Which other layers must be present — bitbake-layers add-layer aborts if a dependency is missing

LAYERSERIES_COMPAT

Which Yocto release codenames (here scarthgap) the layer is tested against — prevents silent incompatibilities on a release upgrade

A common mistake: two of your own layers (e.g. meta-mybbb-bsp and meta-mybbb) with identical BBFILE_PRIORITY. Bitbake then treats the ordering as undefined — a .bbappend that sometimes applies and sometimes doesn’t is a classic symptom of this. Always assign priority explicitly and uniquely per layer.

PACKAGECONFIG: toggling recipe features without forking

Many more complex recipes (e.g. for libraries with optional dependencies) define PACKAGECONFIG flags that let you selectively enable or disable individual build features without modifying the recipe itself:

# in your own .bbappend, e.g. for a library with optional SSL support
PACKAGECONFIG:append = " ssl"
PACKAGECONFIG[ssl] = "--with-ssl,--without-ssl,openssl"

The three comma-separated values in PACKAGECONFIG[<feature>] mean: configure flag when enabled, configure flag when disabled, additional build dependency when enabled.

The most reliable way to find out which PACKAGECONFIG flags a recipe supports is bitbake-layers show-recipes <name> followed by a look at the .bb file itself — not every recipe documents its flags in one central place.

bblayers.conf: ordering pitfalls

bblayers.conf lists all active layers in BBLAYERS. Two points that regularly cause confusion in practice:

  • The order in BBLAYERS itself has no effect on recipe priority — that’s controlled exclusively by BBFILE_PRIORITY in layer.conf (see above). Many developers first try to solve problems by reordering bblayers.conf — that leads nowhere

  • A layer listed in bblayers.conf whose LAYERDEPENDS aren’t satisfied makes bitbake abort at startup with a clear error message — unlike silent priority conflicts, a comparatively harmless failure mode

Keeping rebuild times under control

Yocto builds are long — which clean command discards how much decides between minutes and hours:

CommandEffect

bitbake -c clean <recipe>

Only deletes this recipe’s work directories, shared state is kept — fastest rebuild

bitbake -c cleansstate <recipe>

Additionally deletes this recipe’s shared-state cache entries — needed when the task hash doesn’t change but, e.g., a local patch file outside the hash system was modified

bitbake -c cleanall <recipe>

Additionally deletes downloaded sources — only needed if the source download itself was corrupted

Applying cleansstate or cleanall to a central recipe like virtual/kernel or core-image-minimal tears down most of the shared state cache for everything depending on it — the next build then takes as long as the very first one again. Apply it to the actually affected recipe specifically, not blanket to the whole image.

Summary

AspectKey takeaway

Multi-layer BSP structure

Worth it once hardware, distro policy, and application vary independently — otherwise one layer suffices

Layer priority

Controls .bbappend conflicts, not the order in bblayers.conf — assign explicitly and uniquely

PACKAGECONFIG

Allows feature toggling without forking the recipe

Rebuild time

clean before cleansstate before cleanall — the more targeted, the faster the next build