[PATCH] Mention existence of three supported "classes" directories

[PATCH] Mention existence of three supported "classes" directories

[Robert P. J. Day]

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
+   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.
+
 Layers
 ------

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

[Antonin Godard]

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/

> +   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.

Thanks,
Antonin

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

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

[Robert P. J. Day]

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?

rday

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

[Antonin Godard]

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