ES: Yocto Layers | Amr Tarek

Layers are how the Yocto Project organises its metadata — recipes, configuration files, classes, and machine support packages. Every piece of build knowledge in Yocto lives inside a layer, and building a custom embedded Linux system means composing the right set of layers for your product.

What is a Layer?

A layer is a directory of metadata that follows a specific structure convention. By convention, all layer names begin with meta-.

meta-mylayer/
├── conf/
│   └── layer.conf          (required — configures the layer)
├── recipes-*/              (recipe directories)
│   └── <category>/
│       └── <recipe>.bb
├── classes/                (optional shared classes)
├── README                  (recommended)
└── COPYING.MIT             (license file)

The core requirement for any layer is conf/layer.conf. Everything else is optional but strongly recommended.

Core Yocto Layers

The Yocto Project itself is composed of three core layers:

Layer	Description
`meta`	OpenEmbedded Core — fundamental recipes shared with the entire OE community
`meta-poky`	Yocto-specific metadata for the Poky reference distribution
`meta-yocto-bsp`	Board Support Packages for Yocto's reference machines

These three layers are always included in any Yocto build.

Community Layers

The open-source community maintains hundreds of layers for specific hardware platforms, applications, and distributions. A useful index is available at:

`http://layers.openembedded.org`

Some notable community layers:

Layer	Description
`meta-raspberrypi`	BSP for Raspberry Pi boards
`meta-intel`	BSPs for Intel CPUs and SoCs
`meta-ti`	BSPs for Texas Instruments ARM-based SoCs
`meta-fsl-arm`	BSPs for NXP/Freescale ARM SoCs
`meta-qt5`	Qt5 libraries and development utilities
`meta-angstrom`	The Ångström embedded Linux distribution

Creating a Custom Layer

Yocto provides a tool to create a new layer with the correct structure automatically.

Using bitbake-layers

cd poky
scripts/bitbake-layers create-layer nova

The tool prompts:

Please enter the layer priority you'd like to use: [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-nova.
Don't forget to add it to your BBLAYERS.

Where nova is the layer name — the tool creates a meta-nova directory.

Layer Configuration File

The generated meta-nova/conf/layer.conf looks like:

# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"

# We have recipes-* directories, add to BBFILES
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
${LAYERDIR}/recipes-*/*/*.bbappend"

BBFILE_COLLECTIONS += "nova"
BBFILE_PATTERN_nova = "^${LAYERDIR}/"
BBFILE_PRIORITY_nova = "6"

Variable	Purpose
`BBPATH`	Adds this layer's directory to the BitBake search path
`BBFILES`	Glob patterns for locating recipe files in this layer
`BBFILE_COLLECTIONS`	Registers this layer with a unique collection name
`BBFILE_PATTERN_*`	Pattern to identify files belonging to this layer
`BBFILE_PRIORITY_*`	Priority for resolving conflicts (higher = higher priority)

Adding a Layer to the Build

After creating or downloading a layer, register it in the build by editing build/conf/bblayers.conf:

LCONF_VERSION = "6"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
    /home/amr/poky/meta \
    /home/amr/poky/meta-yocto \
    /home/amr/poky/meta-yocto-bsp \
    /home/amr/poky/meta-nova \
    "

BBLAYERS_NON_REMOVABLE ?= " \
    /home/amr/poky/meta \
    /home/amr/poky/meta-yocto \
    "

Or use the bitbake-layers command:

bitbake-layers add-layer /home/amr/poky/meta-nova

Managing Layers with bitbake-layers

# Add a layer
bitbake-layers add-layer <layer-path>

# List all configured layers
bitbake-layers show-layers

# Show recipes provided by each layer
bitbake-layers show-recipes

Example output of show-layers:

layer                 path                       priority
================================================================
meta                  /home/amr/poky/meta              5
meta-poky             /home/amr/poky/meta-poky         5
meta-yocto-bsp        /home/amr/poky/meta-yocto-bsp    5
meta-nova             /home/amr/poky/meta-nova          6

Layer Priority and Conflicts

When two layers provide a recipe with the same name, BitBake uses BBFILE_PRIORITY to decide which one takes precedence. A higher priority number wins.

This allows custom layers to override recipes from lower-priority layers:

meta (priority 5)         --> provides busybox_1.35.bb
meta-nova (priority 6)    --> provides busybox_1.36.bb (override)

Result: BitBake uses busybox_1.36.bb from meta-nova

Layer Structure Best Practices

meta-mylayer/
├── conf/
│   ├── layer.conf              (required)
│   └── machine/
│       └── mymachine.conf      (if adding BSP)
├── recipes-core/               (overrides to core packages)
├── recipes-kernel/             (kernel recipes/appends)
├── recipes-apps/               (application recipes)
├── classes/                    (reusable class files)
├── README
└── COPYING.MIT

Organise recipes into recipes-<category>/ subdirectories following the naming convention used in the core layers.

Final Thoughts

Layers are the modular building blocks of any Yocto project. Separating concerns into distinct layers — board support, applications, custom configurations — makes the build system maintainable, shareable, and upgradeable.

Layer Composition for a Product:
meta                (core OE recipes)
meta-poky           (Yocto distribution settings)
meta-yocto-bsp      (reference board support)
meta-raspberrypi    (target hardware BSP)
meta-qt5            (application framework)
meta-myproduct      (custom recipes, configs, app)
    |
    v
bitbake my-product-image

Every Yocto project should have at least one custom meta- layer where product-specific recipes, configurations, and overrides live.