[PATCH 1/1] doc: bitbake-user-manual-metadata: fix inherit_defer documentation

Dawid Bijak
2026-04-24T06:23:58Z

The documentation for inherit_defer contained the claim

"If VARNAME is going to be set, it needs to be set before the
inherit_defer statement is parsed"

which is incorrect and contradicts the purpose of inherit_defer.
The wrong claim is replaced with an example which demonstrates
the contrast between a plain defer statement and the inherit_defer
statement by using an override assignment placed after inherit_defer

Additionally the inline python expression examples have been
moved from the inherit_defer section up to the inherit section, since
they apply to both directives

Also add an anti-example showing that the previously documented
pattern of setting the inherited class name from an anonymous
Python function does not work with inherit_defer.

Signed-off-by: Dawid Bijak <bijak.dawid@gmail.com>
---
.../bitbake-user-manual-metadata.rst | 61 ++++++++++---------
1 file changed, 32 insertions(+), 29 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 40cae6b05..38efe6b11 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -803,7 +803,17 @@ An advantage with the inherit directive as compared to both the
:ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
directives is that you can inherit class files conditionally. You can
accomplish this by using a variable expression after the ``inherit``
-statement.
+statement, as in::
+
+ inherit ${@'classname' if condition else ''}
+
+Or::
+
+ inherit ${@bb.utils.contains('VARIABLE', 'something', 'classname', '', d)}
+
+In both cases, if the expression evaluates to an
+empty string, the statement does not trigger a syntax error because it
+becomes a no-op.

For inheriting classes conditionally, using the :ref:`inherit_defer
<ref-bitbake-user-manual-metadata-inherit-defer>` directive is advised as
@@ -827,39 +837,32 @@ the variable after the line is parsed will take effect. With the :ref:`inherit

Here is an example::

- inherit_defer ${VARNAME}
-
-If ``VARNAME`` is
-going to be set, it needs to be set before the ``inherit_defer`` statement is
-parsed. One way to achieve a conditional inherit in this case is to use
-overrides::
-
VARIABLE = ""
- VARIABLE:someoverride = "myclass"
-
-Another method is by using :ref:`anonymous Python
-<bitbake-user-manual/bitbake-user-manual-metadata:Anonymous Python Functions>`.
-Here is an example::
+ inherit_defer ${VARIABLE}
+ VARIABLE:someoverride = "someclass"
+
+:ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>`
+defers the evaluation of ``${VARIABLE}`` until the end of
+parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARIABLE}``
+expands to ``someclass``, which is then inherited. Contrast this with a plain
+:ref:`inherit <ref-bitbake-user-manual-metadata-inherit>`, which would evaluate
+``${VARIABLE}`` immediately, before the ``VARIABLE:someoverride`` assignment
+is parsed. ``${VARIABLE}`` would expand to an empty string and the statement
+would become a no-op.
+
+Note that assigning the variable from an
+:ref:`anonymous Python function <bitbake-user-manual/bitbake-user-manual-metadata:Anonymous Python Functions>`
+does *not* work, because deferred inherits are resolved before anonymous
+Python functions run::

python () {
- if condition == value:
- d.setVar('VARIABLE', 'myclass')
- else:
- d.setVar('VARIABLE', '')
+ if d.getVar('SOMETHING') == 'value':
+ d.setVar('VARIABLE', 'someotherclass')
}

-Alternatively, you could use an inline Python expression in the
-following form::
-
- inherit_defer ${@'classname' if condition else ''}
-
-Or::
-
- inherit_defer ${@bb.utils.contains('VARIABLE', 'something', 'classname', '', d)}
-
-In all cases, if the expression evaluates to an
-empty string, the statement does not trigger a syntax error because it
-becomes a no-op.
+The conditional assignment of ``someotherclass`` has no effect on the
+``inherit_defer`` statement, which has already been resolved by the time
+the anonymous Python function runs.

See also :term:`BB_DEFER_BBCLASSES` for automatically promoting classes
``inherit`` calls to ``inherit_defer``.
--
2.48.1