[PATCH v2 0/4] doc: bitbake-user-manual-metadata: clarify inherit_defer documentation

[PATCH v2 0/4] doc: bitbake-user-manual-metadata: clarify inherit_defer documentation

[Dawid Bijak]

This is v2 of [1].

The previous single patch has been split into 4 smaller, independently reviewable patches
as suggested by Quentin in [1].

The series addresses a few inaccuracies I came across while reading the inherit_defer documentation.

1)
    Drop the claim that "If VARNAME is going to be set, it needs to be set before the inherit_defer statement is parsed"
    which is wrong and defeats the purpose of inherit_defer.
    The whole point of deferred evaluation is that assignments made after the directive are taken into account.

2)
    Drop the anonymous Python example of assigning the class name from an anonymous Python function, which does not work:

    python () {
        if d.getVar('SOMETHING') == 'value':
            d.setVar('VARIABLE', 'someclass')
        else:
            d.setVar('VARIABLE', '')
    }
    inherit_defer ${VARIABLE}

    inherit_defer is resolved before anonymous Python functions run, so ${VARIABLE} always expands to empty
    and the inherit is a no-op.

3)
    Add a short explanation of how inherit_defer interacts with conditional overrides, and rename VARIABLE to
    VARNAME for consistency with the preceding code block.

4)
    Move the inline Python examples up into the inherit section. They work with both plain inherit
    and inherit_defer, so presenting them only under inherit_defer is misleading.

Changes since v1:
  - Split single patch into four
  - Shorten the override example explanation
  - Drop the "footgun" example from the previous patch

[1] https://lore.kernel.org/all/20260424062327.820993-1-bijak.dawid@gmail.com/

Greets,
Dawid

Dawid Bijak (4):
  doc: bitbake-user-manual-metadata: remove incorrect claim
  doc: bitbake-user-manual-metadata: remove invalid anonymous Python
    example
  doc: bitbake-user-manual-metadata: explain inherit_defer example
  doc: bitbake-user-manual-metadata: move inline python examples to
    inherit section

 .../bitbake-user-manual-metadata.rst          | 47 +++++++------------
 1 file changed, 18 insertions(+), 29 deletions(-)

-- 
2.48.1

[PATCH v2 1/4] doc: bitbake-user-manual-metadata: remove incorrect claim

[Dawid Bijak]

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.

Drop the incorrect statement.

Signed-off-by: Dawid Bijak <bijak.dawid@gmail.com>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 4 +---
 1 file changed, 1 insertion(+), 3 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..ee6919dc4 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -829,9 +829,7 @@ 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
+One way to achieve a conditional inherit in this case is to use
 overrides::
 
    VARIABLE = ""
-- 
2.48.1

Re: [PATCH v2 1/4] doc: bitbake-user-manual-metadata: remove incorrect claim

[Quentin Schulz]

Hi Dawid,

On 5/1/26 11:14 AM, Dawid Bijak wrote:
> 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.
> 
> Drop the incorrect statement.
> 

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH v2 1/4] doc: bitbake-user-manual-metadata: remove incorrect claim

[Dawid Bijak]

Hi Quentin,

On Thu, May 07, 2026 at 03:48:19PM +0200, Quentin Schulz wrote:
> Hi Dawid,
> 
> On 5/1/26 11:14 AM, Dawid Bijak wrote:
> > 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.
> > 
> > Drop the incorrect statement.
> > 
> 
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> 
> Thanks!
> Quentin


Thank you for the thorough review of the series. I'll  send v3
incorporating your remarks. It will however take around a week since I'm
tied up at the moment.

Greets,
Dawid

[PATCH v2 2/4] doc: bitbake-user-manual-metadata: remove invalid anonymous Python example

[Dawid Bijak]

The documentation for inherit_defer suggested that conditional inheritance
can be achieved by setting a variable inside an anonymous python function
and then referencing it from inherit_defer.
This does not work: inherit_defer is resolved before the anonymous Python
functions run.

Remove the incorrect example.

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

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index ee6919dc4..b886e0578 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -835,17 +835,6 @@ 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::
-
-   python () {
-       if condition == value:
-           d.setVar('VARIABLE', 'myclass')
-       else:
-           d.setVar('VARIABLE', '')
-   }
-
 Alternatively, you could use an inline Python expression in the
 following form::
 
-- 
2.48.1

Re: [PATCH v2 2/4] doc: bitbake-user-manual-metadata: remove invalid anonymous Python example

[Quentin Schulz]

Hi Dawid,

On 5/1/26 11:14 AM, Dawid Bijak wrote:
> The documentation for inherit_defer suggested that conditional inheritance
> can be achieved by setting a variable inside an anonymous python function
> and then referencing it from inherit_defer.
> This does not work: inherit_defer is resolved before the anonymous Python
> functions run.
> 
> Remove the incorrect example.
> 

That's fine, but this is so far an undocumented limitation and it would 
be really nice to say it's not supported!

Something like:

.. warning::

    Setting or modifying variables within an :ref:`anonymous Python 
function <bitbake-user-manual/bitbake-user-manual-metadata:Anonymous 
Python Functions>` will have no impact on the value of that variable in 
an :ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>` 
directive as the function is run after the directive is resolved.

(untested and probably missing some formatting, e.g. line-wrapping :) ).

Cheers,
Quentin

[PATCH v2 3/4] doc: bitbake-user-manual-metadata: explain inherit_defer example

[Dawid Bijak]

Add a short paragraph describing how the inherit_defer makes use of override
syntax to achieve conditional inheritance, and rename VARIABLE to
VARNAME so the example uses the same identifier as the preceding
code block.

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

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index b886e0578..0c7c3ff99 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -832,8 +832,13 @@ Here is an example::
 One way to achieve a conditional inherit in this case is to use
 overrides::
 
-   VARIABLE = ""
-   VARIABLE:someoverride = "myclass"
+   VARNAME = ""
+   VARNAME:someoverride = "myclass"
+
+:ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>`
+defers the evaluation of ``${VARNAME}`` until the end of
+parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARNAME}``
+expands to ``myclass``, which is then inherited.
 
 Alternatively, you could use an inline Python expression in the
 following form::
-- 
2.48.1

Re: [PATCH v2 3/4] doc: bitbake-user-manual-metadata: explain inherit_defer example

[Quentin Schulz]

Hi Dawid,

On 5/1/26 11:14 AM, Dawid Bijak wrote:
> Add a short paragraph describing how the inherit_defer makes use of override
> syntax to achieve conditional inheritance, and rename VARIABLE to
> VARNAME so the example uses the same identifier as the preceding
> code block.
> 

Can you please instead rename VARNAME in inherit_defer to VARIABLE to 
match the rest of the file?

Otherwise, looks good.

Cheers,
Quentin

[PATCH v2 4/4] doc: bitbake-user-manual-metadata: move inline python examples to inherit section

[Dawid Bijak]

The two inline Python examples,

  inherit_defer ${@'classname' if condition else ''}
  inherit_defer ${@bb.utils.contains('VARIABLE', 'something', 'classname', '', d)}

are presented as inherit_defer-specific techniques, but they work
with plain inherit too. Their placement under
inherit_defer suggests deferred evaluation is required, which is
not the case: the ${@...} expression is evaluated when the
inherit line is parsed in both forms.

Move the inline Python expression examples from the inherit_defer section
up to the inherit section, since they apply to both directives.

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

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 0c7c3ff99..4b1aeedc1 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
@@ -840,19 +850,6 @@ defers the evaluation of ``${VARNAME}`` until the end of
 parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARNAME}``
 expands to ``myclass``, which is then inherited.
 
-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.
-
 See also :term:`BB_DEFER_BBCLASSES` for automatically promoting classes
 ``inherit`` calls to ``inherit_defer``.
 
-- 
2.48.1

Re: [PATCH v2 4/4] doc: bitbake-user-manual-metadata: move inline python examples to inherit section

[Quentin Schulz]

Hi Dawid,

On 5/1/26 11:14 AM, Dawid Bijak wrote:
> The two inline Python examples,
> 
>    inherit_defer ${@'classname' if condition else ''}
>    inherit_defer ${@bb.utils.contains('VARIABLE', 'something', 'classname', '', d)}
> 
> are presented as inherit_defer-specific techniques, but they work
> with plain inherit too. Their placement under
> inherit_defer suggests deferred evaluation is required, which is
> not the case: the ${@...} expression is evaluated when the
> inherit line is parsed in both forms.
> 
> Move the inline Python expression examples from the inherit_defer section
> up to the inherit section, since they apply to both directives.
> 

As said in V1 and in this form: NACK.

What's the raison d'être of inherit_defer if inherit "works just as well"?

To quote Richard in v1:

"""
It works, as long as you are sure that COND won't be changed after the
inherit. When mutliple files altering the variables are involved, that
is often unclear. I think the doc's intent is therefore to recommend
anything with variable accesses is therefore deferred, unless the user
is sure they know what they're doing.
"""

The commit introducing inherit_defer in BitBake is also pretty explicit 
why it was added, see 5c2e840eafeb ("ast/BBHandler: Add inherit_defer
support").

So it may appear to work for you in your specific usecase, but it 
doesn't always. We are very careful to not add unnecessary complexity, 
be it operators or directives so I trust Richard to not have merged 
something that does nothing that isn't already supported by another 
directive or operator. Yes, inherit_defer is useful for the native class 
which we always want to be last, but it's not why this directive was 
added in the first place, it's only piggy-backing there.

So, as said in v1, we are not using footguns as examples. We can however 
say that something may appear to work but is a footgun, as suggested in 
v1 where I said "You can provide an example if you really want to in the 
inherit section, and add a big fat warning after it that it'll break in 
some scenario so you really shouldn't do that and instead use 
inherit_defer.".

Cheers,
Quentin