Yocto Read-Only Root Filesystems: Identify Postinstall Work That Cannot Wait for First Boot

A custom package builds, but adding it to a read-only Yocto image fails during root-filesystem construction. Its post-install script may assume that it can finish on the device, invoke a target executable on the builder, or write through an unprefixed absolute path.

For a root filesystem intended to remain immutable from first boot, the useful question is which outputs can be prepared during image construction and which belong in separately writable runtime state. Silencing the post-install check does not answer that design question.

Find the deferred or failed package operation

The Yocto 5.0.12 read-only-rootfs guide explains the normal requirement: package post-install work must complete while the image filesystem is created. The standard check rejects work left for first boot.

Read the do_rootfs log to identify the package and failing command. Inspect its generated script, including snippets supplied by inherited classes. The recipe's visible pkg_postinst function may not contain every operation that the package manager executes.

Separate three outcomes: an actual script error, an explicitly deferred action, and a command that succeeds without producing the intended file. Returning success early can hide missing initialization, so verify the expected output beneath the constructed root as well as the task result.

Use the correct root and executable context

During image construction, a post-install script uses shell $D to identify the offline root. On the target, that value is empty. A command intended to update an image file must address the offline root when running on the builder, rather than accidentally addressing the builder's own /etc or /var.

For an illustrative generated index at /usr/share/sensor/index, trace both the output pathname and any paths stored inside it. A tool can support an output-directory option while still embedding host-side input paths. Check the tool's actual offline-root interface instead of assuming that prefixing one argument makes the entire operation cross-build safe.

If the script invokes a target-architecture program, ordinary host execution may fail. The guide describes native tools or supported QEMU execution as possible solutions. Prefer an existing class-supported mechanism where available; a handwritten attempt to execute a foreign binary is not equivalent to that integration.

The PACKAGE_WRITE_DEPS reference covers native or cross tools needed by package installation scripts during root-filesystem construction. A tool being available while the recipe compiled does not establish that the rootfs script has declared access to it.

Do not use failure as an implicit deferral mechanism

The post-installation guide documents explicit target deferral through pkg_postinst_ontarget or a delay intercept. It also states that ordinary post-install failures, including exit 1, cause a do_rootfs error. Old recipes that treated any failure as “try again on first boot” need review.

Even explicit deferral conflicts with a design that has no writable root at first boot. If the operation produces deterministic package-derived data, consider generating and packaging it earlier, or completing it with an appropriate native tool during image creation.

If the operation needs device-specific information unavailable on the builder, separate that state from the immutable root. Define its writable destination, creation timing and consumer behavior. A calibration-dependent file and a package-generated cache do not necessarily belong in the same initialization mechanism.

Understand the delayed-postinst exception

The image feature reference also defines read-only-rootfs-delayed-postinsts. Combined with read-only-rootfs, it disables the delayed-script check under the assumption that the root will be writable for first boot. It does not implement that writable state.

Do not add this feature merely to make the build pass. It changes the assumptions that must be satisfied by the boot and storage design. A product intentionally using such a first-boot phase needs to demonstrate how writes complete and how the filesystem returns to its intended state.

Finally, boot the candidate with the intended mount layout and exercise the feature that consumes the generated data. A successful rootfs build establishes that its required installation scripts completed; it does not prove that application startup avoids all later writes to the immutable filesystem.