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

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

[Simon Eugster]

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

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: 5959 bytes --]

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

[Simon Eugster]

[-- 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 --]

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

[Simon Eugster]

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

On Wed, Jan 5, 2022 at 5:02 PM Michael Opdenacker <
michael.opdenacker@bootlin.com> wrote:

> Hi Simon,
>
> Thanks for your answers...
>
> On 1/5/22 11:11 AM, Simon Eugster wrote:
> > Hi Michael,
> >
> >     >
> >     > +.. 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.
>
>
> This makes sense, but so far we just mentioned the old syntax in the
> migration guides. That's why I was asking for other opinions...
>

Looks like there are no other opinions on that topic.
In that case, do you want me to continue with the MR and apply your
suggestions, or discard the MR?

Simon

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

[PATCH] bitbake-user-manual: add note about the old syntax for OVERRIDES

[Michael Opdenacker]

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Peter Kjellerstedt <peter.kjellerstedt@axis.com>
Reported-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../bitbake-user-manual-metadata.rst                   | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index b90e5cf0..97114ed6 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -585,6 +585,16 @@ variable.
 
       EXTRA_OEMAKE:prepend:task-compile = "${PARALLEL_MAKE} "
 
+.. note::
+
+   Before BitBake 1.52 (Honister 3.4), the syntax for :term:`OVERRIDES`
+   used ``_`` instead of ``:``, so you will still find a lot of documentation
+   using ``_append``, ``_prepend``, and ``_remove``, for example.
+
+   For details, see the
+   :yocto_docs:`Overrides Syntax Changes </migration-guides/migration-3.4.html#override-syntax-changes>`
+   section in the Yocto Project manual migration notes.
+
 Key Expansion
 -------------
 
-- 
2.25.1

Re: [docs] [PATCH] bitbake-user-manual: add note about the old syntax for OVERRIDES

[Quentin Schulz]

Hi Michael,

On 3/7/22 19:38, Michael Opdenacker via lists.yoctoproject.org wrote:
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> Reported-by: Peter Kjellerstedt <peter.kjellerstedt@axis.com>
> Reported-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
>   .../bitbake-user-manual-metadata.rst                   | 10 ++++++++++
>   1 file changed, 10 insertions(+)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index b90e5cf0..97114ed6 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -585,6 +585,16 @@ variable.
>   
>         EXTRA_OEMAKE:prepend:task-compile = "${PARALLEL_MAKE} "
>   
> +.. note::
> +
> +   Before BitBake 1.52 (Honister 3.4), the syntax for :term:`OVERRIDES`
> +   used ``_`` instead of ``:``, so you will still find a lot of documentation

We should mention that we're talking about external/third party 
documentation/tutorials and not ours :)

Cheers,
Quentin

Re: [docs] [PATCH] bitbake-user-manual: add note about the old syntax for OVERRIDES

[Michael Opdenacker]

Hi Quentin

Thanks for the review.

On 3/10/22 11:54, Quentin Schulz wrote:
> We should mention that we're talking about external/third party
> documentation/tutorials and not ours :)


Oops, Richard already merged the change. Is it really worth it to make
another commit for such an update?
Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Simon Eugster]

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

I submitted a patch for only the OVERRIDE part now. (The in-reply-to did
not seem to have an effect – sorry for that!)

I can submit that part as separate patch and I'm happy to re-phrase or
change it in other ways.

+.. note::
+
+   Before Honister (3.4), override style used ``_`` instead of ``:``, so
you will
+   still find a lot of documentation using “_append”, “_prepend”, and
+   “_remove”.

Simon

On Tue, Mar 1, 2022 at 2:33 PM Richard Purdie <
richard.purdie@linuxfoundation.org> wrote:

> On Tue, 2022-03-01 at 09:33 +0100, Michael Opdenacker via
> lists.openembedded.org
> wrote:
> > Hi Simon,
> >
> > On 2/28/22 10:31, Simon A. Eugster wrote:
> > >
> > > On Wed, Jan 5, 2022 at 5:02 PM Michael Opdenacker
> > > <michael.opdenacker@bootlin.com> wrote:
> > >
> > >     Hi Simon,
> > >
> > >     Thanks for your answers...
> > >
> > >     On 1/5/22 11:11 AM, Simon Eugster wrote:
> > >     > Hi Michael,
> > >     >
> > >     >     >
> > >     >     > +.. 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.
> > >
> > >
> > >     This makes sense, but so far we just mentioned the old syntax in
> the
> > >     migration guides. That's why I was asking for other opinions...
> > >
> > >
> > > Looks like there are no other opinions on that topic.
> > > In that case, do you want me to continue with the MR and apply your
> > > suggestions, or discard the MR?
> >
> >
> > Well, I'd rather drop the note about the overrides syntax change, but
> > I'm still interested in the rest of the patch.
>
> Since you asked for opinions, I think some mention of this in the overrides
> section of the bitbake manual would be a good idea since it was such a
> fundamental change?
>
> Cheers,
>
> Richard
>
>
>
>
>
>

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

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

[Simon Eugster]

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

Hi Michael,

On Fri, Mar 25, 2022 at 3:31 PM Michael Opdenacker <
michael.opdenacker@bootlin.com> wrote:

> Hi Simon,
>
> On 3/23/22 13:24, Simon A. Eugster wrote:
> > I submitted a patch for only the OVERRIDE part now. (The in-reply-to
> > did not seem to have an effect – sorry for that!)
> >
> > I can submit that part as separate patch and I'm happy to re-phrase or
> > change it in other ways.
> >
> > +.. note::
> > +
> > +   Before Honister (3.4), override style used ``_`` instead of ``:``,
> > so you will
> > +   still find a lot of documentation using “_append”, “_prepend”, and
> > +   “_remove”.
>
>
> This text has already been added:
>
> https://git.openembedded.org/bitbake/commit/?id=ad2307823a96e91873d804aa9d8f11c9ff39bec0


Ah okay, I did not see that. Perfect!

Simon

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

Re: [docs] [PATCH] bitbake: doc: bitbake-user-manual: Improve OVERRIDES docs

[Michael Opdenacker]

Hi Simon

On 3/23/22 13:16, Simon A. Eugster wrote:
> Improve the explanation about OVERRIDES to clarify how variable
> overrides are chosen based on OVERRIDES.
>
> Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> ---
>  .../bitbake-user-manual-metadata.rst          | 20 ++++++++++---------
>  1 file changed, 11 insertions(+), 9 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index ea42d77c..a78f9048 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -517,20 +517,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 = "arm:linux:beaglebone"
>        TEST = "default"
> -      TEST:os = "osspecific"
> +      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


Shouldn't the three overrides be "beaglebone", "linux" and "arm" from
the code above?
Thanks
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Simon Eugster]

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

Hi Michael,

On Tue, Mar 29, 2022 at 7:11 PM Michael Opdenacker <
michael.opdenacker@bootlin.com> wrote:

> Hi Simon,
>
> Thanks for the patch update. See my comments below.
>
> On 3/29/22 16:37, Simon A. Eugster wrote:
> > Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> > ---
> >  .../bitbake-user-manual-metadata.rst          | 26 ++++++++++++-------
> >  1 file changed, 17 insertions(+), 9 deletions(-)
> >
> > diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> > index ea42d77c..7d7d99c2 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”.
> > +
> >  .. _removing-override-style-syntax:
> >
> >  Removal (Override Style Syntax)
>
>
> As discussed previously, we already have such as statement elsewhere in
> the same file (currently:
>
> https://git.openembedded.org/bitbake/tree/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst#n590
> ).
>

Sorry, not sure how that slipped into the patch again, I had previously
removed it. Should be fixed now! :)

(Would be a bit easier with MRs on something like GitLab O:-))

Thanks and sorry for the countless retries,
Simon

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