Skip to contentSkip to conversation

common-tasks.rst: remove SRC_URI:append from examples

PATCH In review Mikko Rapeli 2 participants 6 messages Sep 20, 2022

lore
Share & tools
lore
#0 lore raw

PATCH 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.

---
 documentation/dev-manual/common-tasks.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
documentation/dev-manual/common-tasks.rst +6 -4
index bdc528b723..17d1433150 100644
@@ -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
Signature · 1 line
2.17.1
#1 lore raw

PATCH v3 2/2 kernel-dev/common.rst: remove SRC_URI:append from examples

It's better to use SRC_URI += to append patches etc. If anything is added via :append, that can only be removed with :remove which makes the changes rather permanent compared to light weight += amendmends.

---
 documentation/kernel-dev/common.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
documentation/kernel-dev/common.rst +6 -6
index 16ef6453bd..fb8d7cd029 100644
@@ -360,9 +360,9 @@ home directory:
 
       FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
 
-      SRC_URI:append = " file://patch-file-one.patch"
-      SRC_URI:append = " file://patch-file-two.patch"
-      SRC_URI:append = " file://patch-file-three.patch"
+      SRC_URI += "file://patch-file-one.patch"
+      SRC_URI += "file://patch-file-two.patch"
+      SRC_URI += "file://patch-file-three.patch"
 
    The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
    enable the OpenEmbedded build system to find patch files. For more
@@ -1002,7 +1002,7 @@ Section.
    contents::
 
       FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
-      SRC_URI:append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
+      SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch"
 
    The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
    enable the OpenEmbedded build system to find the patch file.
@@ -1875,7 +1875,7 @@ build.
 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
    recipe's :term:`SRC_URI` statement::
 
-      SRC_URI:append = " file://test.scc"
+      SRC_URI += "file://test.scc"
 
    The leading space before the path is important as the path is
    appended to the existing path.
@@ -1884,7 +1884,7 @@ build.
    :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
    feature::
 
-      KERNEL_FEATURES:append = " test.scc"
+      KERNEL_FEATURES += "test.scc"
 
    The OpenEmbedded build
    system processes the kernel feature when it builds the kernel.
Signature · 1 line
2.17.1
Reviewed-by on v3 2/2
#2 lore raw

Re: [docs] [doc][PATCH v3 2/2] kernel-dev/common.rst: remove SRC_URI:append from examples

Hello Mikko

Quoted 46 lines · Mikko Rapeli

It's better to use SRC_URI += to append patches etc. If anything is added via :append, that can only be removed with :remove which makes the changes rather permanent compared to light weight += amendmends.

---
  documentation/kernel-dev/common.rst | 12 ++++++------
  1 file changed, 6 insertions(+), 6 deletions(-)
documentation/kernel-dev/common.rst +5 -5
index 16ef6453bd..fb8d7cd029 100644
@@ -360,9 +360,9 @@ home directory:
 
        FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
 
-      SRC_URI:append = " file://patch-file-one.patch"
-      SRC_URI:append = " file://patch-file-two.patch"
-      SRC_URI:append = " file://patch-file-three.patch"
+      SRC_URI += "file://patch-file-one.patch"
+      SRC_URI += "file://patch-file-two.patch"
+      SRC_URI += "file://patch-file-three.patch"
 
     The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
     enable the OpenEmbedded build system to find patch files. For more
@@ -1002,7 +1002,7 @@ Section.
     contents::
 
        FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
-      SRC_URI:append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
+      SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch"
 
     The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
     enable the OpenEmbedded build system to find the patch file.
@@ -1875,7 +1875,7 @@ build.
  2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
     recipe's :term:`SRC_URI` statement::
 
-      SRC_URI:append = " file://test.scc"
+      SRC_URI += "file://test.scc"
 
     The leading space before the path is important as the path is
     appended to the existing path.

documentation/kernel-dev/common.rst build. · line 1890

Quoted 8 lines
documentation/kernel-dev/common.rst +1 -1
@@ -1884,7 +1884,7 @@ build.
     :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
     feature::
 
-      KERNEL_FEATURES:append = " test.scc"
+      KERNEL_FEATURES += "test.scc"
 
     The OpenEmbedded build
     system processes the kernel feature when it builds the kernel.

... and merged into master-next too.

Will you send further commit message updates to the other patches in these series?

Thanks
Michael.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
#3 lore raw

Re: [docs] [doc][PATCH v3 2/2] kernel-dev/common.rst: remove SRC_URI:append from examples

Hi,

Quoted 61 lines · Michael Opdenacker

Hello Mikko

Quoted 46 lines · Mikko Rapeli

It's better to use SRC_URI += to append patches etc. If anything is added via :append, that can only be removed with :remove which makes the changes rather permanent compared to light weight += amendmends.

---
  documentation/kernel-dev/common.rst | 12 ++++++------
  1 file changed, 6 insertions(+), 6 deletions(-)
documentation/kernel-dev/common.rst +5 -5
index 16ef6453bd..fb8d7cd029 100644
@@ -360,9 +360,9 @@ home directory:
 
        FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
 
-      SRC_URI:append = " file://patch-file-one.patch"
-      SRC_URI:append = " file://patch-file-two.patch"
-      SRC_URI:append = " file://patch-file-three.patch"
+      SRC_URI += "file://patch-file-one.patch"
+      SRC_URI += "file://patch-file-two.patch"
+      SRC_URI += "file://patch-file-three.patch"
 
     The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
     enable the OpenEmbedded build system to find patch files. For more
@@ -1002,7 +1002,7 @@ Section.
     contents::
 
        FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
-      SRC_URI:append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
+      SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch"
 
     The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
     enable the OpenEmbedded build system to find the patch file.
@@ -1875,7 +1875,7 @@ build.
  2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
     recipe's :term:`SRC_URI` statement::
 
-      SRC_URI:append = " file://test.scc"
+      SRC_URI += "file://test.scc"
 
     The leading space before the path is important as the path is
     appended to the existing path.

documentation/kernel-dev/common.rst build. · line 1890

Quoted 8 lines
documentation/kernel-dev/common.rst +1 -1
@@ -1884,7 +1884,7 @@ build.
     :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
     feature::
 
-      KERNEL_FEATURES:append = " test.scc"
+      KERNEL_FEATURES += "test.scc"
 
     The OpenEmbedded build
     system processes the kernel feature when it builds the kernel.
Quoted 4 lines

... and merged into master-next too.

Will you send further commit message updates to the other patches in these series?

The other changes in the original series are already merged in master so it's a bit
late for commit message updates.

Cheers,
-Mikko

#4 lore raw

Re: [docs] [doc][PATCH v3 2/2] kernel-dev/common.rst: remove SRC_URI:append from examples

Hi Mikko

Quoted 4 lines · Mikko Rapeli

The other changes in the original series are already merged in master so it's a bit
late for commit message updates.

Oops, my bad. I didn't realize they were not documentation changes :} Thanks again
Michael.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
Reviewed-by on v3 1/2
#5 lore raw
In reply to Mikko Rapeli

Hi Mikko,

Thanks for the update.

Quoted 40 lines · Mikko Rapeli

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.

---
  documentation/dev-manual/common-tasks.rst | 10 ++++++----
  1 file changed, 6 insertions(+), 4 deletions(-)
documentation/dev-manual/common-tasks.rst +5 -3
index bdc528b723..17d1433150 100644
@@ -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"

documentation/dev-manual/common-tasks.rst in the BitBake User Manual. · line 2728

Quoted 10 lines
documentation/dev-manual/common-tasks.rst +1 -1
 
     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

... and merged into "master-next".

Cheers
Michael.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com