---
url: /kb/embedded/yocto/creating-meta-layer/index.md
---
# Creating a New Meta Layer

## 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

```bash
# 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-layers
```

## The Generated `layer.conf`

```bash
# 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.wks
```

## Creating a Custom Image Recipe

```bash
# 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:

```bash
bitbake my-product-image
```

## Verifying Layer Health

```bash
# 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
```