Re: [docs] [PATCH] Mention existence of three supported "classes" directories

["Antonin Godard" <antonin.godard@bootlin.com>]

On Tue Jul 8, 2025 at 1:42 PM CEST, Robert P. J. Day wrote:
> On Tue, 8 Jul 2025, Antonin Godard via lists.yoctoproject.org wrote:
>
>> On Tue Jul 8, 2025 at 1:29 PM CEST, Robert P. J. Day wrote:
>> >
>> > Early in Section 1, mention that BitBake supports three related
>> > classes directories.
>> >
>> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>> >
>> > ---
>> >
>> >   I'm not thrilled with this explanation in terms of where it is, but
>> > it's better than not explaining this at all.
>> >
>> > diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
>> > index 539bb62d8..feab1df9d 100644
>> > --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
>> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
>> > @@ -206,6 +206,18 @@ installing (empty by default) and packaging (empty by default). These
>> >  tasks are often overridden or extended by other classes added during the
>> >  project development process.
>> >
>> > +.. note::
>> > +
>> > +   While BitBake comes with just the one ``base.bbclass`` file in the
>> > +   ``classes`` directory, it supports class files also being installed
>> > +   in related directories ``classes-global`` and ``classes-recipe`` and
>> > +   will automatically search all three directories for a selectd class
>>
>> s/selectd/selected/
>
>   already submitted that fix.
>
>> > +   file.
>> > +
>> > +   This means that, in this documentation, when you see a reference to
>> > +   class files being in the ``classes`` directory, you can interpret that
>> > +   as meaning in any one of the above three directories.
>>
>> I don't think this is enough explanation on these directories, and as-is it
>> would create confusion I think.
>>
>> There are some details about these directories here:
>> https://bootlin.com/doc/training/yocto/yocto-slides.pdf#19
>>
>> Maybe that can help you add the explanation?
>>
>> I would also explain the difference between these directories (classes,
>> classes-recipe and classes-global) in a paragraph of its own, not in a note.
>
>   Except that, once again, we would be going outside the bounds of
> BitBake. I totally agree that there should be a comprehensive
> explanation of these directories, but where does that belong?

I think that saying:

- classes-recipe is meant for recipes, and are inherited through the
  `inherit` directive
- classes-global is meant to be inherited through the `INHERIT` variable
- classes can be used in both context

should not be out-of-boundary.

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com