Re: [docs] more docs curiosity: "inherit_defer" in the BB manual

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Robert,

On 7/9/25 4:20 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> On Wed, 9 Jul 2025, Richard Purdie wrote:
> 
>> On Wed, 2025-07-09 at 09:31 -0400, Robert P. J. Day via
>> lists.yoctoproject.org wrote:
>>>
>>> here:
>>>
>>> https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-metadata.html#inherit-defer-directive
>>>
>>> that section strongly suggests that the sole reason to use
>>> "inherit_defer" is that you want to inherit some class, but you're
>>> not
>>> sure which class *yet*, so you use a variable that will, at some
>>> point, be set before parsing is complete. or possibly it will involve
>>> a programmatic condition.
>>>
>>>    so what is the purpose of using "inherit_defer" on a fixed bbclass
>>> name such as this?
>>>
>>> https://git.openembedded.org/openembedded-core/tree/meta/recipes-devtools/qemu/qemu-native.inc#n3
>>>
>>> what is the rationale of inherit_defer'ing a fixed class name? or is
>>> there more to this that i'm missing?
>>
>> native has to be last. That means it has to be deferred.
>>
>> I think bitbake now happens to handle this magically after more recent
>> changes, just to complicate the story.
> 
>    i had assumed the first bit, i am unfamiliar with the second bit, so
> here's my thinking.
> 
>    the section on plain "inherit":
> 
> https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-metadata.html#inherit-directive
> 
> already explains (in the Note) that the placement of "inherit"
> directives is important as that might affect what you will and will
> not be allowed to override, so that part seems fine.
> 
>    the last line in that section, though:
> 
> "For inheriting classes conditionally, using the inherit_defer
> directive is advised ..."
> 
> is now clearly(?) misleading since it suggests it is to be used solely
> for conditional inheriting, which is not entirely true.

Not a native speaker but it just states that if you want to inherit 
classes conditionally, you need to use inherit_defer, not that 
inherit_defer is to be used only for inheriting classes conditionally. 
It's just one use case of it.

> 
>    i think a clearer way to explain this is to just drop that last
> sentence from that section and then, in the following "inherit_defer"

Hard no. We absolutely need to state that you should NOT be using the 
inherit directive for conditional inherits.

Which made me reread the section and I believe we should be 
rewording/removing the before-last paragraph which says that an 
advantage of the inherit directive over include/require directive is 
that you can inherit conditionally. Considering you really shouldn't be 
using inherit but inherit_defer for that, we shouldn't hint at it (and 
rather hint at inherit_defer directly).

> section, explain that it is *mostly* used for conditional inheritance
> (involving variables), but *might* be seen in cases like that "inherit
> native" example (unless that last part is such a corner case that it
> can remain unexplained, and not over-complicate the explanaton).
> 

All I remember is that inherit_defer has interesting side effects with 
how variables are resolved but I haven't played enough with it to know 
or remember which ones. We can start with fixing the inherit directive 
section to stop mentioning to use inherit for conditional inheritance as 
that is factually wrong. For inherit_defer itself, a bit of tinkering 
and experimenting (or studying the parsing code) would help figuring out 
what to put in the docs, but nothing I can suggest myself having 
virtually no experience with it.

Cheers,
Quentin