[bitbake-devel] doc: bitbake-user-manual: document inherit_defer

This was added in 2.7.2. Add it as a subsection of the inherit
directive.

Fixes [YOCTO #15640].

Reported-by: Yoann Congal <yoann.congal@smile.fr>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)


---
base-commit: 40ca2b66df610ac74918edf54369781f52b03728
change-id: 20241118-inherit-defer-48d3c8e0c087

Best regards,

Hi Antonin,

On 11/18/24 4:36 PM, Antonin Godard via lists.openembedded.org wrote:
> This was added in 2.7.2. Add it as a subsection of the inherit
> directive.
> 
> Fixes [YOCTO #15640].
> 
> Reported-by: Yoann Congal <yoann.congal@smile.fr>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 13 +++++++++++++
>   1 file changed, 13 insertions(+)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index 58975f4c88ce549a2fd27136c0cb37b636bafcdb..ab16ddde3cf837092d4c43e467b4becceae23b27 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -840,6 +840,19 @@ 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.
>   
> +``inherit_defer`` Directive
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The ``inherit_defer`` directive works like the ``inherit`` directive, except

add a ref here to the inherit directive section?

> +that it is only evaluated at the end of parsing. Its usage is recommended when a
> +conditional expression is used. For example::
> +
> +   inherit_defer ${@bb.utils.contains('PACKAGECONFIG', 'python', 'python3targetconfig', '', d)}
> +
> +This allows conditional expressions to be evaluated "late", meaning changes
> +to the variable after the line is parsed will take effect. With the ``inherit``
> +directive this is not the case.
> +

OK so I don't know if this wouldn't also typically apply to "inherit 
${VARIABLE}" if VARIABLE is set after the inherit?

Ahah, I believe this is actually specified in the inherit directive section!

"""
An advantage with the inherit directive as compared to both the include 
and require directives is that you can inherit class files 
conditionally. You can accomplish this by using a variable expression 
after the inherit statement. Here is an example:

inherit ${VARNAME}

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

Also, I believe we very likely want to remove the last few paragraphs of 
the inherit directive section?

i.e. from
"""
One way to achieve a conditional inherit in this case is to use overrides:
"""
to the end of the section.

I guess we could replace it with "if you want to conditionally inherit, 
please use :ref:`inherit_defer`".

or something along those lines.

What do you think?

Cheers,
Quentin

Hi Quentin,

On Mon Nov 18, 2024 at 4:44 PM CET, Quentin Schulz wrote:
[...]
>> +``inherit_defer`` Directive
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +The ``inherit_defer`` directive works like the ``inherit`` directive, except
>
> add a ref here to the inherit directive section?

Yes, thanks.

>> +that it is only evaluated at the end of parsing. Its usage is recommended when a
>> +conditional expression is used. For example::
>> +
>> +   inherit_defer ${@bb.utils.contains('PACKAGECONFIG', 'python', 'python3targetconfig', '', d)}
>> +
>> +This allows conditional expressions to be evaluated "late", meaning changes
>> +to the variable after the line is parsed will take effect. With the ``inherit``
>> +directive this is not the case.
>> +
>
> OK so I don't know if this wouldn't also typically apply to "inherit 
> ${VARIABLE}" if VARIABLE is set after the inherit?
>
> Ahah, I believe this is actually specified in the inherit directive section!
>
> """
> An advantage with the inherit directive as compared to both the include 
> and require directives is that you can inherit class files 
> conditionally. You can accomplish this by using a variable expression 
> after the inherit statement. Here is an example:
>
> inherit ${VARNAME}
>
> If VARNAME is going to be set, it needs to be set before the inherit 
> statement is parsed.
> """
>
> Also, I believe we very likely want to remove the last few paragraphs of 
> the inherit directive section?
>
> i.e. from
> """
> One way to achieve a conditional inherit in this case is to use overrides:
> """
> to the end of the section.
>
> I guess we could replace it with "if you want to conditionally inherit, 
> please use :ref:`inherit_defer`".
>
> or something along those lines.
>
> What do you think?

And so the documentation would advise to always use `inherit_defer` for
conditional inherits. As far as I understand the purpose of inherit_defer, this
is fine to me (and error-safe), so I agree with you on removing the conditional
case from the inherit directive section and redirecting towards inherit_defer.

This makes me wonder why inherit_defer isn't merged into inherit then (i.e.
inherit would behave like inherit_defer by default). But I guess there are other
stakes that go beyond my knowledge on this. :)

Cheers,
Antonin