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:
meta-<layername>/recipes-<category>/<package>/<package>_<version>.bb
For example:
meta-nova/recipes-local/helloworld/helloworld_1.0.bb
Standard BitBake Tasks
Every recipe is broken into a pipeline of standard tasks:
| Task | Description |
|---|---|
do_fetch | Download the source code from the URI specified in SRC_URI |
do_unpack | Extract the downloaded archive into the work directory |
do_patch | Apply any patches listed in SRC_URI |
do_configure | Run the build system configuration step (autoconf, cmake, etc.) |
do_compile | Compile the source code |
do_install | Install compiled files to the staging area ${D} |
do_package | Package installed files for distribution |
do_build | Default task — runs the full pipeline |
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:
| Extension | Type | Description |
|---|---|---|
.bb | Recipe | Build instructions for one software component |
.bbappend | Append | Extends or modifies an existing .bb recipe |
.inc | Include | Common content shared by multiple recipes (include / require) |
.bbclass | Class | Reusable classes that can be inherited (inherit) |
.conf | Configuration | Build 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
meta-nova/recipes-local/helloworld/
├── files/
│ └── helloworld.c
└── helloworld_1.0.bb
helloworld_1.0.bb
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
| Variable | Description |
|---|---|
DESCRIPTION | Human-readable description of the package |
LICENSE | SPDX license identifier |
LIC_FILES_CHKSUM | License file path and checksum |
SRC_URI | Location of source files (URL, git, local files) |
S | Source 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:
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:
# 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):
bitbake helloworld
Output binaries are in:
tmp/work/cortexa8hf-vfp-neon-poky-linux-gnueabi/helloworld/1.0-r0/
An installable RPM package is produced at:
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:
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:
bitbake core-image-minimal
The binary will be installed at /usr/bin/helloworld in the root filesystem.
Task Management
List Tasks for a Recipe
bitbake -c listtasks core-image-minimal
Run a Specific Task
bitbake -c fetch busybox
bitbake -c compile linux-yocto
Fetch All Sources
bitbake -c fetchall core-image-minimal
Clean a Recipe
bitbake -c cleanall busybox
Debug a Recipe Interactively
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
meta-myproduct/recipes-homeassistant/python3-homeassistant_2023.11.0.bbappend
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
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.
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.