Skip to contentSkip to conversation

common-tasks: Add a summary to the end of the bbappend example

PATCH In review Tom Rini 4 participants 14 messages Aug 12, 2021 – Aug 13, 2021

lore
Share & tools
lore

Tom Rini

author
#0 lore raw

PATCH 1/3 common-tasks: Add a summary to the end of the bbappend example

Try and make it clearer what the final result of this bbappend example is.

---
 documentation/dev-manual/common-tasks.rst | 6 ++++++
 1 file changed, 6 insertions(+)
documentation/dev-manual/common-tasks.rst +6 -0
index 37077d72d451..2d8ef96e2600 100644
@@ -545,6 +545,12 @@ important as it ensures that items in the list remain colon-separated.
    allow to add build options (e.g. ``systemd``). For these cases, your
    append file would not even use the :term:`FILESEXTRAPATHS` statement.
 
+The end result of this ``.bbappend`` file is that on a Raspberry Pi, where
+``rpi`` will exist in the list of :term:`OVERRIDES`, the file
+``meta-raspberrypi/recipes-bsp/formfactor/formfactor/rpi/machconfig`` will be
+used during ``do_fetch`` and the test for a non-zero file size in
+``do_install`` will return true, and the file will be installed.
+
 Prioritizing Your Layer
 -----------------------
 
Signature · 1 line
2.17.1
author
#1 lore raw

PATCH 2/3 manuals: Rename the "Using .bbappend Files in Your Layer" section

To prepare to add another example bbappend, rename the current "Using .bbappend Files in Your Layer" section to "Appending Other Layers With Your Layer". Name the current example as "Overlaying a File Using Your Layer".

---
 documentation/dev-manual/common-tasks.rst        | 9 ++++++---
 documentation/kernel-dev/common.rst              | 4 ++--
 documentation/kernel-dev/faq.rst                 | 2 +-
 documentation/migration-guides/migration-1.4.rst | 2 +-
 4 files changed, 10 insertions(+), 7 deletions(-)
documentation/dev-manual/common-tasks.rst +6 -3
index 2d8ef96e2600..f15e72887c04 100644
@@ -443,8 +443,8 @@ file. During the processing of each ``conf/layer.conf`` file, BitBake
 adds the recipes, classes and configurations contained within the
 particular layer to the source directory.
 
-Using .bbappend Files in Your Layer
------------------------------------
+Appending Other Layers With Your Layer
+--------------------------------------
 
 A recipe that appends Metadata to another recipe is called a BitBake
 append file. A BitBake append file uses the ``.bbappend`` file type
@@ -474,6 +474,9 @@ does not have a corresponding recipe with a matching name. See the
 :term:`BB_DANGLINGAPPENDS_WARNONLY`
 variable for information on how to handle this error.
 
+Overlaying a File Using Your Layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 As an example, consider the main formfactor recipe and a corresponding
 formfactor append file both from the :term:`Source Directory`.
 Here is the main
@@ -6091,7 +6094,7 @@ layer. The following steps provide some more detail:
 
    -  Add a ``psplash`` append file for a branded splash screen. For
       information on append files, see the
-      ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
+      ":ref:`dev-manual/common-tasks:appending other layers with your layer`"
       section.
 
    -  Add any other append files to make custom changes that are
documentation/kernel-dev/common.rst +2 -2
index a97140b0b904..e0bc375f8247 100644
@@ -425,7 +425,7 @@ home directory:
    The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
    enable the OpenEmbedded build system to find patch files. For more
    information on using append files, see the
-   ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
+   ":ref:`dev-manual/common-tasks:appending other layers with your layer`"
    section in the Yocto Project Development Tasks Manual.
 
 Modifying an Existing Recipe
@@ -1070,7 +1070,7 @@ Section.
    For more information on append files and patches, see the
    ":ref:`kernel-dev/common:creating the append file`" and
    ":ref:`kernel-dev/common:applying patches`" sections. You can also see the
-   ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
+   ":ref:`dev-manual/common-tasks:appending other layers with your layer`"
    section in the Yocto Project Development Tasks Manual.
 
    .. note::
documentation/kernel-dev/faq.rst +1 -1
index f0a7af37bb0b..2497145f26aa 100644
@@ -38,7 +38,7 @@ The kernel image (e.g. ``vmlinuz``) is provided by the
 specify whether or not the kernel image is installed in the generated
 root filesystem, override ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base`` to include or not
 include "kernel-image". See the
-":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
+":ref:`dev-manual/common-tasks:appending other layers with your layer`"
 section in the
 Yocto Project Development Tasks Manual for information on how to use an
 append file to override metadata.
documentation/migration-guides/migration-1.4.rst +1 -1
index 3f980915cf0c..81e8ccd03ba3 100644
@@ -83,7 +83,7 @@ create an append file for the ``init-ifupdown`` recipe instead, which
 you can find in the :term:`Source Directory` at
 ``meta/recipes-core/init-ifupdown``. For information on how to use
 append files, see the
-":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
+":ref:`dev-manual/common-tasks:appending other layers with your layer`"
 section in the Yocto Project Development Tasks Manual.
 
 .. _migration-1.4-remote-debugging:
Signature · 1 line
2.17.1
Reviewed-by on v1 2/3
#2 lore raw

Re: [docs] [PATCH 2/3] manuals: Rename the "Using .bbappend Files in Your Layer" section

Hi Tom,

Quoted 17 lines · Tom Rini

.bbappend Files in Your Layer" section to "Appending Other Layers With Your Layer". Name the current example as "Overlaying a File Using Your Layer".

---
 documentation/dev-manual/common-tasks.rst        | 9 ++++++---
 documentation/kernel-dev/common.rst              | 4 ++--
 documentation/kernel-dev/faq.rst                 | 2 +-
 documentation/migration-guides/migration-1.4.rst | 2 +-
 4 files changed, 10 insertions(+), 7 deletions(-)
documentation/dev-manual/common-tasks.rst +0 -0
index 2d8ef96e2600..f15e72887c04 100644

documentation/dev-manual/common-tasks.rst file. During the processing of each ``conf/layer.conf`` file, BitBake · line 448

Quoted 8 lines
documentation/dev-manual/common-tasks.rst +2 -2
@@ -443,8 +443,8 @@ file. During the processing of each ``conf/layer.conf`` file, BitBake
 adds the recipes, classes and configurations contained within the
 particular layer to the source directory.
 
-Using .bbappend Files in Your Layer
------------------------------------
+Appending Other Layers With Your Layer
+--------------------------------------
 

I could suggest:

Appending Other Layers Metadata With Your Layer

But I think it's fine either way.

Thanks,
Quentin

Reviewed-by
#3 lore raw

Re: [docs] [PATCH 2/3] manuals: Rename the "Using .bbappend Files in Your Layer" section

Hi Tom,

Thanks for the patch!

Quoted 30 lines · Quentin Schulz

Hi Tom,

Quoted 17 lines · Tom Rini

.bbappend Files in Your Layer" section to "Appending Other Layers With Your Layer". Name the current example as "Overlaying a File Using Your Layer".

---
 documentation/dev-manual/common-tasks.rst        | 9 ++++++---
 documentation/kernel-dev/common.rst              | 4 ++--
 documentation/kernel-dev/faq.rst                 | 2 +-
 documentation/migration-guides/migration-1.4.rst | 2 +-
 4 files changed, 10 insertions(+), 7 deletions(-)
documentation/dev-manual/common-tasks.rst +0 -0
index 2d8ef96e2600..f15e72887c04 100644

documentation/dev-manual/common-tasks.rst file. During the processing of each ``conf/layer.conf`` file, BitBake · line 448

Quoted 8 lines
documentation/dev-manual/common-tasks.rst +2 -2
@@ -443,8 +443,8 @@ file. During the processing of each ``conf/layer.conf`` file, BitBake
 adds the recipes, classes and configurations contained within the
 particular layer to the source directory.
 
-Using .bbappend Files in Your Layer
------------------------------------
+Appending Other Layers With Your Layer
+--------------------------------------
 

I could suggest:

Quoted 5 lines

Appending Other Layers Metadata With Your Layer

But I think it's fine either way.

I'm taking your proposal, Quentin, thanks!

and merged into "master-next".

Cheers,
Michael.

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

PATCH 3/3 common-tasks: Add an example of using bbappends to add a file

In reply to Tom Rini

Use the xserver-xf86-config_%.bbappend from meta-raspberrypi to provide an example of having a bbappend file add files to an existing recipe.

---
 documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
 1 file changed, 61 insertions(+)
documentation/dev-manual/common-tasks.rst +61 -0
index f15e72887c04..87abef9ad52f 100644
@@ -554,6 +554,67 @@ The end result of this ``.bbappend`` file is that on a Raspberry Pi, where
 used during ``do_fetch`` and the test for a non-zero file size in
 ``do_install`` will return true, and the file will be installed.
 
+Installing Additional Files Using Your Layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As another example, consider the main xserver-xf86-config recipe and a corresponding
+xserver-xf86-config append file both from the :term:`Source Directory`.
+Here is the main
+xserver-xf86-config recipe, which is named ``xserver-xf86-config_0.1.bb`` and located in
+the "meta" layer at ``meta/recipes-graphics/xorg-xserver``::
+
+   SUMMARY = "X.Org X server configuration file"
+   HOMEPAGE = "http://www.x.org"
+   SECTION = "x11/base"
+   LICENSE = "MIT-X"
+   LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+   PR = "r33"
+
+   SRC_URI = "file://xorg.conf"
+
+   S = "${WORKDIR}"
+
+   CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf"
+
+   PACKAGE_ARCH = "${MACHINE_ARCH}"
+   ALLOW_EMPTY:${PN} = "1"
+
+   do_install () {
+	if test -s ${WORKDIR}/xorg.conf; then
+		install -d ${D}/${sysconfdir}/X11
+		install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/
+	fi
+   }
+
+Following is the append file, which is named ``xserver-xf86-config_%.bbappend``
+and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The
+file is in the layer at ``recipes-graphics/xorg-xserver``::
+
+   FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
+
+   SRC_URI:append:rpi = " \
+       file://xorg.conf.d/98-pitft.conf \
+       file://xorg.conf.d/99-calibration.conf \
+   "
+   do_install:append:rpi () {
+       PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}"
+       if [ "${PITFT}" = "1" ]; then
+           install -d ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+       fi
+   }
+
+   FILES:${PN}:rpi += "${sysconfdir}/X11/xorg.conf ${sysconfdir}/X11/xorg.conf.d/*"
+
+Building off of the previous example, we once again are setting the
+:term:`FILESEXTRAPATHS` variable.  In this case we are also usine the
+:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in
+the list of :term:`OVERRIDES`.  The ``do_install`` task will then perform a
+check for an additional :term:`MACHINE_FEATURES` that if set will cause these
+additional files to be installed.  These additional files are listed in
+:term:`FILES` so that they will be packaged.
+
 Prioritizing Your Layer
 -----------------------
 
Signature · 1 line
2.17.1
#5 lore raw

Re: [docs] [PATCH 3/3] common-tasks: Add an example of using bbappends to add a file

Hi Tom,

Quoted 13 lines · Tom Rini

Use the xserver-xf86-config_%.bbappend from meta-raspberrypi to provide an example of having a bbappend file add files to an existing recipe.

---
 documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
 1 file changed, 61 insertions(+)
documentation/dev-manual/common-tasks.rst +0 -0
index f15e72887c04..87abef9ad52f 100644

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 560

Quoted 7 lines
documentation/dev-manual/common-tasks.rst +4 -0
@@ -554,6 +554,67 @@ The end result of this ``.bbappend`` file is that on a Raspberry Pi, where
 used during ``do_fetch`` and the test for a non-zero file size in
 ``do_install`` will return true, and the file will be installed.
 
+Installing Additional Files Using Your Layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As another example, consider the main xserver-xf86-config recipe and a corresponding

s/xserver-xf86-config/``xserver-xf86-config``/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 561

Quoted 1 line
documentation/dev-manual/common-tasks.rst +1 -0
+xserver-xf86-config append file both from the :term:`Source Directory`.

s/xserver-xf86-config/``xserver-xf86-config``/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 563

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+Here is the main
+xserver-xf86-config recipe, which is named ``xserver-xf86-config_0.1.bb`` and located in

s/xserver-xf86-config/``xserver-xf86-config``/

Quoted 36 lines
documentation/dev-manual/common-tasks.rst +36 -0
+the "meta" layer at ``meta/recipes-graphics/xorg-xserver``::
+
+   SUMMARY = "X.Org X server configuration file"
+   HOMEPAGE = "https://urldefense.proofpoint.com/v2/url?u=http-3A__www.x.org&d=DwIBAg&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=XXgYJ9tKXtc_aBqPPa-9XgJe1nXbWkl8dkudu8oFs_Y&s=0zjLRjQF3x_Fv-B-gOPuwnCc_TfOzMJ50SOySYZMbys&e= "
+   SECTION = "x11/base"
+   LICENSE = "MIT-X"
+   LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+   PR = "r33"
+
+   SRC_URI = "file://xorg.conf"
+
+   S = "${WORKDIR}"
+
+   CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf"
+
+   PACKAGE_ARCH = "${MACHINE_ARCH}"
+   ALLOW_EMPTY:${PN} = "1"
+
+   do_install () {
+	if test -s ${WORKDIR}/xorg.conf; then
+		install -d ${D}/${sysconfdir}/X11
+		install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/
+	fi
+   }
+
+Following is the append file, which is named ``xserver-xf86-config_%.bbappend``
+and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The
+file is in the layer at ``recipes-graphics/xorg-xserver``::
+
+   FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
+
+   SRC_URI:append:rpi = " \
+       file://xorg.conf.d/98-pitft.conf \
+       file://xorg.conf.d/99-calibration.conf \
+   "
+   do_install:append:rpi () {

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 609

Quoted 10 lines
documentation/dev-manual/common-tasks.rst +10 -0
+       PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}"
+       if [ "${PITFT}" = "1" ]; then
+           install -d ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+       fi
+   }
+
+   FILES:${PN}:rpi += "${sysconfdir}/X11/xorg.conf ${sysconfdir}/X11/xorg.conf.d/*"
+

Highly suspect this is wrong. It should be FILES:${PN}:append:rpi instead, otherwise it's completely overriding FILES:${PN} for rpi (even if the operator that is following is +=).

I guess you took this from the bbappend within meta-raspberrypi so it would probably need fixing there.

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 611

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+Building off of the previous example, we once again are setting the
+:term:`FILESEXTRAPATHS` variable.  In this case we are also usine the

s/usine the/using/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 613

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in
+the list of :term:`OVERRIDES`.  The ``do_install`` task will then perform a

s/``do_install``/:ref:ref-tasks-install/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 614

Quoted 1 line
documentation/dev-manual/common-tasks.rst +1 -0
+check for an additional :term:`MACHINE_FEATURES` that if set will cause these

"The do_install task will be extended, for ``rpi`` only, to perform..." instead?

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 617

Quoted 3 lines
documentation/dev-manual/common-tasks.rst +3 -0
+additional files to be installed.  These additional files are listed in
+:term:`FILES` so that they will be packaged.
+

Same, it's rpi-specific here.

Thanks,
Quentin

#6 lore raw

Re: [docs] [PATCH 3/3] common-tasks: Add an example of using bbappends to add a file

Tom, thanks for the patch.
Quentin, thanks for the review.

Quoted 93 lines · Quentin Schulz

Hi Tom,

Quoted 13 lines · Tom Rini

Use the xserver-xf86-config_%.bbappend from meta-raspberrypi to provide an example of having a bbappend file add files to an existing recipe.

---
 documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
 1 file changed, 61 insertions(+)
documentation/dev-manual/common-tasks.rst +0 -0
index f15e72887c04..87abef9ad52f 100644

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 560

Quoted 7 lines
documentation/dev-manual/common-tasks.rst +4 -0
@@ -554,6 +554,67 @@ The end result of this ``.bbappend`` file is that on a Raspberry Pi, where
 used during ``do_fetch`` and the test for a non-zero file size in
 ``do_install`` will return true, and the file will be installed.
 
+Installing Additional Files Using Your Layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As another example, consider the main xserver-xf86-config recipe and a corresponding

s/xserver-xf86-config/``xserver-xf86-config``/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 561

Quoted 1 line
documentation/dev-manual/common-tasks.rst +1 -0
+xserver-xf86-config append file both from the :term:`Source Directory`.

s/xserver-xf86-config/``xserver-xf86-config``/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 563

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+Here is the main
+xserver-xf86-config recipe, which is named ``xserver-xf86-config_0.1.bb`` and located in

s/xserver-xf86-config/``xserver-xf86-config``/

Quoted 36 lines
documentation/dev-manual/common-tasks.rst +36 -0
+the "meta" layer at ``meta/recipes-graphics/xorg-xserver``::
+
+   SUMMARY = "X.Org X server configuration file"
+   HOMEPAGE = "https://urldefense.proofpoint.com/v2/url?u=http-3A__www.x.org&d=DwIBAg&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=XXgYJ9tKXtc_aBqPPa-9XgJe1nXbWkl8dkudu8oFs_Y&s=0zjLRjQF3x_Fv-B-gOPuwnCc_TfOzMJ50SOySYZMbys&e= "
+   SECTION = "x11/base"
+   LICENSE = "MIT-X"
+   LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+   PR = "r33"
+
+   SRC_URI = "file://xorg.conf"
+
+   S = "${WORKDIR}"
+
+   CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf"
+
+   PACKAGE_ARCH = "${MACHINE_ARCH}"
+   ALLOW_EMPTY:${PN} = "1"
+
+   do_install () {
+	if test -s ${WORKDIR}/xorg.conf; then
+		install -d ${D}/${sysconfdir}/X11
+		install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/
+	fi
+   }
+
+Following is the append file, which is named ``xserver-xf86-config_%.bbappend``
+and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The
+file is in the layer at ``recipes-graphics/xorg-xserver``::
+
+   FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
+
+   SRC_URI:append:rpi = " \
+       file://xorg.conf.d/98-pitft.conf \
+       file://xorg.conf.d/99-calibration.conf \
+   "
+   do_install:append:rpi () {

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 609

Quoted 10 lines
documentation/dev-manual/common-tasks.rst +10 -0
+       PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}"
+       if [ "${PITFT}" = "1" ]; then
+           install -d ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+       fi
+   }
+
+   FILES:${PN}:rpi += "${sysconfdir}/X11/xorg.conf ${sysconfdir}/X11/xorg.conf.d/*"
+

Highly suspect this is wrong. It should be FILES:${PN}:append:rpi instead, otherwise it's completely overriding FILES:${PN} for rpi (even if the operator that is following is +=).

I guess you took this from the bbappend within meta-raspberrypi so it would probably need fixing there.

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 611

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+Building off of the previous example, we once again are setting the
+:term:`FILESEXTRAPATHS` variable.  In this case we are also usine the

s/usine the/using/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 613

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in
+the list of :term:`OVERRIDES`.  The ``do_install`` task will then perform a

s/``do_install``/:ref:ref-tasks-install/

Quoted 7 lines

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 614

Quoted 1 line
documentation/dev-manual/common-tasks.rst +1 -0
+check for an additional :term:`MACHINE_FEATURES` that if set will cause these

"The do_install task will be extended, for ``rpi`` only, to perform..." instead?

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 617

Quoted 3 lines
documentation/dev-manual/common-tasks.rst +3 -0
+additional files to be installed.  These additional files are listed in
+:term:`FILES` so that they will be packaged.
+

Same, it's rpi-specific here.

Tom, it's probably better if you prepare a V2 by yourself. If you can prepare it against "master-next", that will even be easier for me, as the first two patches were merged there.

Thanks again,
Michael.

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

Re: [docs] [PATCH 3/3] common-tasks: Add an example of using bbappends to add a file

Quoted 35 lines · Michael Opdenacker

Tom, thanks for the patch.
Quentin, thanks for the review.

Quoted 31 lines · Quentin Schulz

Hi Tom,

Quoted 13 lines · Tom Rini

Use the xserver-xf86-config_%.bbappend from meta-raspberrypi to provide an example of having a bbappend file add files to an existing recipe.

---
 documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
 1 file changed, 61 insertions(+)
documentation/dev-manual/common-tasks.rst +0 -0
index f15e72887c04..87abef9ad52f 100644

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 560

Quoted 7 lines
documentation/dev-manual/common-tasks.rst +4 -0
@@ -554,6 +554,67 @@ The end result of this ``.bbappend`` file is that on a Raspberry Pi, where
 used during ``do_fetch`` and the test for a non-zero file size in
 ``do_install`` will return true, and the file will be installed.
 
+Installing Additional Files Using Your Layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As another example, consider the main xserver-xf86-config recipe and a corresponding

s/xserver-xf86-config/``xserver-xf86-config``/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 561

Quoted 1 line
documentation/dev-manual/common-tasks.rst +1 -0
+xserver-xf86-config append file both from the :term:`Source Directory`.

s/xserver-xf86-config/``xserver-xf86-config``/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 563

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+Here is the main
+xserver-xf86-config recipe, which is named ``xserver-xf86-config_0.1.bb`` and located in

s/xserver-xf86-config/``xserver-xf86-config``/

Whoops.

Quoted 41 lines
Quoted 41 lines
Quoted 41 lines
documentation/dev-manual/common-tasks.rst +41 -0
+the "meta" layer at ``meta/recipes-graphics/xorg-xserver``::
+
+   SUMMARY = "X.Org X server configuration file"
+   HOMEPAGE = "https://urldefense.proofpoint.com/v2/url?u=http-3A__www.x.org&d=DwIBAg&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=XXgYJ9tKXtc_aBqPPa-9XgJe1nXbWkl8dkudu8oFs_Y&s=0zjLRjQF3x_Fv-B-gOPuwnCc_TfOzMJ50SOySYZMbys&e= "
+   SECTION = "x11/base"
+   LICENSE = "MIT-X"
+   LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+   PR = "r33"
+
+   SRC_URI = "file://xorg.conf"
+
+   S = "${WORKDIR}"
+
+   CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf"
+
+   PACKAGE_ARCH = "${MACHINE_ARCH}"
+   ALLOW_EMPTY:${PN} = "1"
+
+   do_install () {
+	if test -s ${WORKDIR}/xorg.conf; then
+		install -d ${D}/${sysconfdir}/X11
+		install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/
+	fi
+   }
+
+Following is the append file, which is named ``xserver-xf86-config_%.bbappend``
+and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The
+file is in the layer at ``recipes-graphics/xorg-xserver``::
+
+   FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
+
+   SRC_URI:append:rpi = " \
+       file://xorg.conf.d/98-pitft.conf \
+       file://xorg.conf.d/99-calibration.conf \
+   "
+   do_install:append:rpi () {
+       PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}"
+       if [ "${PITFT}" = "1" ]; then
+           install -d ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
Quoted 8 lines
Quoted 8 lines

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 609

Quoted 5 lines
documentation/dev-manual/common-tasks.rst +5 -0
+       fi
+   }
+
+   FILES:${PN}:rpi += "${sysconfdir}/X11/xorg.conf ${sysconfdir}/X11/xorg.conf.d/*"
+

Highly suspect this is wrong. It should be FILES:${PN}:append:rpi instead, otherwise it's completely overriding FILES:${PN} for rpi (even if the operator that is following is +=).

Yeah, it does.

Quoted 2 lines
Quoted 2 lines

I guess you took this from the bbappend within meta-raspberrypi so it would probably need fixing there.

Yup, copy/paste/indent of the current upstream recipe.

Quoted 8 lines
Quoted 8 lines

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 611

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+Building off of the previous example, we once again are setting the
+:term:`FILESEXTRAPATHS` variable.  In this case we are also usine the

s/usine the/using/

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 613

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in
+the list of :term:`OVERRIDES`.  The ``do_install`` task will then perform a

s/``do_install``/:ref:ref-tasks-install/

Quoted 7 lines
Quoted 7 lines

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 614

Quoted 1 line
documentation/dev-manual/common-tasks.rst +1 -0
+check for an additional :term:`MACHINE_FEATURES` that if set will cause these

"The do_install task will be extended, for ``rpi`` only, to perform..." instead?

documentation/dev-manual/common-tasks.rst The end result of this ``.bbappend`` file is that on a Raspberry Pi, where · line 617

Quoted 3 lines
documentation/dev-manual/common-tasks.rst +3 -0
+additional files to be installed.  These additional files are listed in
+:term:`FILES` so that they will be packaged.
+

Same, it's rpi-specific here.

What I was trying to convey here is that in the meta-raspberrypi layer, all of the machines add "rpi" to the OVERRIDE list, for a common one. At the high level, I was trying to find a simple example of using an append to add files, but also didn't want to add another example layer and it seems like meta-raspberrypi is what's used everywhere else. I'll see about re-wording things a bit more to be clearer / more consistent.

Quoted 3 lines

Tom, it's probably better if you prepare a V2 by yourself. If you can prepare it against "master-next", that will even be easier for me, as the first two patches were merged there.

Agreed. First up, I'm going to need to go and get meta-raspberrypi fixed for this example, or switch to the u-boot example there, which I avoided since it's doing two things.

Thanks for the review and feedback.

Signature · 1 line
Tom
#8 lore raw

Re: [docs] [PATCH 3/3] common-tasks: Add an example of using bbappends to add a file

In reply to Quentin Schulz
Quoted 3 lines · Quentin Schulz

Hi Tom,

On Thu, Aug 12, 2021 at 12:10:27PM -0400, Tom Rini wrote:

[snip]

Quoted 6 lines

Review

Quoted 2 lines
(quoted diff) +2 -0
+   FILES:${PN}:rpi += "${sysconfdir}/X11/xorg.conf ${sysconfdir}/X11/xorg.conf.d/*"
+

Highly suspect this is wrong. It should be FILES:${PN}:append:rpi instead, otherwise it's completely overriding FILES:${PN} for rpi (even if the operator that is following is +=).

Right, so, this is not fatally wrong, re-reading the main recipe and building it. But it's also not a best practices example, so not what should be put in to the documentation. I'll go and get meta-raspberrypi fixed to follow best practices and once that's merged I'll v2 this last part, along with the rest of the feedback.

Signature · 1 line
Tom
Reviewed-by on v1 1/3
#9 lore raw
In reply to Tom Rini

Hi Tom,

Quoted 13 lines · Tom Rini

Try and make it clearer what the final result of this bbappend example is.

---
 documentation/dev-manual/common-tasks.rst | 6 ++++++
 1 file changed, 6 insertions(+)
documentation/dev-manual/common-tasks.rst +0 -0
index 37077d72d451..2d8ef96e2600 100644

documentation/dev-manual/common-tasks.rst important as it ensures that items in the list remain colon-separated. · line 552

Quoted 8 lines
documentation/dev-manual/common-tasks.rst +5 -0
@@ -545,6 +545,12 @@ important as it ensures that items in the list remain colon-separated.
    allow to add build options (e.g. ``systemd``). For these cases, your
    append file would not even use the :term:`FILESEXTRAPATHS` statement.
 
+The end result of this ``.bbappend`` file is that on a Raspberry Pi, where
+``rpi`` will exist in the list of :term:`OVERRIDES`, the file
+``meta-raspberrypi/recipes-bsp/formfactor/formfactor/rpi/machconfig`` will be
+used during ``do_fetch`` and the test for a non-zero file size in
+``do_install`` will return true, and the file will be installed.

I agree that this text really helps to understand this section. I was confused otherwise.

... and merged into "master-next" for yocto-docs.

Thanks again,
Michael.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
Reviewed-by on v1 1/3
#10 lore raw
In reply to Tom Rini

Hi Tom,

Thanks for sending the patch :)

Quoted 12 lines · Tom Rini

is.

---
 documentation/dev-manual/common-tasks.rst | 6 ++++++
 1 file changed, 6 insertions(+)
documentation/dev-manual/common-tasks.rst +0 -0
index 37077d72d451..2d8ef96e2600 100644

documentation/dev-manual/common-tasks.rst important as it ensures that items in the list remain colon-separated. · line 551

Quoted 7 lines
documentation/dev-manual/common-tasks.rst +4 -0
@@ -545,6 +545,12 @@ important as it ensures that items in the list remain colon-separated.
    allow to add build options (e.g. ``systemd``). For these cases, your
    append file would not even use the :term:`FILESEXTRAPATHS` statement.
 
+The end result of this ``.bbappend`` file is that on a Raspberry Pi, where
+``rpi`` will exist in the list of :term:`OVERRIDES`, the file
+``meta-raspberrypi/recipes-bsp/formfactor/formfactor/rpi/machconfig`` will be
+used during ``do_fetch`` and the test for a non-zero file size in

s/``do_fetch``/:ref:ref-tasks-fetch/

documentation/dev-manual/common-tasks.rst important as it ensures that items in the list remain colon-separated. · line 553

Quoted 2 lines
documentation/dev-manual/common-tasks.rst +2 -0
+``do_install`` will return true, and the file will be installed.
+

s/``do_install``/:ref:ref-tasks-install/

Otherwise,

Thanks!
Quentin

#11 lore raw

Hi Quentin,

Thanks for the review!

Quoted 5 lines · Quentin Schulz

s/``do_fetch``/:ref:ref-tasks-fetch/

Quoted 2 lines

+``do_install`` will return true, and the file will be installed. +

s/``do_install``/:ref:ref-tasks-install/

Good catch! I see other places in the documentation where this could be done. I'll add it to my TODO list, but be my guest if you have time.

I updated the commit in master-next.
Cheers,
Michael.

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

Hi Quentin,

Thanks for the review!

Quoted 2 lines · Quentin Schulz

s/``do_fetch``/:ref:ref-tasks-fetch/

Quoted 8 lines
Quoted 3 lines
Quoted 2 lines

+``do_install`` will return true, and the file will be installed. +

s/``do_install``/:ref:ref-tasks-install/

Good catch! I see other places in the documentation where this could be done. I'll add it to my TODO list, but be my guest if you have time.

You can open a Bugzilla entry for this so we don't forget :)

We probably need to do the same for classes, tasks and variables. I saw I missed a few variables that aren't highlighted with tick quotes in the docs, which explains why they were missed by the script :)

Cheers,
Quentin

#13 lore raw
Quoted 5 lines · Quentin Schulz

You can open a Bugzilla entry for this so we don't forget :)

We probably need to do the same for classes, tasks and variables. I saw I missed a few variables that aren't highlighted with tick quotes in the docs, which explains why they were missed by the script :)

Good idea. Anyway, I'm one of the people with the greatest number of bugs. Here it is: https://bugzilla.yoctoproject.org/show_bug.cgi?id=14508

Thanks again
Michael.

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