ES: Yocto Recipes and Tasks

Recipes are the fundamental unit of build knowledge in the Yocto Project. Each recipe describes how to fetch, configure, compile, and install a software component. Understanding recipe syntax, task structure, and how to write and extend recipes is the core skill of Yocto development.

Recipes are what make the Yocto Project work. Every software component in an embedded Linux image — from BusyBox to the Linux kernel to your custom application — has a corresponding recipe that tells BitBake exactly how to obtain, build, and install it.


What is a Recipe?

A recipe is a collection of tasks written in a combination of Python and shell code. It tells BitBake:

  • Where to find the source code
  • How to configure and compile it
  • Where to install it in the root filesystem
  • What other packages it depends on
  • What license it uses

Recipe files live inside layer directories following the pattern:

md
meta-<layername>/recipes-<category>/<package>/<package>_<version>.bb

For example:

md
meta-nova/recipes-local/helloworld/helloworld_1.0.bb


Standard BitBake Tasks

Every recipe is broken into a pipeline of standard tasks:

TaskDescription
do_fetchDownload the source code from the URI specified in SRC_URI
do_unpackExtract the downloaded archive into the work directory
do_patchApply any patches listed in SRC_URI
do_configureRun the build system configuration step (autoconf, cmake, etc.)
do_compileCompile the source code
do_installInstall compiled files to the staging area ${D}
do_packagePackage installed files for distribution
do_buildDefault task — runs the full pipeline

md
do_fetch
    |
    v
do_unpack
    |
    v
do_patch
    |
    v
do_configure
    |
    v
do_compile
    |
    v
do_install
    |
    v
do_package
    |
    v
do_build


Recipe File Types

There are five types of recipe-related files:

ExtensionTypeDescription
.bbRecipeBuild instructions for one software component
.bbappendAppendExtends or modifies an existing .bb recipe
.incIncludeCommon content shared by multiple recipes (include / require)
.bbclassClassReusable classes that can be inherited (inherit)
.confConfigurationBuild configuration variables
The difference between `include` and `require`: `require` produces an error if the file does not exist; `include` silently ignores a missing file.

All recipes automatically inherit classes/base.bbclass.


Writing a Hello World Recipe

Directory Structure

md
meta-nova/recipes-local/helloworld/
├── files/
│   └── helloworld.c
└── helloworld_1.0.bb

helloworld_1.0.bb

bitbake
DESCRIPTION = "A friendly program that prints Hello World!"
PRIORITY = "optional"
SECTION = "examples"

LICENSE = "GPLv2"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/GPL-2.0;md5=801f80980d171dd6425610833a22dbe6"

SRC_URI = "file://helloworld.c"
S = "${WORKDIR}"

do_compile() {
    ${CC} ${CFLAGS} -o helloworld helloworld.c
}

do_install() {
    install -d ${D}${bindir}
    install -m 0755 helloworld ${D}${bindir}
}

Key Variables

VariableDescription
DESCRIPTIONHuman-readable description of the package
LICENSESPDX license identifier
LIC_FILES_CHKSUMLicense file path and checksum
SRC_URILocation of source files (URL, git, local files)
SSource directory after unpacking
${D}Destination directory (staging area for the target)
${bindir}Binary directory (/usr/bin)
${CC}Cross-compiler (set by the toolchain)
${CFLAGS}Compiler flags

Recipe Licensing

Every recipe must declare its license and the checksum of the license file:

bitbake
LICENSE = "GPLv2"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/GPL-2.0;md5=801f80980d171dd6425610833a22dbe6"

Standard licenses are available in meta/files/common-licenses/. Commercial licenses are disabled by default but can be enabled:

bitbake
# In the recipe
LICENSE_FLAGS = "commercial"

# In conf/local.conf
LICENSE_FLAGS_ACCEPTED = "commercial"


Building a Recipe

Build only the recipe (without the full image):

bash
bitbake helloworld

Output binaries are in:

md
tmp/work/cortexa8hf-vfp-neon-poky-linux-gnueabi/helloworld/1.0-r0/

An installable RPM package is produced at:

md
tmp/deploy/rpm/cortexa8hf_vfp_neon/helloworld-1.0-r0.cortexa8hf_vfp_neon.rpm


Adding a Recipe to the Image

To include the package in the final image, add it to conf/local.conf:

bash
IMAGE_INSTALL:append = " helloworld"

**Important:** The space before the recipe name is mandatory. BitBake appends this string to `IMAGE_INSTALL`, so the space prevents the name from merging with the previous entry.

Then rebuild the image:

bash
bitbake core-image-minimal

The binary will be installed at /usr/bin/helloworld in the root filesystem.


Task Management

List Tasks for a Recipe

bash
bitbake -c listtasks core-image-minimal

Run a Specific Task

bash
bitbake -c fetch busybox
bitbake -c compile linux-yocto

Fetch All Sources

bash
bitbake -c fetchall core-image-minimal

Clean a Recipe

bash
bitbake -c cleanall busybox

Debug a Recipe Interactively

bash
bitbake -c devshell <recipe-name>

This opens a shell with all the build environment variables set, in the recipe's source directory — ideal for debugging compilation issues.


Extending Recipes with .bbappend

A .bbappend file adds to or modifies an existing recipe without changing the original file. This is the standard way to customise upstream recipes in a product layer.

Example: Appending to a Recipe

md
meta-myproduct/recipes-homeassistant/python3-homeassistant_2023.11.0.bbappend

bitbake
SUMMARY = "Open-source home automation platform running on Python 3"

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

SRC_URI += "file://homeassistant.service"

do_install:append() {
    install -d ${D}${systemd_unitdir}/system
    install -m 0644 ${WORKDIR}/homeassistant.service \
        ${D}${systemd_unitdir}/system
}

Example: Applying a Patch via Append

bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI += "file://0001-fix-compilation-issue.patch"


Final Thoughts

Recipes are the unit of work in the Yocto Project. Every software component is a recipe. Every customisation is a .bbappend. Every shared pattern is a class.

md
Recipe Development Flow:
Identify the software to build
    |
    v
Write <package>_<version>.bb
    - Set SRC_URI, LICENSE, LIC_FILES_CHKSUM
    - Write do_compile() and do_install()
    |
    v
bitbake <recipe>  (verify it builds)
    |
    v
IMAGE_INSTALL:append = " <recipe>"
    |
    v
bitbake core-image-minimal  (verify in image)

Mastering recipe writing is the single most important Yocto skill for embedded Linux developers.