BitBake Include Files: Separate Metadata Lookup from Local Source Lookup

A recipe cannot require a shared .inc file, even though its append successfully finds a neighboring configuration payload. Extending FILESEXTRAPATHS again will not fix that parser failure. Metadata inclusion and source-file acquisition use different lookup mechanisms and happen at different stages.

The first useful question is whether the missing file contains BitBake statements or is an input that a task consumes. Its filename extension is a clue, but the directive that references it determines the mechanism.

Read the directive that failed

The include and require documentation describes insertion of another metadata file at the directive's position. A missing include can be tolerated; a missing require causes a parsing error. Use require for definitions that must exist for the recipe to be valid.

By contrast, the FILESPATH reference describes lookup of local files named in SRC_URI. Adding an .inc file as a source payload does not execute its assignments. Including a runtime configuration file does not install it into the target filesystem.

Suppose a recipe needs both sensor-common.inc, containing package metadata, and sensor.conf, containing application settings. The first belongs in a metadata inclusion relationship. The second belongs in the recipe's input and installation flow. Giving both files the same convenient directory does not unify those relationships.

Follow the relative-include search order

The examined configuration parser searches the including file's directory before BBPATH for a relative include name. It selects the first matching file. A nested include therefore starts from the directory of its immediate parent metadata file, not necessarily the recipe directory that began the chain.

For a line such as require sensor-common.inc, inspect the parent file's actual directory and then the effective BBPATH entries. If two layers provide a matching path, locate the selected copy before editing either. A first-match lookup does not combine all files with the same basename.

Use a more specific relative path when the shared file has a deliberate namespace. Broadly adding directories to BBPATH can expose other same-named metadata files and change more than the intended inclusion. A temporary absolute path may help isolate a search failure, but a developer-specific absolute path is a poor committed fix.

Check when the filename expression is expanded

The include AST implementation expands the requested filename when it evaluates the include statement, then invokes the parser on the result.

For an illustrative require ${POLICY_FRAGMENT}.inc, establish POLICY_FRAGMENT before that statement. A later assignment does not retroactively replace the metadata already included. If the final value looks correct in an environment dump, inspect its assignment history and the position of the directive rather than concluding that the earlier inclusion must have used that value.

This matters when a version recipe and an append both manipulate the selector. Prefer a plainly ordered shared definition or a supported conditional metadata design over relying on a value that becomes available only after the inclusion has already happened.

Distinguish absent optional metadata from broken metadata

Optional inclusion suppresses a missing-file condition; it does not make arbitrary contents safe to parse. The examined parser still reports other file-access errors, and a syntax error inside a found file remains a real metadata problem.

For diagnosis, use bitbake -e sensor-tools with the real recipe name and examine the origin comments of a distinctive variable assigned by the shared file. Parser debug output can also identify the expanded include request. If parsing stops before an environment dump is available, work from the reported parent filename and line first.

Resolve the failure at that boundary: wrong expanded name, wrong search location, unintended first match or invalid included content. Once metadata parsing succeeds, investigate source lookup and installation separately. This keeps an .inc failure from accumulating unrelated source-search settings that never participated in its resolution.