bitbake: doc: bitbake-user-manual: Add more explanations to OVERRIDES
Hi Michael,
Am Mi., 15. Dez. 2021 um 11:46 Uhr schrieb Michael Opdenacker < [email protected]>:
Quoted 28 lines
Hi Simon,
Many thanks for the new version of your patch!
See my questions below...Review
Quoted 6 lines · Simon A. Eugster
Signed-off-by Simon A. Eugster <[email protected]>--- .../bitbake-user-manual-metadata.rst | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-)(quoted diff) +0
-0
b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rstdoc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell
Quoted 4 lines
index
d802a8d3..fc4f5d13100644doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0@@ -300,6 +300,12 @@ It is also possible to append and prepend to shellfunctions and
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 300
Quoted 1 line
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0BitBake-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"doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 305
Quoted 5 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-0sections for examples. +.. note:: + + Before Honister (3.4), override style used ``_`` instead of ``:``,so you will
Quoted 9 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 308
Quoted 3 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-0+ 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.
Quoted 24 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 526
Quoted 9 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-1.. _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`, thenthe
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 530
Quoted 5 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-1"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 likearchitecture:os:machine
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 531
Quoted 1 line
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-0+ 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?
Quoted 7 lines
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!
Quoted 22 lines
Quoted 22 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +8
-7TEST = "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.
Quoted 7 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 565
Quoted 6 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-1DEPENDS = "glibc ncurses" OVERRIDES = "machine:local" - DEPENDS:append:machine = "libmad" + DEPENDS:append:machine = " libmad" In this example, :term:`DEPENDS` becomes "glibc ncurses libmad".
Thanks,
Simon
PATCH 1/1 bitbake: doc: bitbake-user-manual: Add more explanations to OVERRIDES
(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 < [email protected]>:
Quoted 28 lines
Hi Simon,
Many thanks for the new version of your patch!
See my questions below...Review
Quoted 6 lines · Simon A. Eugster
Signed-off-by Simon A. Eugster <[email protected]>--- .../bitbake-user-manual-metadata.rst | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-)(quoted diff) +0
-0
b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rstdoc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell
Quoted 4 lines
index
d802a8d3..fc4f5d13100644doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0@@ -300,6 +300,12 @@ It is also possible to append and prepend to shellfunctions and
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 300
Quoted 1 line
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0BitBake-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"doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 305
Quoted 5 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-0sections for examples. +.. note:: + + Before Honister (3.4), override style used ``_`` instead of ``:``,so you will
Quoted 9 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 308
Quoted 3 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-0+ 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.
Quoted 24 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 526
Quoted 9 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-1.. _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`, thenthe
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 530
Quoted 5 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-1"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 likearchitecture:os:machine
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 531
Quoted 1 line
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-0+ 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?
Quoted 7 lines
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!
Quoted 22 lines
Quoted 22 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +8
-7TEST = "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.
Quoted 7 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 565
Quoted 6 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +1
-1DEPENDS = "glibc ncurses" OVERRIDES = "machine:local" - DEPENDS:append:machine = "libmad" + DEPENDS:append:machine = " libmad" In this example, :term:`DEPENDS` becomes "glibc ncurses libmad".
Thanks,
Simon
Quoted 23 lines · Michael Opdenacker
Hi Simon,
Thanks for your answers...
Quoted 18 lines · Simon Eugster
Hi Michael,
Review
Quoted 4 lines
+.. note::
(quoted diff) +2
-0+ + 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?
Quoted 8 lines
Quoted 3 lines
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
PATCH 1/1 bitbake-user-manual: add note about the old syntax for OVERRIDES
In reply to a message not in the archive--- .../bitbake-user-manual-metadata.rst | 10 ++++++++++ 1 file changed, 10 insertions(+)
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +10 -0
@@ -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 -------------
Signature · 1 line
2.25.1
Re: [docs] [PATCH] bitbake-user-manual: add note about the old syntax for OVERRIDES
Hi Michael,
Quoted 12 lines · Michael Opdenacker via lists.yoctoproject.org
Signed-off-by Michael Opdenacker <[email protected]>Reported-by Peter Kjellerstedt <[email protected]>Reported-by Richard Purdie <[email protected]>--- .../bitbake-user-manual-metadata.rst | 10 ++++++++++ 1 file changed, 10 insertions(+)doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 591
Quoted 7 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +4
-0@@ -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
Hi Quentin
Thanks for the review.
Quoted 2 lines · Quentin Schulz
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.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
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
Quoted 68 lines · Richard Purdie
Quoted 35 lines · Michael Opdenacker via lists.openembedded.org
Hi Simon,
Quoted 32 lines · Simon A. Eugster
On Wed, Jan 5, 2022 at 5:02 PM Michael Opdenacker
<[email protected]> 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 inthe
Quoted 4 lines
Quoted 4 lines
Quoted 1 line
docs. I would have expected such a note.
This makes sense, but so far we just mentioned the old syntax in
the
Quoted 10 lines
Quoted 6 lines
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
Re: [docs] [PATCH] bitbake: doc: bitbake-user-manual: Improve OVERRIDES docs
In reply to a message not in the archiveHi Simon
Quoted 26 lines · Simon A. Eugster
Improve the explanation about OVERRIDES to clarify how variable overrides are chosen based on OVERRIDES.
Signed-off-by Simon A. Eugster <[email protected]>--- .../bitbake-user-manual-metadata.rst | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-)doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-3@@ -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"
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst variable. · line 531
Quoted 10 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-5+ 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.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Hi Michael,
Quoted 17 lines · Michael Opdenacker
Hi Simon,
Review
Quoted 12 lines · Simon A. Eugster
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::
(quoted diff) +2
-0+ + Before Honister (3.4), override style used ``_`` instead of ``:``,so you will
(quoted diff) +2
-0+ still find a lot of documentation using “_append”, “_prepend”, and + “_remove”.
Quoted 3 lines
This text has already been added:
https://git.openembedded.org/bitbake/commit/?id=ad2307823a96e91873d804aa9d8f11c9ff39bec0
Ah okay, I did not see that. Perfect!
Simon
Hi Michael,
Quoted 32 lines · Michael Opdenacker
Hi Simon,
Thanks for the patch update. See my comments below.
Review
Quoted 6 lines · Simon A. Eugster
Signed-off-by Simon A. Eugster <[email protected]>--- .../bitbake-user-manual-metadata.rst | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-)(quoted diff) +0
-0
b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rstdoc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell
Quoted 4 lines
index
ea42d77c..7d7d99c2100644doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0@@ -300,6 +300,12 @@ It is also possible to append and prepend to shellfunctions and
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 300
Quoted 1 line
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0BitBake-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"doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 305
Quoted 5 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-0sections for examples. +.. note:: + + Before Honister (3.4), override style used ``_`` instead of ``:``,so you will
Quoted 5 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +3
-0+ still find a lot of documentation using “_append”, “_prepend”, and + “_remove”. + .. _removing-override-style-syntax:
Quoted 9 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst It is also possible to append and prepend to shell · line 311
Quoted 1 line
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0
-0Removal (Override Style Syntax)As discussed previously, we already have such as statement elsewhere in the same file (currently:
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