Yocto Layers: How to Create and Manage Custom Layers

What exactly is a Yocto layer? There are so many meta-xxx directories — what do they all do?

A Yocto layer is a directory that groups related recipes, configurations, and patches into a reusable module. You stack layers to build a custom Linux image — your board support, your apps, your distro config — without ever touching upstream Poky source. This article covers how the layer model works, how to create custom layers, how to add external BSP layers like meta-raspberrypi, and how to debug common layer errors.

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

Layer Types and Structure

Types of Layers

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

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 (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"

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

Creating a Custom Layer

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

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"
EOF

Adding a Layer to Your Build

Editing bblayers.conf

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

# Or 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 \
  "

Absolute paths are the standard practice. bitbake-layers add-layer also inserts absolute paths.

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

Customizing Existing Recipes

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. See the bbappend practical guide for details.

Adding an External BSP Layer

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

Download the Layers

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

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

Add the Layers and Configure

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

Set the target machine in conf/local.conf:

MACHINE = "raspberrypi4-64"

For the full Raspberry Pi build workflow, see the RPi build guide.

OpenEmbedded Layer Index

The community maintains a searchable index of publicly available layers at the OpenEmbedded Layer Index.

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. You can filter by Yocto release branch (Scarthgap, Kirkstone, etc.) to find compatible layers.

Commonly Used Layers

Common Errors and Fixes

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"

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.

No bb files matched for bbappend

WARNING: No bb files in default matched BBFILE_PATTERN

Cause: You have a .bbappend file in your layer, but no matching .bb recipe exists in any active layer. This often happens after upgrading Yocto — the recipe you were appending may have been renamed or removed.

Fix: Find the correct recipe name in the new release. If the recipe was intentionally removed, delete the orphaned .bbappend. To suppress this as a warning instead of an error during migration, set BB_DANGLINGAPPENDS_WARNONLY = "1" in local.conf.

Debugging Priority Conflicts

When the same recipe exists in multiple layers, the one with the highest BBFILE_PRIORITY wins. This can cause unexpected behavior if you don't realize a recipe is being overridden.

# Show all overlayed recipes (same recipe name in multiple layers)
bitbake-layers show-overlayed

# Show which recipes come from which layers
bitbake-layers show-recipes "busybox"

show-overlayed is your best friend when debugging "why is my recipe being ignored?" scenarios. If a recipe from your custom layer isn't taking effect, check whether a higher-priority layer is overriding it.

FAQ

What's the difference between a layer and a recipe?

A recipe (.bb file) is the build instructions for a single package — where to get the source, how to compile, and where to install. A layer is a directory that groups multiple related recipes, configurations, and patches into a reusable module. Think of recipes as individual instructions and layers as organized folders that contain them.

Can I put everything in one custom layer?

Technically yes, but it's not recommended for larger projects. The common pattern is to separate concerns: one layer for your BSP customizations, one for your application recipes, and one for distro-level configuration. For small projects or prototyping, a single meta-myproject layer is perfectly fine.

What priority number should I use for my custom layer?

The bitbake-layers create-layer command defaults to priority 6. For most custom layers, 6–10 works well. The key rule: your custom layer should have a higher priority than the layers it overrides. Poky's base layers (meta, meta-poky) use priority 5, so 6+ ensures your customizations take precedence.

How do I override a recipe from another layer?

Use a .bbappend file in your own layer. The .bbappend extends or overrides specific parts of the original recipe without modifying the upstream file. Your layer's priority must be equal to or higher than the layer containing the original recipe.

Do I need LAYERSERIES_COMPAT in my layer.conf?

Yes. Since Yocto 2.4 (Rocko), LAYERSERIES_COMPAT is required when BBFILE_COLLECTIONS is set — which is every layer. Without it, BitBake throws a compatibility error. Set it to the Yocto release branch you're targeting (e.g., scarthgap).

How do I find layers for a specific package or board?

Check the OpenEmbedded Layer Index. You can search by layer name, recipe name, or machine name, and filter by Yocto release. It's the most comprehensive directory of community-maintained layers.

Can I use layers from different Yocto releases together?

Generally no. Mixing layers from different releases (e.g., a Kirkstone layer with a Scarthgap build) often causes hard-to-debug errors. Always use layers that match your Yocto release branch. If a layer hasn't been updated, check for a compatible fork or consider the migration guide.

Wrapping Up

• 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

Ready for the next step? Here's where to go from here:

• Writing recipes — package your applications into images
• bbappend practical guide — patterns for customizing existing recipes
• Building Linux for Raspberry Pi — deploy to real hardware

To go deeper into embedded Linux, these books are excellent references.

Related articles:

• How to Write Yocto Recipes: A .bb File Guide
• Yocto bbappend: A Practical Guide with 5 Patterns
• Getting Started with Yocto: Build Your First Linux Image
• Yocto Build Errors: Task-by-Task Debugging Guide
• The Complete Guide to 10x Faster Yocto Builds
• Migrating from Kirkstone to Scarthgap