Yocto Layers: Keep Board Support Separate from Product Policy

A board layer is added to support a second product, and an unrelated image suddenly gains a service or changes a library option. The immediate temptation is to reorder layers until the build looks right. A more durable investigation asks which metadata is allowed to affect which build. Layer ownership should make that answer predictable before a new board is added.

This article uses Yocto Project 5.0.12 Scarthgap documentation. It develops an example review method for separating hardware support from product policy. It does not claim that a particular repository was tested or that a suggested layout is mandatory for every organization.

Define the boundary in terms of change

A useful ownership test is: what should cause this setting to change? A device-tree adjustment caused by a new board revision has a different owner from a decision to include remote diagnostics in every product. An application version selected for one product family is different again from the recipe that describes how to build that application.

Write those distinctions into a short layer contract. A board-support layer should explain its machines and hardware-specific customizations. A distribution layer should explain shared policy. A product image can select the set of capabilities delivered together. A reusable application layer can supply recipes without deciding that every consuming image must install them.

The BSP guide describes the BSP as a layer containing the relevant support metadata and dependencies. The distribution guide explains how a named distribution keeps policy in versioned configuration. These are useful implementation homes; the ownership contract still needs to describe the project's intended boundaries.

Inspect the effect of adding a layer

Choose a reference machine that the new layer is not supposed to affect. Record its parsed configuration and the recipes selected for a representative image before enabling the layer. Then enable the layer without selecting its machine or distribution and compare the relevant values. This is a proposed regression check, not an assumption that every build must remain byte-identical.

Look especially for assignments in conf/layer.conf, unqualified recipe appends, and shared files placed where unrelated machines can find them. Ask whether each change is intended to apply globally or requires a machine, distribution, recipe, or feature condition. A comment saying board-specific does not establish that condition.

The layer best-practices section demonstrates how unqualified metadata can affect another machine and how machine-scoped changes avoid that leak. It also recommends append files rather than copying entire recipes merely to make a small adjustment. Review the smallest effective difference instead of maintaining an unexplained duplicate recipe.

Separate availability from selection

A layer can make a recipe available without making its package part of every image. Preserve that separation in design reviews. For an illustrative diagnostics service, ask three questions: who provides the recipe, who chooses the service for an image, and who sets the production access policy? Combining all three in a board append makes later reuse harder to reason about.

Create a responsibility record for contested settings. Give the diagnostics recipe to its component maintainer, the image package selection to the product image owner, and access policy to the distribution or product policy owner. The exact repository boundaries may differ, but each decision should have one authoritative location and a reviewer who understands its impact.

Avoid solving unclear ownership solely by increasing BBFILE_PRIORITY. A higher priority can affect recipe selection without explaining whether the selected behavior belongs in that layer. When two layers intentionally customize the same recipe, document their interaction and inspect the final parsed result. Priority is an implementation mechanism, not an architectural explanation.

Test a small configuration matrix

A single working machine cannot establish that a reusable layer is properly scoped. Select a modest matrix that tests the promised boundaries rather than every theoretically possible combination. For example, use the supported board with its product distribution, the same board with a reference image, and a second machine that should remain unaffected by the board layer.

For each case, compare the settings tied to the change under review. A kernel patch requires checking the selected kernel and patch application; a service addition requires checking the image package set and enablement; a configuration-file replacement requires inspecting the actual file selected. Do not collapse these into a generic build passed result.

1. Record the layer revisions and selected machine, distribution, and image for every matrix entry.
2. Parse and inspect the variables or recipe appends that implement the changed behavior.
3. Build the affected artifacts and retain evidence of their contents.
4. Run the relevant target check where hardware behavior is involved.
5. Confirm that an unrelated matrix entry retains its intended behavior after the layer is enabled.

Failures should identify the leaking decision, not merely the first package that rebuilt. A task-signature change is a useful investigation signal, but it does not automatically identify an incorrect result. Determine whether the changed input was intended for that configuration.

Leave a contract that survives the next board

Document each layer's purpose, dependencies, supported release series, configuration entry points, and expected non-effects. Include an example of an intentionally scoped customization and explain where future product policy should go. This helps a later contributor avoid copying the nearest existing workaround into the wrong ownership boundary.

The review is complete when a new contributor can answer what the layer supplies, what activates its behavior, and which other configurations were checked. Layer separation cannot replace runtime validation or guarantee compatibility with arbitrary third-party layers. It can make the impact of a board addition narrow enough to understand and test, which is the practical requirement for maintaining more than one product.