Re: [docs] [PATCH] migration-guides: Add start of 3.4 guide with override migration notes

["Quentin Schulz" <quentin.schulz@theobroma-systems.com>]

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