Purpose and Mechanism

A .bbappend file extends or overrides a recipe without modifying the original .bb file. This is the cornerstone of the Yocto layering model: you never fork upstream recipes; you append to them.

When BitBake parses a recipe:

1. Parses the base .bb file
2. Finds all .bbappend files whose name matches (using glob patterns)
3. Applies the .bbappend content in layer priority order (lowest to highest)

The result is as if the .bbappend content were appended to the .bb file, with layer priority deciding which wins in conflicts.

Naming Convention

Original recipe:          meta-oe/recipes-core/busybox/busybox_1.36.1.bb
Version-locked append:    meta-myproduct/recipes-core/busybox/busybox_1.36.1.bbappend
Version wildcard append:  meta-myproduct/recipes-core/busybox/busybox_%.bbappend

The % wildcard matches any version. Use it so your append continues to apply when the upstream recipe is version-bumped.

FILESEXTRAPATHS — Adding File Search Paths

Before adding a local file to SRC_URI in a .bbappend, you must tell BitBake where to find it:

# Prepend THIS file's containing directory to the file search path
# THISDIR = directory containing this .bbappend file
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

# Or with a literal subdirectory:
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

Without this, file://mypatch.patch in SRC_URI will only search the base recipe's directories and fail to find your file.

Common Patterns

Applying Patches

# meta-myproduct/recipes-core/busybox/busybox_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

# Patches are applied in order; git-format-patch output is preferred
SRC_URI:append = " file://0001-enable-httpd-cgi.patch \
                   file://0002-fix-segfault-in-sh.patch"

Changing Build Configuration

# autotools recipe: extend configure flags
EXTRA_OECONF:append = " --enable-my-feature"

# CMake recipe: extend cmake flags
EXTRA_OECMAKE:append = " -DMY_OPTION=ON"

# Kernel: add a config fragment
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI:append = " file://enable-usb-serial.cfg"

Modifying Task Functions

# Add steps AFTER the inherited do_install
do_install:append() {
    install -d ${D}${sysconfdir}/busybox
    install -m 0644 ${WORKDIR}/my-busybox.conf \
        ${D}${sysconfdir}/busybox/busybox.conf
}

# Add steps BEFORE do_configure
do_configure:prepend() {
    export EXTRA_DEFINE="-DPRODUCT_NAME=mydevice"
}

Changing Dependencies

# Add a runtime dependency alongside this package
RDEPENDS:${PN}:append = " ca-certificates"

# Add a build-time dependency
DEPENDS:append = " openssl-native"

Disabling a Recipe

# Prevent this recipe from being built (e.g., replaced by your own version)
python () {
    raise bb.parse.SkipRecipe("Replaced by meta-myproduct version")
}

Task Flag Modifiers

Task flags control scheduling and dependency behaviour:

# Force this task to run even if inputs haven't changed
do_my_task[nostamp] = "1"

# This task depends on another recipe's task completing first
do_compile[depends] = "my-codegen-native:do_populate_sysroot"

# Run do_populate_sysroot for every recipe in DEPENDS before do_configure
do_configure[deptask] = "do_populate_sysroot"

# Recursively run do_package_write_ipk for every RDEPEND
do_build[recrdeptask] += "do_package_write_ipk"

The Override Syntax Change (Honister / 3.4+)

Era	Old syntax	New syntax
Before Honister	SRC_URI_append	SRC_URI:append
Before Honister	do_install_append	do_install:append
Before Honister	RDEPENDS_${PN}	RDEPENDS:${PN}
Before Honister	KERNEL_IMAGETYPE_raspberrypi4	KERNEL_IMAGETYPE:raspberrypi4

The old underscore syntax still parses with a warning in some releases, but the colon syntax is required from Scarthgap onward. Scan your layer for old syntax:

# Find files still using old underscore-based append/prepend
grep -r "_append\|_prepend\|_remove" meta-myproduct/ \
    --include="*.bb" --include="*.bbappend" --include="*.bbclass"
# Any match needs updating to colon syntax

The Full Customization Hierarchy

bitbake.conf                       ← global defaults
    ↓ (layer priority order)
Recipe (.bb)                       ← base package instructions
    ↓ (same layer priority order)
Append files (.bbappend)           ← overlay customizations
    ↓
Inherited classes (.bbclass)       ← injected build logic
    ↓
Final DataStore                    ← :append/:prepend applied last

Contributors: Vasu Grover

Previous pageClasses (.bbclass)

Next pageCreating a New Meta Layer