Layers are the single most important organizational concept in the Yocto Project, and understanding them well is what separates someone who can run a prebuilt BSP from someone who can actually customize one. This lecture, part of our free linux development course, explains what a layer really is, how BitBake decides which layer’s recipe wins when several provide the same thing, and walks through creating your own layer from scratch for a fictional board.
What You Will Learn
- What a Yocto layer actually is, and why the build system is organized this way at all
- The role of the core layers every build starts with
- How BitBake resolves conflicts when the same recipe exists in more than one layer
- How to scaffold and register a brand-new custom layer
- Practical conventions for naming and organizing your own layers
Prerequisites
This lecture builds directly on the previous one in this free linux kernel development course, where you built and booted a core-image-minimal image. You should already have a working build directory with the environment setup script sourced.
Why Layers Exist
A Yocto build has to combine three very different kinds of concerns: generic Linux distribution metadata, board-specific support (BSP) for your exact hardware, and your own application or product-specific customizations. If all of that lived in one giant tree, sharing and reusing any single piece — say, a BSP for a chip vendor’s reference board — would be impossible without dragging along everything else. Layers solve this by giving each concern its own self-contained, independently versioned tree of recipes and configuration that BitBake can combine at build time.
By convention every layer directory name begins with meta. This is a naming convention only — nothing in BitBake enforces the prefix — but it’s followed so consistently across the ecosystem that any experienced Yocto developer will recognize a directory like meta-nova as a layer on sight.
The Core Layers
Every standard Yocto build starts with a small set of foundational layers already present:
| Layer | Provides |
|---|---|
| meta | OpenEmbedded core — the base recipe classes and core packages nearly everything else depends on |
| meta-poky (distro layer) | The reference distribution’s policy and configuration on top of OpenEmbedded core |
| meta-yocto-bsp | Board support packages for the Yocto Project’s own reference machines, including the QEMU targets |
Each layer in that stack can add new recipes, and critically, can also override settings or even entire recipes from layers earlier in the stack. This is what makes a custom BSP layer able to say “use this kernel config instead of the generic one” without having to fork and modify the core layer itself.
How BitBake Finds and Orders Layers
The list of active layers for a given build directory lives in a single file:
<build-dir>/conf/bblayers.confThis file simply lists filesystem paths to each layer you want included. BitBake reads every layer’s own conf/layer.conf to learn what recipes that layer contributes and at what priority.
Priority matters because more than one layer is often able to provide the exact same recipe — for example, two different BSP layers might both ship a variant of the same package with board-specific patches. When that happens, BitBake does not error out; it picks the version from whichever contributing layer has the higher declared priority. This is the mechanism that lets a vendor BSP layer cleanly override a generic recipe from core without editing core at all.
Anatomy of a Layer’s layer.conf
Every layer needs at minimum a conf/layer.conf file. Here is an original, minimal example for a fictional layer named ep-demo, explained line by line:
# Add this layer's conf and classes directories to BitBake's search path
BBPATH .= ":${LAYERDIR}"
# Tell BitBake where to find recipes contributed by this layer
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
${LAYERDIR}/recipes-*/*/*.bbappend"
# Register this layer under the name "ep-demo"
BBFILE_COLLECTIONS += "ep-demo"
BBFILE_PATTERN_ep-demo = "^${LAYERDIR}/"
# Priority used to resolve conflicts with other layers (higher wins)
BBFILE_PRIORITY_ep-demo = "7"BBFILES tells BitBake which file patterns count as recipes within this layer — normal recipes end in .bb, and recipes that only extend or patch an existing recipe from another layer end in .bbappend. BBFILE_COLLECTIONS registers the layer’s name, and BBFILE_PRIORITY is the number that resolves any conflict against other layers providing the same recipe.
Scaffolding a New Layer
Rather than writing this file by hand every time, Yocto ships a helper script that generates a correctly structured layer for you:
$ cd poky
$ scripts/yocto-layer create ep-demoThe script interactively asks two questions: what priority to assign, and whether to generate example recipe and bbappend files to start from.
Please enter the layer priority you'd like to use for the layer: [default: 6]
Would you like to have an example recipe created? (y/n) [default: n]
Would you like to have an example bbappend file created? (y/n) [default: n]
New layer created in meta-ep-demo.
Don't forget to add it to your BBLAYERS (for details see meta-ep-demo/README).This produces a meta-ep-demo directory containing a populated conf/layer.conf, a starter README, and a default MIT license file. The final manual step the script reminds you about is registering the new layer’s path inside bblayers.conf so BitBake actually picks it up on the next build.
A Worked Example: Overriding One Setting From a Recipe
To make the override mechanism concrete, here’s an original, minimal .bbappend that lives in our fictional meta-ep-demo layer and adds one extra file to an existing image recipe, without touching the original recipe at all:
# File: meta-ep-demo/recipes-core/images/core-image-minimal.bbappend
IMAGE_INSTALL:append = " ep-hello-tool"Because meta-ep-demo is registered with a priority higher than the core layer, this append is picked up automatically the next time core-image-minimal is built, adding the fictional ep-hello-tool package to the image — a clean, non-invasive way to customize a shared recipe.
Common Mistakes and Troubleshooting
Forgetting to add the new layer to bblayers.conf
The scaffolding script creates the layer directory but does not register it. If your new recipes seem to be silently ignored, check bblayers.conf first.
Two layers with clashing priorities
If two layers claim the same priority and both provide the same recipe, BitBake will refuse to build and report the conflict rather than guessing. Always give custom layers a distinct, deliberately chosen priority.
Layer compatibility with the Yocto release
A layer built for one Yocto release is not guaranteed to work unmodified on a different release. Always check a third-party layer’s declared compatible release before adding it to your build.
Best Practices
- Keep BSP concerns, distro policy, and application customization in separate layers, even for a single product — it keeps each layer independently reusable.
- Prefer
.bbappendfiles over copying and modifying an entire upstream recipe — you inherit upstream fixes automatically. - Choose layer priorities deliberately and document them, especially once a project accumulates more than two or three custom layers.
Security Considerations
Every layer you add to a build has the same level of trust as your own code — a layer’s recipes can fetch arbitrary source and run arbitrary build-time scripts. Only add third-party layers from sources you trust, and review unfamiliar recipes before building them.
Summary and Key Takeaways
- Layers separate core, distro, BSP, and product-specific concerns into independently reusable trees.
bblayers.conflists which layers are active; each layer’s ownlayer.confdeclares its recipes and priority.- Priority resolves conflicts when multiple layers provide the same recipe — highest priority wins.
scripts/yocto-layer createscaffolds a new layer correctly, but you must still register it yourself.
With layers understood, you now have the two pieces that matter most for real embedded Linux work in this free embedded systems course: how a build actually runs, and how to organize your own customizations cleanly on top of it without forking anything upstream.
Frequently Asked Questions
Do layer directory names have to start with “meta”?
No, it’s a strong convention, not a technical requirement. Following it makes your layers instantly recognizable to other Yocto developers.
What happens if two layers provide the same recipe?
BitBake uses each layer’s declared priority to decide which version wins. If both layers have the same priority, BitBake reports a conflict instead of guessing.
What’s the difference between a .bb and a .bbappend file?
A .bb file is a complete, standalone recipe. A .bbappend file extends or overrides an existing recipe from another layer without modifying that layer directly.
Does scripts/yocto-layer create register the layer automatically?
No. It generates the layer directory and configuration files, but you still need to add the layer’s path to bblayers.conf yourself.
Can I use a third-party layer from the OpenEmbedded layer index?
Yes, but always check that the layer declares compatibility with your specific Yocto release before adding it, since layer APIs can change between releases.
Where should I put board-specific kernel configuration?
In your BSP layer, typically as a .bbappend to the kernel recipe, keeping it separate from generic distro or application-layer concerns.
Is there a limit to how many layers a build can use?
No hard limit, but each added layer increases build complexity and the chance of priority conflicts, so keep the layer stack as lean as the project genuinely needs.
Continue This Free Linux Development Course
Next up: writing your first custom recipe from scratch inside your own layer.
Next Lecture Browse Full Course
2 Comments