doc/bitbake-user-manual-ref-variables: improve INHERIT

Current wording makes it difficult to understand what
exactly is done with INHERIT-ed anonymous functions and
when.

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
 doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

On Wed Oct 1, 2025 at 11:37 AM CEST, Adam Blank via lists.openembedded.org wrote:
> Current wording makes it difficult to understand what
> exactly is done with INHERIT-ed anonymous functions and
> when.
>
> Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
> ---
>  doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> index 810f88689..9d0cbd71d 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> @@ -1200,8 +1200,8 @@ overview of their function and contents.
>  
>     :term:`INHERIT`
>        Causes the named class or classes to be inherited globally. Anonymous
> -      functions in the class or classes are not executed for the base
> -      configuration and in each individual recipe. The OpenEmbedded build
> +      functions in the class or classes are executed either for the base
> +      configuration, or in each individual parsed recipe. The OpenEmbedded build

I ran a quick test, and I do see the anonymous function called for individual
recipes, but I have trouble understanding what the "base configuration" is. Does
this mean the anonymous function is also called in the top-level context /
top-level configuration, with no recipes associated to it?

The original sentence could be interpreted differently IMO, and I would have
phrased it this way:

"""
Anonymous functions in the class or classes are not executed for the base
configuration but are executed in each individual recipe.
"""

Which is what I observe when testing… I don't see any call to it without an
associated recipe.

What do you think?

Thanks,
Antonin

Anonymous Python functions are called either when a recipe is finalised, or
when
Bitbake is called to show just the base configuration, i.e. 'bitbake -e'.
In a normal build those two cases don't coincide, so your proposal is fully
correct,
but perhaps it would be good to hint on why their execution can be observed
in
the 'show environment' case?

Thanks,
Adam

On Fri, 3 Oct 2025 at 13:55, Antonin Godard <antonin.godard@bootlin.com>
wrote:

> On Wed Oct 1, 2025 at 11:37 AM CEST, Adam Blank via lists.openembedded.org
> wrote:
> > Current wording makes it difficult to understand what
> > exactly is done with INHERIT-ed anonymous functions and
> > when.
> >
> > Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
> > ---
> >  doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git
> a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > index 810f88689..9d0cbd71d 100644
> > --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > @@ -1200,8 +1200,8 @@ overview of their function and contents.
> >
> >     :term:`INHERIT`
> >        Causes the named class or classes to be inherited globally.
> Anonymous
> > -      functions in the class or classes are not executed for the base
> > -      configuration and in each individual recipe. The OpenEmbedded
> build
> > +      functions in the class or classes are executed either for the base
> > +      configuration, or in each individual parsed recipe. The
> OpenEmbedded build
>
> I ran a quick test, and I do see the anonymous function called for
> individual
> recipes, but I have trouble understanding what the "base configuration"
> is. Does
> this mean the anonymous function is also called in the top-level context /
> top-level configuration, with no recipes associated to it?
>
> The original sentence could be interpreted differently IMO, and I would
> have
> phrased it this way:
>
> """
> Anonymous functions in the class or classes are not executed for the base
> configuration but are executed in each individual recipe.
> """
>
> Which is what I observe when testing… I don't see any call to it without an
> associated recipe.
>
> What do you think?
>
> Thanks,
> Antonin
>
> --
> Antonin Godard, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
>
>

On Fri Oct 3, 2025 at 2:06 PM CEST, Adam Blank wrote:
> Anonymous Python functions are called either when a recipe is finalised, or
> when
> Bitbake is called to show just the base configuration, i.e. 'bitbake -e'.
> In a normal build those two cases don't coincide, so your proposal is fully
> correct,
> but perhaps it would be good to hint on why their execution can be observed
> in
> the 'show environment' case?

Ha you are correct, I did not think of trying bitbake -e! I guess I was just
confused by what base configuration meant here. This could probably be improved
to provide a reference to the "Parsing the Base Configuration Metadata" section
with:

:ref:`base configuration <bitbake-user-manual/bitbake-user-manual-execution:Parsing the Base Configuration Metadata>`

But out-of-context for your patch.

I would insist on the fact that the two cannot coincide then, but your patch is
already an improvement.

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks!
Antonin