Creating a New Meta Layer
About 406 wordsAbout 1 min
2025-12-21
The Golden Rule
Never add recipes directly to poky/meta or any upstream layer you don't own. Always create a dedicated layer for your product customizations. This way, git pull on Poky never conflicts with your work.
Step-by-Step Creation
# 1. Navigate to your project root (where poky lives)
cd /opt/yocto
# 2. Create the layer with the correct structure
bitbake-layers create-layer meta-myproduct
# Generated structure:
# meta-myproduct/
# ├── COPYING.MIT
# ├── README
# ├── conf/
# │ └── layer.conf ← auto-generated with correct BBFILE_COLLECTIONS
# └── recipes-example/
# └── example/
# └── example_0.1.bb ← example recipe to delete
# 3. Register the layer in the build
cd poky
source oe-init-build-env ../build
bitbake-layers add-layer ../meta-myproduct
# 4. Verify
bitbake-layers show-layersThe Generated layer.conf
# meta-myproduct/conf/layer.conf
# (auto-generated by bitbake-layers create-layer)
BBPATH .= ":${LAYERDIR}"
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
${LAYERDIR}/recipes-*/*/*.bbappend"
BBFILE_COLLECTIONS += "meta-myproduct"
BBFILE_PATTERN_meta-myproduct = "^${LAYERDIR}/"
BBFILE_PRIORITY_meta-myproduct = "6"
# Add your dependencies and compatibility:
LAYERDEPENDS_meta-myproduct = "core"
LAYERSERIES_COMPAT_meta-myproduct = "scarthgap styhead"Update BBFILE_PRIORITY to 10 for a product layer that should override BSP and OE layers.
Recommended Layer Structure
meta-myproduct/
├── conf/
│ ├── layer.conf
│ └── machine/ # Only if this is also a BSP layer
│ └── my-board.conf
├── classes/ # Custom .bbclass files
│ └── my-deploy-hook.bbclass
├── recipes-myapp/ # Custom applications
│ └── myapp/
│ ├── myapp_1.0.bb
│ └── files/
│ └── 0001-fix-crash.patch
├── recipes-core/ # Overrides/appends to core recipes
│ └── busybox/
│ ├── busybox_%.bbappend
│ └── busybox/
│ └── my-busybox.cfg
├── recipes-kernel/ # Kernel config fragments
│ └── linux/
│ ├── linux-yocto_%.bbappend
│ └── linux-yocto/
│ └── enable-cdc-acm.cfg
├── recipes-images/ # Custom image recipes
│ └── images/
│ └── my-product-image.bb
└── wic/ # WKS partition layout files
└── my-board-sdcard.wksCreating a Custom Image Recipe
# meta-myproduct/recipes-images/images/my-product-image.bb
# Inherit core-image to get IMAGE_FEATURES handling and do_rootfs/do_image tasks
require recipes-core/images/core-image-minimal.bb
SUMMARY = "My product Linux image"
# Add packages on top of everything core-image-minimal includes
IMAGE_INSTALL:append = " \
myapp \
nginx \
python3 \
packagegroup-my-iot-core \
"
# Add image-level feature flags
IMAGE_FEATURES:append = " ssh-server-openssh"
# Set the image name
IMAGE_BASENAME = "my-product-image"Build with:
bitbake my-product-imageVerifying Layer Health
# Confirm layer is registered and at expected priority
bitbake-layers show-layers
# Check that LAYERSERIES_COMPAT matches current Yocto release
bitbake-layers show-layers 2>&1 | grep -i compat
# Confirm your recipes are visible
bitbake-layers show-recipes | grep myapp
# Check for override conflicts with other layers
bitbake-layers show-overlayed