Fwd: [docs] [PATCH] bitbake: doc: bitbake-user-manual: Add more explanations to OVERRIDES

[Simon Eugster <simon.eu@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4532 bytes --]

(Forwarding manually because I was not subscribed anymore and the email got
dropped.)

Hi Michael,

Am Mi., 15. Dez. 2021 um 11:46 Uhr schrieb Michael Opdenacker <
michael.opdenacker@bootlin.com>:

> Hi Simon,
>
> Many thanks for the new version of your patch!
> See my questions below...
>
> On 12/15/21 10:25 AM, Simon A. Eugster wrote:
> > Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> > ---
> >  .../bitbake-user-manual-metadata.rst          | 28 ++++++++++++-------
> >  1 file changed, 18 insertions(+), 10 deletions(-)
> >
> > diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> > index d802a8d3..fc4f5d13 100644
> > --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> > @@ -300,6 +300,12 @@ It is also possible to append and prepend to shell
> functions and
> >  BitBake-style Python functions. See the
> ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:shell functions`"
> and ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style
> python functions`"
> >  sections for examples.
> >
> > +.. note::
> > +
> > +   Before Honister (3.4), override style used ``_`` instead of ``:``,
> so you will
> > +   still find a lot of documentation using “_append”, “_prepend”, and
> > +   “_remove”.
> > +
>
>
> I don't have anything about this text, but I wonder whether we should
> mention the old syntax in the current docs.
> Thoughts anyone?
>

I added this because I (as a new user) found it very confusing to find all
the _ style syntax in guides online and no mention of it in the docs. I
would have expected such a note.


> >  .. _removing-override-style-syntax:
> >
> >  Removal (Override Style Syntax)
> > @@ -517,20 +523,22 @@ variable.
> >  -  *Selecting a Variable:* The :term:`OVERRIDES` variable is a
> >     colon-character-separated list that contains items for which you want
> >     to satisfy conditions. Thus, if you have a variable that is
> > -   conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the
> > +   conditional on "arm", and "arm" is listed in :term:`OVERRIDES`, then
> the
> >     "arm"-specific version of the variable is used rather than the
> >     non-conditional version. Here is an example::
> >
> > -      OVERRIDES = "architecture:os:machine"
> > +      # Typically, OVERRIDES contains something like
> architecture:os:machine
> > +      OVERRIDES = "linux:arm"
>
>
> Here you quote an example with two items, but this doesn't align with
> the typical contents with three items you mention in the comment that
> you added.
> By the way, according to the below text, didn't you mean?
>
> OVERRIDES = "foo:linux:arm"
>
> It looks like a good idea to have this comment; this way you can give a
> concrete example. In my opinion, "foo" is vague, what about instead?
>
> OVERRIDES = "arm:linux:beaglebone"
>

Yes, will change that!


> >        TEST = "default"
> > -      TEST_os = "osspecific"
> > -      TEST_nooverride = "othercondvalue"
> > +      TEST:arm = "armspecific"
> > +      TEST:nooverride = "othercondvalue"
> >
> > -   In this example, the :term:`OVERRIDES`
> > -   variable lists three overrides: "architecture", "os", and "machine".
> > -   The variable ``TEST`` by itself has a default value of "default". You
> > -   select the os-specific version of the ``TEST`` variable by appending
> > -   the "os" override to the variable (i.e. ``TEST_os``).
> > +   In this example, the :term:`OVERRIDES` variable lists three
> > +   overrides: "foo", "linux", and "arm". The variable ``TEST`` by itself
> > +   has a default value of "default", and the value of the “arm” specific
> > +   version “armspecific” is used because :term:`OVERRIDES` contains
> > +   “arm”. The “nooverride” specific version is not used because
> > +   :term:`OVERRIDES` does not contain “nooverride”.
> >
> >     To better understand this, consider a practical example that assumes
> >     an OpenEmbedded metadata-based Linux kernel recipe file. The
> > @@ -552,7 +560,7 @@ variable.
> >
> >        DEPENDS = "glibc ncurses"
> >        OVERRIDES = "machine:local"
> > -      DEPENDS:append:machine = "libmad"
> > +      DEPENDS:append:machine = " libmad"
> >
> >     In this example, :term:`DEPENDS` becomes "glibc ncurses libmad".
>

Thanks,
Simon

[-- Attachment #2: Type: text/html, Size: 6133 bytes --]