[doc,v3,1/2] common-tasks.rst: remove SRC_URI:append from examples

Using SRC_URI:append without recipe, machine or architecture specific
limitations makes the :append'ed text more difficult to override than if
the "+=" operator was used. This makes it hard for example to override
SRC_URI completely in a bbappend to update the full recipe to a newer
version. Thus common, reusable layers which users are meant to re-use
and customize should not use SRC_URI:append but SRC_URI += instead.

Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
---
 documentation/dev-manual/common-tasks.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

Hi Mikko,

Thanks for the update.

On 9/20/22 08:45, Mikko Rapeli wrote:
> Using SRC_URI:append without recipe, machine or architecture specific
> limitations makes the :append'ed text more difficult to override than if
> the "+=" operator was used. This makes it hard for example to override
> SRC_URI completely in a bbappend to update the full recipe to a newer
> version. Thus common, reusable layers which users are meant to re-use
> and customize should not use SRC_URI:append but SRC_URI += instead.
>
> Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> ---
>   documentation/dev-manual/common-tasks.rst | 10 ++++++----
>   1 file changed, 6 insertions(+), 4 deletions(-)
>
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index bdc528b723..17d1433150 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -2577,7 +2577,7 @@ chapter of the BitBake User Manual.
>   
>         S = "${WORKDIR}/postfix-${PV}"
>         CFLAGS += "-DNO_ASM"
> -      SRC_URI:append = " file://fixup.patch"
> +      CFLAGS:append = " --enable-important-feature"
>   
>   -  *Functions:* Functions provide a series of actions to be performed.
>      You usually use functions to override the default implementation of a
> @@ -2708,19 +2708,21 @@ in the BitBake User Manual.
>      to existing variables. This operator does not add any additional
>      space. Also, the operator is applied after all the ``+=``, and ``=+``
>      operators have been applied and after all ``=`` assignments have
> -   occurred.
> +   occurred. This means that if ``:append`` is used in a recipe, it can
> +   only be overridden by another layer using the  special ``:remove``
> +   operator, which in turn will prevent further layers from adding it back.
>   
>      The following example shows the space being explicitly added to the
>      start to ensure the appended value is not merged with the existing
>      value::
>   
> -      SRC_URI:append = " file://fix-makefile.patch"
> +      CFLAGS:append = " --enable-important-feature"
>   
>      You can also use
>      the ``:append`` operator with overrides, which results in the actions
>      only being performed for the specified target or machine::
>   
> -      SRC_URI:append:sh4 = " file://fix-makefile.patch"
> +      CFLAGS:append:sh4 = " --enable-important-sh4-specific-feature"
>   
>   -  *Prepending (:prepend):* Use the ``:prepend`` operator to prepend
>      values to existing variables. This operator does not add any


Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
... and merged into "master-next".

Cheers
Michael.