Yocto Virtual Providers: Keep Kernel and Toolchain Selection Explicit

An application depends on a virtual interface, and two layers offer implementations. Adding the second layer changes the available choices, but the engineer still needs to establish which implementation the product uses. The same problem appears when a board selects a vendor kernel or a distribution integrates an external toolchain.

This article uses Yocto Project 5.0.12 documentation. It examines provider selection as a build-dependency decision, then follows that decision to the kernel and compiler evidence. It does not report a completed provider migration or claim that alternative implementations are automatically compatible.

Identify the dependency that needs an implementation

Begin at the consumer. Record the actual build-time dependency name and the recipe that declares it. If the dependency is a virtual name, list the recipes advertising that name through PROVIDES. Keep the consumer, alias, and candidate recipe names together in the review record.

The virtual-provider guide describes this mechanism using build-time PROVIDES and DEPENDS. It explicitly distinguishes it from runtime package dependencies. A package installation problem expressed through RDEPENDS should not be diagnosed by changing a build-time virtual provider without establishing the connection.

Ask what the alias promises to the consumer. The metadata name represents a dependency interface; it is not a test result showing that every implementation satisfies every product requirement. Write down the expected headers, tools, kernel artifacts, or other outputs before switching the provider.

Select the kernel recipe by its recipe name

The PREFERRED_PROVIDER reference specifies the provider alias as the variable suffix and the preferred recipe's PN as the value. For a product with an actual recipe named linux-product, an illustrative selection would be PREFERRED_PROVIDER_virtual/kernel = "linux-product".

Confirm that the intended recipe exists in the enabled layers and advertises the virtual name. Then inspect bitbake -e virtual/kernel in the product's configured build environment. Record the selected recipe identity, source revision, and effective provider setting. Do not infer the selected kernel solely from the presence of a vendor layer on disk.

Kernel version selection is a separate step after choosing the implementation. A version preference for one kernel recipe does not select that recipe in place of another provider. Likewise, kernel configuration fragments associated with an unselected provider cannot establish the configuration of the selected kernel.

Keep toolchain selection within its integration contract

An external compiler installation does not become the Yocto toolchain merely because its directory appears first in an interactive shell's PATH. Inspect the metadata integration that supplies the toolchain and the consumer tasks that invoke it.

The external-toolchain guide describes adding the supporting layer, locating the installed toolchain through EXTERNAL_TOOLCHAIN, and using TCMODE to select the corresponding toolchain configuration include. The default mode selects the internally built toolchain. An external mode requires the integration expected by its supporting layer.

Read the selected tcmode-*.inc and associated recipes in the actual checkout. Record the provider assignments that integration makes, rather than copying a list of virtual compiler names from another product or release. Compiler, linker, runtime, and development-file choices need to agree with the integration's supported target configuration.

This article does not prescribe a universal external-toolchain configuration. Different supporting layers can expose different settings. The acceptance requirement is that the product's resolved dependency graph and task commands match the reviewed integration, with any unsupported combinations left explicit.

Verify the consumers use the selected outputs

Generate the dependency graph for a representative target with bitbake -g product-image. The BitBake graph reference documents the recipe list and task graph. Find the relevant consumer-to-provider relationship and check for unexpected implementations.

For the toolchain, inspect a representative application's configure and compile logs. Record the compiler command, target options, sysroot selection, and version information from the task environment. An interactive shell command can answer a different question because the recipe's task environment may select different tools.

For the kernel, connect the selected recipe to the deployed kernel artifact and its configuration. Include any module packages that the product expects to load. A successful build of a kernel recipe is not enough if image assembly later selects a stale or different deployed artifact.

Keep these checks tied to exact file identities where possible. Save hashes and configuration records rather than relying only on familiar filenames such as a generic kernel-image link. The intended provider should be traceable from the dependency choice through the files actually delivered.

Diagnose competing choices without suppressing the evidence

When the wrong provider is selected, inspect the effective assignment and its origin. Check machine and distribution configuration, included toolchain policy, and any local overrides. Change the narrowest appropriate product policy after identifying the conflicting assignment.

When the intended provider is unavailable, review its compatibility conditions and parse diagnostics. Do not replace a virtual dependency with an arbitrary concrete recipe just to eliminate an error; doing so may bypass the intended abstraction while leaving the consumer's real requirements unmet.

The reference notes that nonselected providers of a virtual/* item are prevented from building under that selection mechanism. Treat an attempt to build an excluded alternative as a configuration question, not evidence that the selected recipe is missing. Use a separate controlled configuration when comparing alternatives.

Accept the provider change at the interface boundary

A review should retain the dependency alias, chosen recipe, selected revisions, toolchain mode where relevant, and evidence from consuming tasks. Add product tests for the outputs that matter, such as the expected kernel boot path or a representative application built with the integrated compiler.

Provider selection and functional compatibility are separate conclusions. Make both explicit before adopting the change. This keeps a future layer update from silently turning a metadata preference into an unsupported assumption about the product's kernel or build tools.