If you’re taking this free embedded Linux course seriously, sooner or later you stop
patching the poky/meta directory directly and start your own layer. This lecture is the missing piece
between “I can build core-image-minimal” and “I can maintain my own board support package.” We create
a brand-new layer from scratch, register it correctly, and prove BitBake actually sees it — the same
skill you’ll lean on constantly in any free linux device drivers course or production
BSP work where you’re integrating out-of-tree drivers, custom machine configs, or vendor recipes.
bblayers.conf
bitbake-layers
layer priority
BSP layer
free embedded linux course
What You Will Learn
- Why real BSP work always lives in its own layer
- Creating a layer skeleton with bitbake-layers create-layer
- Registering a layer in build/conf/bblayers.conf by hand
- Verifying registration and priority with bitbake-layers show-layers
- What layer priority actually controls
- A working build proving the empty layer doesn’t break anything
Prerequisites
You should already have a working Poky checkout that can build core-image-minimal for QEMU or a
real board (covered earlier in this series), and be comfortable running bitbake from an
initialized build environment. No prior layer-authoring experience is assumed.
Why Everything Custom Belongs in Its Own Layer
Yocto’s entire design rests on the idea that nobody should ever edit poky/meta. Every board vendor,
every product team, every hobbyist adds their own machine configuration, kernel recipe, and application
packages through a separate layer that sits alongside the core layers and is combined by BitBake at
parse time. A layer is nothing more than a directory with a conf/layer.conf file and a predictable
subdirectory structure — recipes-bsp, recipes-kernel, recipes-core, and so on. Keeping your changes in
a layer means you can rebase onto a newer Yocto release, share your BSP with teammates, and version it
in its own git repository without dragging poky’s history along.
├── meta (OpenEmbedded core — never edit)
├── meta-poky (distro policy — never edit)
├── meta-yocto-bsp (reference BSPs — never edit)
└── meta-ep-board (YOUR new layer)
├── conf/
│ └── layer.conf
├── recipes-bsp/
├── recipes-kernel/
└── recipes-core/
Step 1 — Generate the Layer Skeleton
Modern Yocto ships a helper that writes the boilerplate for you instead of hand-crafting layer.conf.
From the top of your Poky checkout:
$ cd ~/poky
$ bitbake-layers create-layer ../meta-ep-board
$ tree meta-ep-board
meta-ep-board/
├── conf
│ └── layer.conf
├── COPYING.MIT
├── README
└── recipes-example
└── example
└── example_0.1.bbOpen the generated conf/layer.conf and you’ll find it already sets
BBFILE_COLLECTIONS, BBFILE_PATTERN, and a default
BBFILE_PRIORITY of 6 — one point above the reference BSP layers, which is exactly what you
want for a layer meant to override machine-specific recipes.
Step 2 — Register the Layer for This Build
Generating the layer doesn’t make it part of your current build — that’s controlled per build
directory by build/conf/bblayers.conf. The safest way to add it is again through the
helper, which also validates the path:
$ bitbake-layers add-layer ../meta-ep-boardIf you inspect build/conf/bblayers.conf afterward, you’ll see BitBake appended an
absolute path to the BBLAYERS variable:
BBLAYERS ?= "
/home/ravi/poky/meta
/home/ravi/poky/meta-poky
/home/ravi/poky/meta-yocto-bsp
/home/ravi/poky/meta-ep-board
"You can edit this file by hand too — it’s plain BitBake syntax — but add-layer catches
typos and missing layer.conf files before they cost you a confusing parse error.
Step 3 — Verify BitBake Actually Sees It
Never trust that a layer is registered just because it’s in the conf file — always confirm with the
tool that reads BitBake’s parsed layer database:
$ bitbake-layers show-layers
layer path priority
====================================================================
meta /home/ravi/poky/meta 5
meta-poky /home/ravi/poky/meta-poky 5
meta-yocto-bsp /home/ravi/poky/meta-yocto-bsp 5
meta-ep-board /home/ravi/poky/meta-ep-board 6If your layer is missing from this list, BitBake either couldn’t parse its
layer.conf or the path in bblayers.conf is wrong — check both before assuming
anything deeper is broken.
Understanding Layer Priority
The number on the right of show-layers is BBFILE_PRIORITY, and it decides
which recipe wins when two layers ship a .bb file with the same package name and version.
Higher priority always wins. This is the entire mechanism behind “vendor overrides”: your
meta-ep-board layer at priority 6 can ship a linux-yocto_%.bbappend that
patches the kernel recipe defined at priority 5 in meta, without ever touching core.
| Priority | Typical layer | Wins conflicts against |
|---|---|---|
| 5 | meta, meta-poky, meta-yocto-bsp | nothing — lowest tier |
| 6-9 | Your custom BSP / product layer | core and reference BSP layers |
| 10+ | Site-specific emergency overrides | everything below it |
Step 4 — Prove It With a Real Build
An empty layer that parses cleanly is a good sign, but the real test is a full build. Point
MACHINE at hardware you already have working (a QEMU target is fine here) and build:
$ bitbake core-image-minimalIf this completes with your new layer registered and no parse errors, you’ve confirmed the layer is
wired in correctly and is safe to start filling with real recipes.
Common Mistakes
Relative paths in bblayers.conf
Hand-editing with a relative path that’s correct from one build directory but wrong from another
breaks CI. Let add-layer write the absolute path, or use
${TOPDIR}/../meta-ep-board consistently.
Forgetting BBFILE_PATTERN after a rename
If you rename the layer directory after generation, layer.conf‘s regex-based
BBFILE_PATTERN can stop matching, silently dropping every recipe in the layer from the
build with no error.
Two layers, same priority, same recipe
BitBake will refuse to build and report a “multiple .bb files” error rather than guess. Bump one
layer’s priority instead of deleting a recipe you still need.
Best Practices
- One layer per concern: BSP, product recipes, and distro policy in separate layers
- Keep priority gaps (6, 10, 15) so you can slot new override layers in later
- Commit conf/layer.conf changes with the recipes that need them, not separately
- Run bitbake-layers show-layers in CI as a sanity check before every build
Summary and Key Takeaways
- Custom work always goes in its own layer, never inside poky/meta
- bitbake-layers create-layer and add-layer replace hand-editing conf files
- show-layers is the ground truth for what BitBake actually parsed
- Priority resolves recipe conflicts — higher number always wins
Conclusion
Creating a layer is a five-minute task, but understanding why it exists — isolation, override
priority, and reproducibility — is what separates someone following a tutorial from someone who can
maintain a real BSP. With meta-ep-board registered and verified, the next lecture in this
free linux kernel development course moves on to what actually goes inside a layer:
recipes, and the metadata types BitBake understands.
Frequently Asked Questions
Do I need bitbake-layers, or can I just edit bblayers.conf by hand?
You can edit it by hand — it’s plain shell-style BitBake syntax — but bitbake-layers validates the
layer.conf exists and writes a correct absolute path, which avoids a common class of typo bugs.
What happens if two layers have the same priority?
BitBake only cares about priority when there’s an actual recipe conflict. If no filenames collide,
equal priority is harmless. If they do collide, BitBake raises a build error instead of silently
picking one.
Can a layer depend on another custom layer?
Yes — declare it in layer.conf via LAYERDEPENDS, and BitBake will refuse to parse your layer if the
dependency isn’t also present in bblayers.conf.
Is BBFILE_PRIORITY the same as build order?
No. It only resolves conflicts between recipes of the same name/version across layers — it has no
effect on the order tasks execute in.
Why did my new layer’s recipes not show up in bitbake-layers show-recipes?
Almost always a BBFILE_PATTERN mismatch after renaming the layer directory, or a missing
BBFILE_COLLECTIONS entry — check layer.conf against the generated template.
Should meta-ep-board be its own git repository?
Yes — treating each layer as an independently versioned repository is what lets you pin exact
layer/core combinations per product release.
Keep Building With EmbeddedPathashala
This lecture is part of a completely free embedded Linux course covering toolchains, bootloaders,
kernel porting, root filesystems, and build systems from first principles.
2 Comments