Yocto Package Renames: Coordinate Runtime Aliases, Replacement and Conflicts

A product renames a runtime package from sensor-tools to sensor-utils. New images build, but a field upgrade reports file ownership conflicts or leaves an old dependent package unsatisfied. Renaming the recipe or output file alone does not describe the transition to the package manager.

Three relationships need separate decisions: which old dependency name the new package can satisfy, which predecessor it replaces, and whether both packages may coexist. The example is illustrative and assumes the new package really preserves the interface expected by old consumers.

Provide the old runtime name deliberately

The RPROVIDES reference defines runtime package aliases. An illustrative RPROVIDES:${PN} += "sensor-tools" lets the new package advertise that old name when ${PN} is the actual new output package.

This does not create a second archive named sensor-tools, and it does not prove behavioral compatibility. Check that the commands, library interfaces or data expected by old dependents still exist. Otherwise the alias can satisfy metadata while leaving the consumer broken at runtime.

Use the output package's override, not an unrelated recipe name. One recipe may emit several packages, and only the package containing the replacement functionality should make the relevant claim.

Describe replacement and coexistence separately

The RREPLACES reference identifies packages replaced during an upgrade. It specifically notes that removing the other package as part of the transition also requires listing it in RCONFLICTS.

For a complete mutually exclusive rename, the new package's metadata might therefore include both RREPLACES:${PN} += "sensor-tools" and RCONFLICTS:${PN} += "sensor-tools", in addition to the runtime alias. These lines describe the intended relationship; the actual transaction still needs verification with the deployed backend.

The RCONFLICTS definition also permits version constraints. Use those when only an older range conflicts, rather than excluding a future package that legitimately reuses the name for a different role.

Do not apply the complete-rename pattern blindly to a package split. If sensor-tools remains supported while its data moves into sensor-data, removing the whole original package may be the wrong transition.

Read the generated backend relationships

The examined Yocto DEB writer emits the three relationships as distinct control fields after processing package-name mappings. Inspect those generated fields, not just the recipe assignments, especially when output package renaming is involved.

There is also a versioned-alias limitation worth checking: this examined writer deliberately discards version information from RPROVIDES. Debian's relationship policy explains that an unversioned Provides entry does not satisfy a versioned dependency. A simple rename test using only unversioned consumers would miss that case.

For DEB replacement behavior, the same policy distinguishes taking over files from resolving whole-package replacement conflicts. This is why a file overlap, a dependency alias and an obsolete predecessor should not be collapsed into one generic “rename” setting.

Exercise the installed predecessor case

Start with the old package and one real dependent installed on a disposable target. Request the new package through the intended update path, then inspect which package owns overlapping files, whether the predecessor remains installed, and whether the dependent remains satisfiable.

Include a dependent with a version constraint if the product uses one. Also test a fresh installation, because success when no predecessor exists cannot validate the replacement path. Compare the package manager's proposed transaction before accepting it in the test environment.

If the transaction succeeds but the old consumer fails, revisit the interface compatibility claimed by RPROVIDES. If files collide, inspect replacement/conflict fields and actual output names. If the new package is never selected, investigate feed availability and dependency resolution separately.

The finished transition is a package relationship that matches the intended installed-state change. It should not rely on manually deleting conflicting files or forcing the package manager past an unresolved ownership error.