What You Will Learn

Prerequisites

Why local.conf Is the Wrong Place for Image Changes

local.conf lives inside your build directory, which is machine-specific and almost always excluded from version control. Any package or feature you add there disappears the moment a teammate clones your metadata layers into a fresh build/ directory. Worse, two developers editing their own local.conf files independently can end up shipping images that silently differ from each other, which is a nightmare to debug six months later when a field device behaves differently from the one on your desk.

The fix is to move anything that defines what the final image contains — packages, image features, filesystem types, root filesystem size — into a proper image recipe that lives in a layer and gets committed alongside your other metadata. That recipe becomes the single source of truth for what “your product’s Linux image” actually is.

Adding and Removing Packages Cleanly

The most direct way to change an image’s package set is the IMAGE_INSTALL variable. Using the modern BitBake override syntax (replacing the older _append/_remove suffix style you may see in older references), you append packages like this:

IMAGE_INSTALL:append = " ep-diag-tool strace"

And remove a package that a lower layer or base image already pulled in with:

IMAGE_INSTALL:remove = "some-unwanted-app"

Note the leading space before the package name in the append line — BitBake concatenates strings literally, so a missing space silently merges two package names into one and your build fails with a confusing “nothing provides” error.

EXTRA_IMAGE_FEATURES: Sweeping Image-Wide Changes

Sometimes you want more than “add this package.” EXTRA_IMAGE_FEATURES (set in local.conf for local experimentation, or IMAGE_FEATURES inside a recipe for something permanent) toggles entire behavior sets defined by core-image.bbclass. The table below covers the ones you will reach for most often:

Writing Your First Custom Image Recipe

The simplest permanent recipe just extends an existing one using require. Suppose you want core-image-minimal plus your own diagnostics tool and strace. Create ep-diag-image.bb inside meta-yourlayer/recipes-local/images/:

DESCRIPTION = "core-image-minimal plus EP diagnostic tooling"
require recipes-core/images/core-image-minimal.bb

IMAGE_INSTALL:append = " ep-diag-tool strace"

Build it exactly like any other image target:

$ bitbake ep-diag-image

Expected tail of a successful build:

NOTE: Executing Tasks
NOTE: Tasks Summary: Attempted 3142 tasks of which 2891 didn't need to be rerun and all succeeded.

Summary: There were 0 WARNING messages shown.

Total Control: Building an Image From Scratch

For a product image, you often don’t want to inherit anything you didn’t explicitly ask for. Start from an empty IMAGE_INSTALL and build up:

SUMMARY = "Minimal EP product image with diagnostics"
IMAGE_INSTALL = "packagegroup-core-boot ep-diag-tool strace"
IMAGE_LINGUAS = " "
LICENSE = "MIT"
IMAGE_ROOTFS_SIZE ?= "8192"

inherit core-image

A quick field guide to the four variables that trip people up most:

Real-World Use Case

A typical pattern in a production embedded Linux project: a shared company-base-image.bb holds packages and features common to every product line, and each board-specific team layer adds a thin recipe that does require company-base-image.bb plus two or three board-specific packages. This keeps the “what’s actually on the device” question answerable by reading one small file instead of grepping through a shared local.conf nobody remembers editing.

Common Mistakes and Troubleshooting

• Missing leading space in append lines — always write IMAGE_INSTALL:append = " pkg", never "pkg".
• Shipping debug-tweaks to production — this feature exists for development images only; a production image with passwordless root is a serious security hole.
• Forgetting inherit core-image in a from-scratch recipe — without it, none of the image-generation tasks exist and BitBake will complain the target has no do_image task.
• Confusing recipe LICENSE with package licensing — the recipe’s LICENSE variable only describes the recipe file itself.

Best Practices

• Keep experimentation in local.conf, but promote anything permanent into a versioned image recipe before it reaches a shared branch.
• Prefer require over duplicating an existing base image recipe — you inherit upstream fixes automatically.
• Set IMAGE_ROOTFS_SIZE with ?= so machine-specific configs can still adjust it for boards with tighter storage.

Summary and Key Takeaways

Image features give you sweeping, class-level control over what an image contains; IMAGE_INSTALL gives you fine-grained package control; and a dedicated, version-controlled image recipe is what turns both into something reproducible across your whole team. Master these three levers and you have full command over what actually ships on your device.

Conclusion

Custom image recipes are the backbone of any serious Yocto-based product, and they are a core skill in this free linux device drivers course. Once you’re comfortable writing them, the next natural step is building a standalone SDK so other developers on your team don’t need a full Yocto build environment just to compile against your image — covered in the next lecture of this free linux kernel development course series.

FAQ