Yocto Root Filesystem Postprocessing: Find Which Task Changed a Delivered File

A configuration file inside the final image differs from the file shipped by its package. The package recipe may be correct: an image-level hook, package installation script, or later image task may have changed the file. Find the first boundary at which its contents diverge before adding another modification.

This article uses Yocto Project 5.0.12 task and variable documentation. It follows an illustrative /etc/product-release file through image construction. The filename is an example, and no build output or execution result is presented as an observed fact.

Compare one file at meaningful boundaries

Record the expected bytes, mode, ownership, and whether the path is a regular file or a symbolic link. Preserve the current final image for analysis. Comparing a symlink's text with the contents of its target can otherwise create a misleading difference before any build-stage investigation begins.

Inspect the file in the recipe's install staging area, the resulting package, the image root filesystem directory, and the final filesystem artifact. Use hashes for byte comparisons and separate records for metadata. Do not compare a work directory from one build against an image produced by another configuration.

If the package already contains the unexpected contents, return to the recipe's install and packaging process. If the package is correct but the assembled rootfs differs, focus on package installation and rootfs processing. If the rootfs directory is correct but the delivered filesystem differs, investigate the later image-creation path.

Use the task model to choose the right investigation

The Yocto task reference places root filesystem construction and its postprocessing before image generation. It describes do_image and the generated image-format tasks, followed by do_image_complete. The latter runs image-output postprocessing.

This order matters when choosing a hook. A change to an unpacked rootfs tree must occur before the filesystem artifact consuming that tree is created. A function that runs after output creation cannot be assumed to retroactively update files already embedded in an image.

Map the example file to that sequence. Write down the task that should produce its final contents and the first task that consumes those contents. This gives the investigation a concrete ordering question instead of a vague search for a script that happens to mention the filename.

Inspect the effective rootfs hooks

The ROOTFS_POSTPROCESS_COMMAND reference describes functions called after root filesystem creation. Its functions can use IMAGE_ROOTFS to locate the tree under construction. Keep the destination relative to that build-controlled root, not an absolute path on the host.

Run bitbake -e product-image, replacing the example image name, and inspect the effective hook list and the definitions of relevant functions. Follow their assignment history into recipes, includes, and classes. A hook visible in one layer may be replaced or augmented by later metadata.

Read the task logs and generated task implementation in the image recipe's work directory. The Yocto debugging guide explains task log and run-file locations. Use those files to establish what was scheduled and what errors occurred; metadata text alone does not prove successful execution.

Search for both the complete path and the basename. A function may construct the path from IMAGE_ROOTFS and a directory variable. Also inspect package post-installation logic when the divergence first appears during rootfs assembly. Do not assume every change after packaging came from the named postprocess hook.

Give the customization an appropriate owner

If the file is part of an application's installed interface and should follow that application into different images, prefer a recipe-owned file. Its source, install action, and package ownership can then be reviewed together. This also makes package replacement behavior easier to reason about.

If the file describes the complete image composition, an image-specific function may be appropriate. Make its inputs explicit and its output narrowly scoped. Avoid a generic hook that rewrites many unrelated configuration files because those changes become difficult to attribute to a single product requirement.

Consider the consequence of overwriting a package-owned file after package installation. The image now differs from that package's original payload. Decide whether a future package upgrade may restore different contents, and document that relationship if runtime package management is supported. An image hook should not silently masquerade as the package's own default configuration.

Verify ordering with a minimal diagnostic change

In a disposable build, add a clearly named diagnostic around the suspected function to record the target file's hash before and after the change. Keep the diagnostic output outside the delivered root filesystem unless it is intentionally part of the product. Remove temporary instrumentation after establishing the responsible stage.

Test the function's behavior when its expected input is missing. It should fail clearly or follow a documented fallback, not report success after modifying nothing. Avoid commands that hide errors behind unconditional success, because they make a hook appear reliable while leaving the image inconsistent.

Check repeat execution as well. A function that appends the same line each time can accumulate duplicate content during development. Prefer a deterministic transformation with explicit preconditions, and confirm the resulting bytes rather than only checking that the function name appears in a log.

Inspect the final artifact and first boot separately

The IMAGE_POSTPROCESS_COMMAND reference applies after final image output files are created. Use that distinction when deciding whether a later action is checking an artifact or changing its contents. Re-extract the file from the final artifact after the corrected build.

If the file changes only after boot, investigate runtime initialization, overlays, or provisioning rather than continuing to edit build-time hooks. Preserve the preboot and postboot states as separate evidence. The completed diagnosis should name the exact function or runtime writer responsible, its inputs, and the stage at which the delivered file becomes final.