Yocto Layers Explained: How to Create and Add meta-xxx Layers

"What exactly is a Yocto layer?"

"There are so many meta-xxx directories — what do they all do?"

"I want to add the Raspberry Pi BSP layer to my build."

If you've spent any time with Yocto, you've run into these questions. Layers are the most important concept in Yocto — get them right and everything else falls into place. This article explains how layers work and walks you through creating your own.

Prerequisites

• You understand the basics of Yocto (BitBake, recipes)
• You've successfully built core-image-minimal with Poky

Not there yet? Start with the Yocto Beginner's Guide first.

What You'll Learn

• What layers are and why they matter
• The different types of layers (BSP, distribution, software)
• How to create a custom layer
• How to add external layers (like meta-raspberrypi)
• How to configure layer.conf and bblayers.conf
• How to customize existing recipes with .bbappend

What Is a Yocto Layer?

A layer is a directory that groups related recipes, configuration files, and patches into a logical module.

Yocto's build system works by stacking multiple layers on top of each other. Each layer can override or extend what's below it. This is what allows you to customize your system without ever touching the upstream source.

A higher-priority layer can override a recipe in a lower-priority layer. If the same recipe exists in multiple layers, the one with the highest priority wins.

Why Are Layers Necessary?

• Reusability — the same layer can be shared across multiple projects
• Maintainability — your changes stay separate from upstream. When you upgrade Poky, your customizations don't get wiped out
• Team collaboration — BSP work, application work, and distro configuration can be owned by different people
• Version control — each layer can live in its own Git repository

One of the most common mistakes beginners make is editing Poky's source directly. Don't do this. The moment you upgrade Poky, all your changes disappear.

Types of Layers

In your own projects, always create a custom layer and put your recipes and patches there.

Layer Directory Structure

All layers follow the same basic structure:

meta-mylayer/
├── conf/
│   └── layer.conf          # Layer configuration (required)
├── COPYING.MIT             # License file
├── README                  # Layer description
├── recipes-bsp/            # BSP recipes
├── recipes-core/           # Core system recipes
├── recipes-example/        # Example recipes
│   └── myapp/
│       ├── myapp_1.0.bb
│       └── files/
├── recipes-kernel/         # Kernel-related recipes
├── recipes-graphics/       # Graphics recipes
└── classes/                # Shared class files (.bbclass)

The recipes-* directory naming is a convention. BitBake automatically discovers recipes inside directories matching this pattern.

Inside layer.conf

conf/layer.conf is the layer's identity card. Without it, Yocto won't recognize the directory as a layer.

# conf/layer.conf

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

# Tell BitBake where to find recipes in this layer
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"

# Give this layer a unique collection name
BBFILE_COLLECTIONS += "meta-mylayer"
BBFILE_PATTERN_meta-mylayer = "^${LAYERDIR}/"

# Layer priority — higher number wins when recipes conflict (6–10 is typical for custom layers)
BBFILE_PRIORITY_meta-mylayer = "6"

# Which Yocto releases this layer is compatible with
LAYERSERIES_COMPAT_meta-mylayer = "scarthgap styhead"

# Other layers this layer depends on
LAYERDEPENDS_meta-mylayer = "core"

Creating a Custom Layer

Method 1: Using bitbake-layers (Recommended)

The easiest and most reliable approach is to use the bitbake-layers command.

# Enter the build environment
$ cd ~/yocto/poky
$ source oe-init-build-env build

# Navigate to the parent directory and create the layer
$ cd ..
$ bitbake-layers create-layer meta-myproject

# Inspect the generated files
$ ls meta-myproject/
conf  COPYING.MIT  README  recipes-example

$ cat meta-myproject/conf/layer.conf

Method 2: Manual Creation

Creating the layer manually is a great way to understand what each piece does.

# Create the directory structure
$ mkdir -p meta-myproject/conf
$ mkdir -p meta-myproject/recipes-example/myapp

# Write layer.conf
$ cat > meta-myproject/conf/layer.conf << 'EOF'
BBPATH .= ":${LAYERDIR}"
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"
BBFILE_COLLECTIONS += "meta-myproject"
BBFILE_PATTERN_meta-myproject = "^${LAYERDIR}/"
BBFILE_PRIORITY_meta-myproject = "6"
LAYERSERIES_COMPAT_meta-myproject = "scarthgap styhead"
EOF

Adding a Layer to Your Build

Editing bblayers.conf

# Method 1: Using the command (recommended)
$ cd ~/yocto/poky
$ source oe-init-build-env build
$ bitbake-layers add-layer ../meta-myproject

# Method 2: Edit the file directly
$ nano conf/bblayers.conf

Example conf/bblayers.conf:

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

Always use absolute paths here. Relative paths don't work.

Verifying and Removing Layers

# List all active layers
$ bitbake-layers show-layers

layer                 path                                      priority
==========================================================================
meta                  /home/user/yocto/poky/meta                 5
meta-poky             /home/user/yocto/poky/meta-poky            5
meta-yocto-bsp        /home/user/yocto/poky/meta-yocto-bsp       5
meta-myproject        /home/user/yocto/meta-myproject            6

# Remove a layer from the build (files are not deleted)
$ bitbake-layers remove-layer meta-myproject

Adding an External BSP Layer (meta-raspberrypi)

Here's a practical example: adding Raspberry Pi support with meta-raspberrypi.

Step 1: Download the Layers

# Clone into the same parent directory as Poky
$ cd ~/yocto
$ git clone -b styhead git://git.yoctoproject.org/meta-raspberrypi

# meta-openembedded is a dependency of meta-raspberrypi
$ git clone -b styhead git://git.openembedded.org/meta-openembedded

Step 2: Add the Layers

$ cd ~/yocto/poky
$ source oe-init-build-env build

# Add meta-oe (required by meta-raspberrypi)
$ bitbake-layers add-layer ../meta-openembedded/meta-oe

# Add meta-raspberrypi
$ bitbake-layers add-layer ../meta-raspberrypi

# Verify
$ bitbake-layers show-layers

Step 3: Set the Target Machine

# Edit conf/local.conf
$ nano conf/local.conf

# Change MACHINE to your target
MACHINE = "raspberrypi4-64"

# Available machines:
# raspberrypi      - Raspberry Pi 1
# raspberrypi2     - Raspberry Pi 2
# raspberrypi3     - Raspberry Pi 3
# raspberrypi3-64  - Raspberry Pi 3 (64-bit)
# raspberrypi4     - Raspberry Pi 4
# raspberrypi4-64  - Raspberry Pi 4 (64-bit)
# raspberrypi5     - Raspberry Pi 5

Finding Layers: OpenEmbedded Layer Index

The community maintains a searchable index of publicly available layers:

https://layers.openembedded.org

Search for things like "raspberrypi", "qt5", or "nodejs" and you'll find layers that provide support. Before writing a recipe from scratch, always check here first.

Commonly Used Layers

Customizing Recipes with .bbappend

When you need to modify an existing recipe, never edit the original file. Use a .bbappend file in your own layer instead. This is Yocto's non-destructive customization pattern.

# Example: applying a custom patch to busybox
# meta-mylayer/recipes-core/busybox/busybox_%.bbappend

# Add your patch files directory
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI += "file://my-fix.patch"

# Add a configure option
EXTRA_OECONF += "--enable-feature-x"

The % in the filename is a wildcard that matches any version. This means your .bbappend will still work even after Poky upgrades the package version.

Common Errors and Fixes

Error: Layer 'xxx' is not compatible

ERROR: Layer xxx is not compatible with the current version

Cause: The LAYERSERIES_COMPAT in layer.conf doesn't match the active Yocto branch.

Fix: Update LAYERSERIES_COMPAT in your layer's layer.conf:

LAYERSERIES_COMPAT_meta-mylayer = "scarthgap styhead"

Error: Layer depends on 'xxx'

ERROR: Layer xxx depends on layer xxx

Cause: A required dependency layer hasn't been added yet.

Fix: Add the dependency layer first with bitbake-layers add-layer.

Summary: Layer Management Best Practices

• Always put your recipes in a custom layer — never edit Poky directly
• Use .bbappend to modify existing recipes — keep upstream files untouched
• Name your layers with the meta- prefix — it's the established convention
• Set LAYERSERIES_COMPAT correctly — prevents mysterious compatibility errors
• Keep each layer in its own Git repository — essential for team development

Once you internalize the layer concept, Yocto's architecture starts to make intuitive sense. It's really just "put related things in folders and stack them." The power comes from how cleanly it separates concerns.

Next Steps

• Yocto Project Complete Beginner's Guide
• How to Write Custom Yocto Recipes
• Building Linux for Raspberry Pi with Yocto

This article reflects the state of Yocto Project as of January 2026. Procedures may change as new versions are released.