What a Layer Is

A layer is a directory containing a conf/layer.conf file that registers it with BitBake. Everything else — recipes, classes, machine configs, bbappends — is optional content the layer contributes.

The fundamental value of layers is separation of concerns without forking. When your product needs to change how busybox is configured, you create a .bbappend in your product layer instead of modifying the upstream busybox_1.36.1.bb in oe-core. When oe-core upgrades to busybox_1.37.0.bb, your .bbappend with a % wildcard continues to apply automatically.

conf/layer.conf — Anatomy

A complete layer.conf for a custom product layer:

# Add this layer's path to BitBake's search path
BBPATH .= ":${LAYERDIR}"

# Where BitBake should look for .bb and .bbappend files
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
             ${LAYERDIR}/recipes-*/*/*.bbappend"

# Internal name for this layer (must be unique across all layers)
BBFILE_COLLECTIONS += "meta-myproduct"

# All .bb/.bbappend files belonging to this collection
BBFILE_PATTERN_meta-myproduct = "^${LAYERDIR}/"

# Priority: higher number wins when two layers define conflicting recipes
BBFILE_PRIORITY_meta-myproduct = "10"

# Other layers this layer requires
LAYERDEPENDS_meta-myproduct = "core openembedded-layer"

# Yocto releases this layer is tested against
LAYERSERIES_COMPAT_meta-myproduct = "scarthgap styhead"

BBFILE_PRIORITY is the conflict resolution mechanism: if both meta-oe (priority 6) and meta-myproduct (priority 10) provide a recipe for openssl, meta-myproduct's version wins. This is how you override upstream recipes without forking.

Layer Types and Priority Ranges

Type	Priority	Examples	Purpose
oe-core	5	meta	Minimal cross-arch base
Distribution	5	meta-poky	Distro policy, preferred versions
OpenEmbedded	6–7	meta-oe, meta-python, meta-multimedia	Broad recipe collection
BSP / Machine	8–9	meta-raspberrypi, meta-ti, meta-freescale	Hardware support
Product / Custom	10+	meta-myproduct	Application recipes and overrides

bblayers.conf — Registering Layers

# build/conf/bblayers.conf
BBPATH = "${TOPDIR}"

BBLAYERS ?= " \
  /opt/yocto/poky/meta \
  /opt/yocto/poky/meta-poky \
  /opt/yocto/poky/meta-yocto-bsp \
  /opt/yocto/meta-openembedded/meta-oe \
  /opt/yocto/meta-openembedded/meta-python \
  /opt/yocto/meta-raspberrypi \
  /opt/yocto/meta-myproduct \
"

Manage this file with bitbake-layers commands rather than editing by hand:

# Add a layer (validates LAYERDEPENDS and LAYERSERIES_COMPAT)
bitbake-layers add-layer /opt/yocto/meta-myproduct

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

# See all recipes and which layer provides each
bitbake-layers show-recipes

# Find recipes that are shadowed by higher-priority layers
bitbake-layers show-overlayed

BSP Layer vs Feature Layer

BSP Layer (e.g., meta-raspberrypi): Contains machine .conf files, kernel recipes, bootloader recipes, and hardware-specific userspace. Governed by the silicon/board vendor.

meta-raspberrypi/
├── conf/
│   ├── layer.conf
│   └── machine/
│       ├── raspberrypi4-64.conf   # DEFAULTTUNE, serial console, etc.
│       └── raspberrypi5.conf
├── recipes-bsp/
│   └── bootfiles/              # GPU firmware, config.txt, etc.
├── recipes-kernel/
│   └── linux/
│       └── linux-raspberrypi_6.6.bb
└── wic/
    └── sdimage-raspberrypi.wks  # SD card partition layout

Feature Layer (e.g., meta-python): Adds capabilities without owning any machine. No conf/machine/ directory. Can be used with any MACHINE.

Creating a Custom Layer

# From the poky directory with build env sourced
bitbake-layers create-layer ../../meta-myproduct

# The generated structure:
# meta-myproduct/
# ├── conf/layer.conf      (pre-filled with correct BBFILE_COLLECTIONS)
# ├── COPYING.MIT
# └── README

# Register it immediately
bitbake-layers add-layer ../../meta-myproduct

Always place your layer outside the poky/ directory so it survives git pull on Poky.

Contributors: Vasu Grover

Previous pageBuild Process Flow

Next pageBitBake Recipes (.bb files)