Yocto License Filtering: Separate Image Restrictions from Global Recipe Exclusion

A product image needs a license-name restriction, but placing INCOMPATIBLE_LICENSE in global configuration makes an unrelated build dependency unavailable. These are different policy scopes. A restriction evaluated for every affected recipe can change the build graph; one applied to a particular image evaluates the packages entering that image.

This is a build-system mechanism. Its result depends on the declared license metadata and does not establish a product's legal obligations or distribution permission.

Choose the restriction boundary deliberately

The INCOMPATIBLE_LICENSE reference distinguishes a global setting from a setting local to an image recipe. It recommends the image-local approach for image restrictions because global exclusion can make build dependencies unsatisfiable.

For an illustrative image-only policy, place INCOMPATIBLE_LICENSE = "GPL-3.0-only" in the intended image recipe. Inspect both that image's environment and a separately parsed component recipe. The restriction should not unexpectedly become a shared global setting through an included configuration fragment.

An image-local restriction is not a source-download ban. Components can remain buildable and serve build-time purposes even when their packages are unacceptable in the selected root filesystem. Conversely, global configuration expresses a broader build policy and should not be chosen merely because it is the easiest file to edit.

Interpret the actual license expression

License metadata can describe alternatives. In the hypothetical expression MIT | GPL-3.0-only, an allowed alternative can satisfy the incompatibility check. The expression MIT & GPL-3.0-only has different semantics and cannot be treated as the same choice.

The examined license helper evaluates alternatives and checks package-specific LICENSE metadata when available, falling back to the recipe's declaration. Inspect the declaration of the package named in the error rather than relying only on the recipe summary.

Do not edit an ampersand into a vertical bar to clear a failure. That changes the asserted licensing relationship. Correct metadata only when the underlying source and its applicable terms actually support the correction.

The supported wildcard forms are also limited. The reference lists specific GPL, LGPL and AGPL version-three forms; this setting is not a general-purpose glob filter for arbitrary license families. Prefer the exact current identifiers required by the policy.

Distinguish a parse exclusion from an image rejection

In the examined base class, package-license checks can mark incompatible outputs and can skip a recipe when no acceptable package outputs remain. This can explain a missing-provider report before image assembly. The helper also contains exemptions for particular build-tool recipe forms, so global does not mean every host-side tool is categorically removed.

At the image boundary, the examined license-image class checks installed package metadata and reports incompatible licenses. An image rejection should lead to the package and dependency that introduced it, not immediately to a provider-priority change.

Use the earliest diagnostic to choose the investigation. For a skipped recipe, inspect the component's effective policy and package declarations. For an image rejection, inspect the image's policy and the rejected installed package. These checks occur in different datastores and can legitimately see different settings.

Keep exceptions as exact package-license decisions

INCOMPATIBLE_LICENSE_EXCEPTIONS uses package-and-license pairs. An illustrative entry is sensor-helper:GPL-3.0-only, not just the recipe name or a blanket exemption for every output it produces.

The helper removes matching pairs from the disallowed set for that package. The image code still reports an exception-based inclusion through its license-incompatible QA handling. Do not assume adding an exception guarantees a silent successful build under every QA configuration.

Before adding one, confirm the package identity used by the diagnostic, the precise license identifier and the scope of the approved policy exception. Test another output from the same recipe that should remain restricted.

The final engineering result should explain which scope rejected which declared license, and why the selected alternative or exception is appropriate. A successful rootfs task validates that configured check against its inputs; it does not replace review of the metadata's accuracy.