Yocto do_deploy Outputs: Preserve Artifacts Across Shared-State Restore

A custom recipe produces a binary in the image deployment directory
during a local build. On another build machine, BitBake reuses shared
state and the binary is missing. Rebuilding the task manually makes it
appear again. That pattern is a reason to inspect the deployment
contract before blaming the cache server.

This article uses the Yocto Project 5.0.12 task documentation and the
OpenEmbedded scarthgap deploy class inspected on 19 October 2026. The
implementation link is pinned to commit
b4f06303e55c7270a8482a610927a1c41d5dbf9c; downstream commits can differ.
The proposed checks have not been executed.

Identify the owner of the
artifact

Begin with one exact output: its filename, content identity,
producing recipe and intended consumer. Avoid treating every file under
the shared image directory as interchangeable evidence. A file left by
an earlier build can make a broken deployment task look correct until a
clean environment removes that accidental dependency.

Ask where the recipe writes the artifact, which task writes it, and
how that task enters the normal build graph. These are separate
questions. A shell function with the desired name is not sufficient if
the intended build never schedules it, and a scheduled task is not
sufficient if its output bypasses the declared cache mapping.

The do_deploy
reference instructs recipes to inherit the deploy class and write to
DEPLOYDIR. It explicitly warns against writing directly into
DEPLOY_DIR_IMAGE. The task must also be added to the recipe’s task
graph.

Follow both paths to
the final directory

The scarthgap
deploy class declares DEPLOYDIR as the shared-state input directory
and DEPLOY_DIR_IMAGE as the output directory. It registers do_deploy for
shared state and provides its setscene task. It also declares DEPLOYDIR
as a clean task directory.

That mapping explains why a direct write into the final directory is
misleading. The local command may create a visible file without placing
that file inside the output set that the deployment contract expects to
preserve and restore. Inspect the declared path rather than treating
visual presence after one execution as proof of cache correctness.

For a custom artifact, write a short ownership statement: this recipe
places this output under its deployment staging directory, and the class
makes that output available in the machine’s image deployment area. Then
check the implementation against that statement. If another task also
writes the same final name, resolve the ownership conflict before
interpreting restore behavior.

Keep the recipe
example deliberately small

An illustrative custom recipe can inherit deploy, define do_deploy to
install its generated file into DEPLOYDIR, and add that task after its
actual producer. The prerequisite is not always do_compile: choose the
task that really creates the input artifact in this recipe.

Do not copy a binary out of an unrelated recipe’s work directory to
fill the gap. If an input comes from another recipe, express the
relevant task dependency and use an agreed artifact interface. Otherwise
the deployment fix may simply move the undeclared relationship to
another location.

Similarly, avoid assuming that a relative filename identifies the
right machine variant. Record the effective deployment directory and
relevant configuration in the verification evidence. A successful copy
of the wrong variant is still a deployment failure.

Compare a task run with a
restore

Use an isolated verification build so the test does not remove
another developer’s work or shared cache. Preserve the recipe metadata
and build configuration before making changes. Define an expected output
manifest containing names and content digests for the artifact set being
reviewed.

First, observe a build that executes the producing task and
deployment task. Check both the staging output and the final output.
Retain the task log and record which steps ran. Do not infer execution
merely because the file exists; it may predate the current
invocation.

Next, exercise the project’s normal shared-state reuse path in a
fresh output context that does not contain the artifact already. Observe
whether setscene supplies the expected deployment result. Compare
against the manifest, including files that should be absent. A stale
extra file can be just as misleading as a missing required one.

These are proposed tests. A report should state the exact build and
cache conditions used rather than claiming that a single warm build
proves reproducibility across all machines and configurations.

Investigate stale outputs
separately

Suppose the new recipe intentionally stops producing an auxiliary
file. A local directory that still contains the old file can conceal the
change. Preserve the before-and-after manifests and identify which task
owns cleanup for the relevant output scope. Do not solve this by
deleting a broad shared directory during an ordinary build.

The class’s clean staging directory is one important part of the
model, but it is not permission to assume that every external consumer
has discarded its own copied artifact. If a packaging script reads the
final directory later, verify its selection rule and dependency
independently.

Keep filename stability and content stability distinct. A constant
filename can point to changed bytes; a changed filename can leave an old
consumer looking at a previous build. Document which identity the
consumer uses and how release packaging captures the intended
artifact.

Close with a two-path
acceptance rule

The useful acceptance criterion is not “the file appeared after
forcing the task.” It is that both normal task execution and
shared-state restoration supply the declared artifact to the intended
consumer without relying on leftover files.

Record the corrected write location, task relationship and output
manifest. Leave destructive cache cleanup out of the routine repair
unless an isolated test genuinely requires it. A deployment recipe that
respects the declared staging path is easier to explain, review and
validate because the local-build path and the restore path are designed
to meet at the same contract.