a couple random thoughts about YP docs and examples

a couple random thoughts about YP docs and examples

[Robert P. J. Day]

  reading the bitbake manual (although this could just as well apply
to YP docs in general), my first general nitpick is the number of
awkwardly contrived examples that involve contrived variable names.
consider this section on the ":remove" directive:

https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-metadata.html#removal-override-style-syntax

why use variables FOO and FOO2 and arbitrary numeric strings when
there are so many meaningful examples in the OE code base that would
make actual sense, such as:

  meta/recipes-bsp/grub/grub2.inc:CFLAGS:remove = "-O2"
  meta/recipes-bsp/grub/grub2.inc:TUNE_CCARGS:remove = "-mfpmath=sse"

Examples like that actually suggest to the reader *why* one might want
to remove strings from various variables related to various recipes.

  Also, I don't see any mention in that section about override-related
removal that would be useful to explain, stuff like:

meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv32 = "libunwind"
meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv64 = "libunwind"
meta-poky/conf/distro/poky-tiny.conf:PACKAGECONFIG:remove:pn-opkg-utils = "python"

In short, we should be using actual examples from the OE code base as
examples, and we should try to be complete.

rday

Re: [docs] a couple random thoughts about YP docs and examples

[Antonin Godard]

On Mon Jul 7, 2025 at 9:16 PM CEST, Robert P. J. Day wrote:
>
>   reading the bitbake manual (although this could just as well apply
> to YP docs in general), my first general nitpick is the number of
> awkwardly contrived examples that involve contrived variable names.
> consider this section on the ":remove" directive:
>
> https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-metadata.html#removal-override-style-syntax
>
> why use variables FOO and FOO2 and arbitrary numeric strings when
> there are so many meaningful examples in the OE code base that would
> make actual sense, such as:
>
>   meta/recipes-bsp/grub/grub2.inc:CFLAGS:remove = "-O2"
>   meta/recipes-bsp/grub/grub2.inc:TUNE_CCARGS:remove = "-mfpmath=sse"
>
> Examples like that actually suggest to the reader *why* one might want
> to remove strings from various variables related to various recipes.
>
>   Also, I don't see any mention in that section about override-related
> removal that would be useful to explain, stuff like:
>
> meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv32 = "libunwind"
> meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv64 = "libunwind"
> meta-poky/conf/distro/poky-tiny.conf:PACKAGECONFIG:remove:pn-opkg-utils = "python"
>
> In short, we should be using actual examples from the OE code base as
> examples, and we should try to be complete.

Bitbake is not only used with OE-Core, and so the Bitbake documentation should
not make any references to it. Maybe more meaningful examples could be taken but
we need to keep that in mind.

Antonin

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

Re: [docs] a couple random thoughts about YP docs and examples

[Robert P. J. Day]

On Tue, 8 Jul 2025, Antonin Godard wrote:

> On Mon Jul 7, 2025 at 9:16 PM CEST, Robert P. J. Day wrote:
> >
> >   reading the bitbake manual (although this could just as well apply
> > to YP docs in general), my first general nitpick is the number of
> > awkwardly contrived examples that involve contrived variable names.
> > consider this section on the ":remove" directive:
> >
> > https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-metadata.html#removal-override-style-syntax
> >
> > why use variables FOO and FOO2 and arbitrary numeric strings when
> > there are so many meaningful examples in the OE code base that would
> > make actual sense, such as:
> >
> >   meta/recipes-bsp/grub/grub2.inc:CFLAGS:remove = "-O2"
> >   meta/recipes-bsp/grub/grub2.inc:TUNE_CCARGS:remove = "-mfpmath=sse"
> >
> > Examples like that actually suggest to the reader *why* one might want
> > to remove strings from various variables related to various recipes.
> >
> >   Also, I don't see any mention in that section about override-related
> > removal that would be useful to explain, stuff like:
> >
> > meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv32 = "libunwind"
> > meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv64 = "libunwind"
> > meta-poky/conf/distro/poky-tiny.conf:PACKAGECONFIG:remove:pn-opkg-utils = "python"
> >
> > In short, we should be using actual examples from the OE code base as
> > examples, and we should try to be complete.
>
> Bitbake is not only used with OE-Core, and so the Bitbake
> documentation should not make any references to it. Maybe more
> meaningful examples could be taken but we need to keep that in mind.

  i understand the general *philosophy* behind that, but i still think
it is more informative if actual live examples are used, rather than
the generic "FOO = fubar" sort of thing.

rday

Re: [docs] a couple random thoughts about YP docs and examples

[Robert P. J. Day]

On Tue, 8 Jul 2025, Antonin Godard via lists.yoctoproject.org wrote:

> On Mon Jul 7, 2025 at 9:16 PM CEST, Robert P. J. Day wrote:
> >
> >   reading the bitbake manual (although this could just as well apply
> > to YP docs in general), my first general nitpick is the number of
> > awkwardly contrived examples that involve contrived variable names.
> > consider this section on the ":remove" directive:
> >
> > https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-metadata.html#removal-override-style-syntax
> >
> > why use variables FOO and FOO2 and arbitrary numeric strings when
> > there are so many meaningful examples in the OE code base that would
> > make actual sense, such as:
> >
> >   meta/recipes-bsp/grub/grub2.inc:CFLAGS:remove = "-O2"
> >   meta/recipes-bsp/grub/grub2.inc:TUNE_CCARGS:remove = "-mfpmath=sse"
> >
> > Examples like that actually suggest to the reader *why* one might want
> > to remove strings from various variables related to various recipes.
> >
> >   Also, I don't see any mention in that section about override-related
> > removal that would be useful to explain, stuff like:
> >
> > meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv32 = "libunwind"
> > meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv64 = "libunwind"
> > meta-poky/conf/distro/poky-tiny.conf:PACKAGECONFIG:remove:pn-opkg-utils = "python"
> >
> > In short, we should be using actual examples from the OE code base as
> > examples, and we should try to be complete.
>
> Bitbake is not only used with OE-Core, and so the Bitbake
> documentation should not make any references to it. Maybe more
> meaningful examples could be taken but we need to keep that in mind.

  I think there is a fundamental flaw in this thinking in that there
is a fair bit of BB-specific content that is *not* covered in the BB
manual, but is covered only in the YP docs. Consider the
previously-mentioned "bitbake-getvar" command -- that utility is
defined by the bitbake layer, but it is currently documented only in
the YP docs.

  If you really and truly want to think of BitBake as a standalone,
independent-from-OE program, then *all* of its features should be
documented in the BB manual. As it is, that's not what's happening at
the moment. If BB should really be treated as standalone, then the BB
docs should document stuff like bitbake-getvar, and bitbake-diffsigs,
and bitbake-layers, and ... well, you get the idea.

  IMNSHO, you can't have it both ways -- you can't insist that BitBake
is standalone, then leave much of its documentation to the YP docs.

rday

Re: [docs] a couple random thoughts about YP docs and examples

[Quentin Schulz]

Hi Robert,

On 7/8/25 11:56 AM, Robert P. J. Day via lists.yoctoproject.org wrote:
> On Tue, 8 Jul 2025, Antonin Godard via lists.yoctoproject.org wrote:
> 
>> On Mon Jul 7, 2025 at 9:16 PM CEST, Robert P. J. Day wrote:
>>>
>>>    reading the bitbake manual (although this could just as well apply
>>> to YP docs in general), my first general nitpick is the number of
>>> awkwardly contrived examples that involve contrived variable names.
>>> consider this section on the ":remove" directive:
>>>
>>> https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-metadata.html#removal-override-style-syntax
>>>
>>> why use variables FOO and FOO2 and arbitrary numeric strings when
>>> there are so many meaningful examples in the OE code base that would
>>> make actual sense, such as:
>>>
>>>    meta/recipes-bsp/grub/grub2.inc:CFLAGS:remove = "-O2"
>>>    meta/recipes-bsp/grub/grub2.inc:TUNE_CCARGS:remove = "-mfpmath=sse"
>>>
>>> Examples like that actually suggest to the reader *why* one might want
>>> to remove strings from various variables related to various recipes.
>>>
>>>    Also, I don't see any mention in that section about override-related
>>> removal that would be useful to explain, stuff like:
>>>
>>> meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv32 = "libunwind"
>>> meta/recipes-devtools/rust/libstd-rs_1.87.0.bb:DEPENDS:remove:riscv64 = "libunwind"
>>> meta-poky/conf/distro/poky-tiny.conf:PACKAGECONFIG:remove:pn-opkg-utils = "python"
>>>
>>> In short, we should be using actual examples from the OE code base as
>>> examples, and we should try to be complete.

FWIW, I did a 45min presentation a few years ago on BitBake operators, I 
barely could catch my breath and didn't manage to put everything I 
wanted in there. There are many possible examples, with corner cases and 
side effects. I do agree we should do better though but I haven't found 
the time (or the way) to make this presentation into actual patches for 
the docs :/ Also the ability to sum things up quickly and clearly isn't 
one of my strengths :)

So while I understand the desire to be complete, it may actually be 
quite tiresome to do it (but we definitely should!).

>>
>> Bitbake is not only used with OE-Core, and so the Bitbake
>> documentation should not make any references to it. Maybe more
>> meaningful examples could be taken but we need to keep that in mind.
> 
>    I think there is a fundamental flaw in this thinking in that there
> is a fair bit of BB-specific content that is *not* covered in the BB
> manual, but is covered only in the YP docs. Consider the
> previously-mentioned "bitbake-getvar" command -- that utility is
> defined by the bitbake layer, but it is currently documented only in
> the YP docs.
> 

It can be moved to BB docs and referred to or augmented in YP docs, 
that's not an issue.

>    If you really and truly want to think of BitBake as a standalone,
> independent-from-OE program, then *all* of its features should be
> documented in the BB manual. As it is, that's not what's happening at
> the moment. If BB should really be treated as standalone, then the BB
> docs should document stuff like bitbake-getvar, and bitbake-diffsigs,
> and bitbake-layers, and ... well, you get the idea.
> 

And I don't see an issue with that. It's just that the YP docs are more 
"public" than the BitBake one so people are just contributing/reading 
that one. YP docs should complement the BB docs with things that aren't 
in BitBake but OE-Core/YP, the rest should be in BB docs (and referring 
it from YP docs or augmenting it in the context of YP/OE-Core).

>    IMNSHO, you can't have it both ways -- you can't insist that BitBake
> is standalone, then leave much of its documentation to the YP docs.
> 

This is just the current situation. We may have made mistakes in the 
past or have now changed our minds, it doesn't mean we have to stick 
with what we have today. I think it's a good thing to not want newer BB 
doc to be in YP docs even if we currently have BB doc in YP docs. We 
really shouldn't be mentioning YP stuff in BB docs though!

However, it doesn't need to be that strict, I would say you could 
provide real life examples but they don't need to link to existing 
recipes in OE-Core or YP. What matters is that we explain why we need to 
do such a thing (e.g. :remove or :remove:some-override). Real life 
examples aren't necessarily easier to understand though, so we could 
have this FOO:remove = "bar" (or with different names, we just need to 
keep it simple and easily justifiable) example augmented with a real 
life example.

Cheers,
Quentin