* [PATCH] migration-guides: Add start of 3.4 guide with override migration notes
@ 2021-07-29 22:09 Richard Purdie
2021-07-30 8:16 ` [docs] " Quentin Schulz
0 siblings, 1 reply; 3+ messages in thread
From: Richard Purdie @ 2021-07-29 22:09 UTC (permalink / raw)
To: docs
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
documentation/migration-guides/index.rst | 1 +
.../migration-guides/migration-3.4.rst | 72 +++++++++++++++++++
2 files changed, 73 insertions(+)
create mode 100644 documentation/migration-guides/migration-3.4.rst
diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst
index 6304e6318..287b55319 100644
--- a/documentation/migration-guides/index.rst
+++ b/documentation/migration-guides/index.rst
@@ -12,6 +12,7 @@ to move to one release of the Yocto Project from the previous one.
.. toctree::
migration-general
+ migration-3.4
migration-3.3
migration-3.2
migration-3.1
diff --git a/documentation/migration-guides/migration-3.4.rst b/documentation/migration-guides/migration-3.4.rst
new file mode 100644
index 000000000..45ce38cd6
--- /dev/null
+++ b/documentation/migration-guides/migration-3.4.rst
@@ -0,0 +1,72 @@
+Release 3.4 (honister)
+======================
+
+This section provides migration information for moving to the Yocto
+Project 3.4 Release (codename "honister") from the prior release.
+
+Override syntax changes
+-----------------------
+
+This release requires changes to the metadata to indicate where overrides are
+being used in variable key names. This is done with the ":" character replacing
+the use of "_" previously. This means that an entry like::
+
+ SRC_URI_qemux86 = "file://somefile"
+
+becomes::
+
+ SRC_URI:qemux86 = " file://somefile"
+
+since qemux86 is an override. This applies to any use of override syntax so::
+
+ SRC_URI_append = " file://somefile"
+ SRC_URI_append_qemux86 = " file://somefile2"
+ SRC_URI_remove_qemux86-64 = " file://somefile3"
+ SRC_URI_prepend_qemuarm = "file://somefile4 "
+ FILES_${PN}-ptest = "${bindir}/xyz"
+ IMAGE_CMD_tar = "tar"
+ BASE_LIB_tune-coretexa76 = "lib"
+ SRCREV_pn-bash = "abc"
+ BB_TASK_NICE_LEVEL_task-testimage = '0'
+
+becomes::
+
+ SRC_URI:append = " file://somefile"
+ SRC_URI:append:qemux86 = " file://somefile2"
+ SRC_URI:remove:qemux86-64 = " file://somefile3"
+ SRC_URI:prepend:qemuarm = "file://somefile4 "
+ FILES:${PN}-ptest = "${bindir}/xyz"
+ IMAGE_CMD:tar = "tar"
+ BASE_LIB:tune-coretexa76 = "lib"
+ SRCREV:pn-bash = "abc"
+ BB_TASK_NICE_LEVEL:task-testimage = '0'
+
+This also applies to variable queries to the datastore, for example using getVar
+and similar so d.getVar("RDEPENDS_${PN}") becomes d.getVar("RDEPENDS:${PN}").
+
+Whilst some of these are fairly obvious such as MACHINE and DISTRO overrides, some
+are less obvious, for example the packaging variables such as RDEPENDS, FILES and
+so on taking package names (e.g. ${PN}, ${PN}-ptest) as overrides. These overrides
+are not always applies in OVERRIDES but applied conditionally in specific contexts
+such as packaging. The task-<taskname> is another context specific override, the
+context being specific tasks in that case. Tune overrides are another specialist
+case where some code does use them as overrides but some does not. We plan to try
+and make the tune code use overrides more consistently in the future.
+
+To help with migration of layers there is a script in OE-Core. Once configured
+with the overrides used by a layer, this can be run as::
+
+ <oe-core>/scripts/contrib/convert-overrides.py <layerdir>
+
+Please read the notes in the script as it isn't entirely automatic and it isn't
+expected to handle every case. In particular, it needs to be told which overrides
+the layer uses (usually machine and distro names/overrides) and the result should
+be carefully checked since it can be a little enthusiastic and will convert
+references to "_append", "_remove" and "_prepend" in function and variables names.
+
+For reference, this conversion is important as it allows bitbake to know what is
+an override and what is not. This should allow us to proceed with other syntax
+improvements and simplifications for usability. It also means bitbake no longer
+has to guess and maintain large lookup lists just in case "functionname" in
+"my_functionname" is an override and this should improve efficiency.
+
--
2.30.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [docs] [PATCH] migration-guides: Add start of 3.4 guide with override migration notes
2021-07-29 22:09 [PATCH] migration-guides: Add start of 3.4 guide with override migration notes Richard Purdie
@ 2021-07-30 8:16 ` Quentin Schulz
2021-07-30 9:27 ` Michael Opdenacker
0 siblings, 1 reply; 3+ messages in thread
From: Quentin Schulz @ 2021-07-30 8:16 UTC (permalink / raw)
To: Richard Purdie; +Cc: docs
Hi Richard,
On Thu, Jul 29, 2021 at 11:09:45PM +0100, Richard Purdie wrote:
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
> documentation/migration-guides/index.rst | 1 +
> .../migration-guides/migration-3.4.rst | 72 +++++++++++++++++++
> 2 files changed, 73 insertions(+)
> create mode 100644 documentation/migration-guides/migration-3.4.rst
>
> diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst
> index 6304e6318..287b55319 100644
> --- a/documentation/migration-guides/index.rst
> +++ b/documentation/migration-guides/index.rst
> @@ -12,6 +12,7 @@ to move to one release of the Yocto Project from the previous one.
> .. toctree::
>
> migration-general
> + migration-3.4
> migration-3.3
> migration-3.2
> migration-3.1
> diff --git a/documentation/migration-guides/migration-3.4.rst b/documentation/migration-guides/migration-3.4.rst
> new file mode 100644
> index 000000000..45ce38cd6
> --- /dev/null
> +++ b/documentation/migration-guides/migration-3.4.rst
> @@ -0,0 +1,72 @@
> +Release 3.4 (honister)
> +======================
> +
> +This section provides migration information for moving to the Yocto
> +Project 3.4 Release (codename "honister") from the prior release.
> +
> +Override syntax changes
> +-----------------------
> +
> +This release requires changes to the metadata to indicate where overrides are
> +being used in variable key names. This is done with the ":" character replacing
> +the use of "_" previously. This means that an entry like::
> +
> + SRC_URI_qemux86 = "file://somefile"
> +
> +becomes::
> +
> + SRC_URI:qemux86 = " file://somefile"
> +
Is the leading space here on purpose?
> +since qemux86 is an override. This applies to any use of override syntax so::
> +
I'm pondering whether we should quote or tick quote qemux86?
> + SRC_URI_append = " file://somefile"
> + SRC_URI_append_qemux86 = " file://somefile2"
> + SRC_URI_remove_qemux86-64 = " file://somefile3"
> + SRC_URI_prepend_qemuarm = "file://somefile4 "
> + FILES_${PN}-ptest = "${bindir}/xyz"
> + IMAGE_CMD_tar = "tar"
> + BASE_LIB_tune-coretexa76 = "lib"
s/BASE_LIB_tune-coretexa76/BASE_LIB_tune-cortexa76/
> + SRCREV_pn-bash = "abc"
> + BB_TASK_NICE_LEVEL_task-testimage = '0'
> +
> +becomes::
> +
> + SRC_URI:append = " file://somefile"
> + SRC_URI:append:qemux86 = " file://somefile2"
> + SRC_URI:remove:qemux86-64 = " file://somefile3"
> + SRC_URI:prepend:qemuarm = "file://somefile4 "
> + FILES:${PN}-ptest = "${bindir}/xyz"
> + IMAGE_CMD:tar = "tar"
> + BASE_LIB:tune-coretexa76 = "lib"
s/BASE_LIB:tune-coretexa76/BASE_LIB:tune-cortexa76/
> + SRCREV:pn-bash = "abc"
> + BB_TASK_NICE_LEVEL:task-testimage = '0'
> +
> +This also applies to variable queries to the datastore, for example using getVar
> +and similar so d.getVar("RDEPENDS_${PN}") becomes d.getVar("RDEPENDS:${PN}").
> +
Probably would benefit from tick quotes?
> +Whilst some of these are fairly obvious such as MACHINE and DISTRO overrides, some
s/MACHINE/:term:`MACHINE`/
Ditto for DISTRO.
> +are less obvious, for example the packaging variables such as RDEPENDS, FILES and
Ditto for RDEPENDS and FILES.
> +so on taking package names (e.g. ${PN}, ${PN}-ptest) as overrides. These overrides
Tick quotes for ${PN}?
> +are not always applies in OVERRIDES but applied conditionally in specific contexts
s/OVERRIDES/:term:`OVERRIDES`/
s/applies// ?
> +such as packaging. The task-<taskname> is another context specific override, the
Tick quoting task-<taskname>?
> +context being specific tasks in that case. Tune overrides are another specialist
s/specialist/special/ ?
> +case where some code does use them as overrides but some does not. We plan to try
> +and make the tune code use overrides more consistently in the future.
> +
> +To help with migration of layers there is a script in OE-Core. Once configured
Add a link to this script whose text is "a script in OE-Core"? (I know
it's mentioned below).
> +with the overrides used by a layer, this can be run as::
> +
> + <oe-core>/scripts/contrib/convert-overrides.py <layerdir>
> +
> +Please read the notes in the script as it isn't entirely automatic and it isn't
> +expected to handle every case. In particular, it needs to be told which overrides
> +the layer uses (usually machine and distro names/overrides) and the result should
> +be carefully checked since it can be a little enthusiastic and will convert
> +references to "_append", "_remove" and "_prepend" in function and variables names.
> +
Pondering whether the one (or two) paragpraphs above should be in a
..note section to highlight it.
> +For reference, this conversion is important as it allows bitbake to know what is
> +an override and what is not. This should allow us to proceed with other syntax
> +improvements and simplifications for usability. It also means bitbake no longer
> +has to guess and maintain large lookup lists just in case "functionname" in
> +"my_functionname" is an override and this should improve efficiency.
> +
Thanks for the patch :)
Cheers,
Quentin
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [docs] [PATCH] migration-guides: Add start of 3.4 guide with override migration notes
2021-07-30 8:16 ` [docs] " Quentin Schulz
@ 2021-07-30 9:27 ` Michael Opdenacker
0 siblings, 0 replies; 3+ messages in thread
From: Michael Opdenacker @ 2021-07-30 9:27 UTC (permalink / raw)
To: Quentin Schulz, Richard Purdie; +Cc: docs
Richard, thanks for the patch
Quentin, thanks for the review
I'm taking care of preparing a V2 to reduce the load on Richard's
shoulders...
On 7/30/21 10:16 AM, Quentin Schulz wrote:
> Hi Richard,
>
> On Thu, Jul 29, 2021 at 11:09:45PM +0100, Richard Purdie wrote:
>> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
>> ---
>> documentation/migration-guides/index.rst | 1 +
>> .../migration-guides/migration-3.4.rst | 72 +++++++++++++++++++
>> 2 files changed, 73 insertions(+)
>> create mode 100644 documentation/migration-guides/migration-3.4.rst
>>
>> diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst
>> index 6304e6318..287b55319 100644
>> --- a/documentation/migration-guides/index.rst
>> +++ b/documentation/migration-guides/index.rst
>> @@ -12,6 +12,7 @@ to move to one release of the Yocto Project from the previous one.
>> .. toctree::
>>
>> migration-general
>> + migration-3.4
>> migration-3.3
>> migration-3.2
>> migration-3.1
>> diff --git a/documentation/migration-guides/migration-3.4.rst b/documentation/migration-guides/migration-3.4.rst
>> new file mode 100644
>> index 000000000..45ce38cd6
>> --- /dev/null
>> +++ b/documentation/migration-guides/migration-3.4.rst
>> @@ -0,0 +1,72 @@
>> +Release 3.4 (honister)
>> +======================
>> +
>> +This section provides migration information for moving to the Yocto
>> +Project 3.4 Release (codename "honister") from the prior release.
>> +
>> +Override syntax changes
>> +-----------------------
>> +
>> +This release requires changes to the metadata to indicate where overrides are
>> +being used in variable key names. This is done with the ":" character replacing
>> +the use of "_" previously. This means that an entry like::
>> +
>> + SRC_URI_qemux86 = "file://somefile"
>> +
>> +becomes::
>> +
>> + SRC_URI:qemux86 = " file://somefile"
>> +
> Is the leading space here on purpose?
Assuming that's a typo. Fixed.
>
>> +since qemux86 is an override. This applies to any use of override syntax so::
>> +
> I'm pondering whether we should quote or tick quote qemux86?
I'll set it to ``qemux86`` but I plan to write some documentation coding
style so that we know which conventions to follow.
>
>> + SRC_URI_append = " file://somefile"
>> + SRC_URI_append_qemux86 = " file://somefile2"
>> + SRC_URI_remove_qemux86-64 = " file://somefile3"
>> + SRC_URI_prepend_qemuarm = "file://somefile4 "
>> + FILES_${PN}-ptest = "${bindir}/xyz"
>> + IMAGE_CMD_tar = "tar"
>> + BASE_LIB_tune-coretexa76 = "lib"
> s/BASE_LIB_tune-coretexa76/BASE_LIB_tune-cortexa76/
Fixed.
>> + SRCREV:pn-bash = "abc"
>> + BB_TASK_NICE_LEVEL:task-testimage = '0'
>> +
>> +This also applies to variable queries to the datastore, for example using getVar
>> +and similar so d.getVar("RDEPENDS_${PN}") becomes d.getVar("RDEPENDS:${PN}").
>> +
> Probably would benefit from tick quotes?
Done
>
>> +Whilst some of these are fairly obvious such as MACHINE and DISTRO overrides, some
> s/MACHINE/:term:`MACHINE`/
>
> Ditto for DISTRO.
>
>> +are less obvious, for example the packaging variables such as RDEPENDS, FILES and
> Ditto for RDEPENDS and FILES.
Fixed
>
>> +so on taking package names (e.g. ${PN}, ${PN}-ptest) as overrides. These overrides
> Tick quotes for ${PN}?
>
>> +are not always applies in OVERRIDES but applied conditionally in specific contexts
> s/OVERRIDES/:term:`OVERRIDES`/
All fixed!
>
> s/applies// ?
I first felt like writing "applied" instead, but this makes sense too.
The sentence is now:
"These overrides are not always in
:term:`OVERRIDES` but applied conditionally in specific contexts
such as packaging"
>
>> +such as packaging. The task-<taskname> is another context specific override, the
> Tick quoting task-<taskname>?
Yes
>
>> +context being specific tasks in that case. Tune overrides are another specialist
> s/specialist/special/ ?
Make sense
>
>> +case where some code does use them as overrides but some does not. We plan to try
>> +and make the tune code use overrides more consistently in the future.
>> +
>> +To help with migration of layers there is a script in OE-Core. Once configured
> Add a link to this script whose text is "a script in OE-Core"? (I know
> it's mentioned below).
>
>> +with the overrides used by a layer, this can be run as::
>> +
>> + <oe-core>/scripts/contrib/convert-overrides.py <layerdir>
I'm not sure about what you're proposing here. I believe we currently
don't put hyperlinks to source code in the documentation, we just
mention the file paths. We could though.
>> +
>> +Please read the notes in the script as it isn't entirely automatic and it isn't
>> +expected to handle every case. In particular, it needs to be told which overrides
>> +the layer uses (usually machine and distro names/overrides) and the result should
>> +be carefully checked since it can be a little enthusiastic and will convert
>> +references to "_append", "_remove" and "_prepend" in function and variables names.
>> +
> Pondering whether the one (or two) paragpraphs above should be in a
> ..note section to highlight it.
Good idea, I put the first paragraph in a note. I didn't want the second
paragraph to be in the same note. This way it's more visible IMHO.
I'll submit my V2 soon.
Thanks again,
Michael.
--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2021-07-30 9:27 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-07-29 22:09 [PATCH] migration-guides: Add start of 3.4 guide with override migration notes Richard Purdie
2021-07-30 8:16 ` [docs] " Quentin Schulz
2021-07-30 9:27 ` Michael Opdenacker
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.