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

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

[Tom Rini]

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

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 documentation/dev-manual/common-tasks.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 37077d72d451..2d8ef96e2600 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -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
 -----------------------
 
-- 
2.17.1

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

[Tom Rini]

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

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 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(-)

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 2d8ef96e2600..f15e72887c04 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -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
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index a97140b0b904..e0bc375f8247 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -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::
diff --git a/documentation/kernel-dev/faq.rst b/documentation/kernel-dev/faq.rst
index f0a7af37bb0b..2497145f26aa 100644
--- a/documentation/kernel-dev/faq.rst
+++ b/documentation/kernel-dev/faq.rst
@@ -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.
diff --git a/documentation/migration-guides/migration-1.4.rst b/documentation/migration-guides/migration-1.4.rst
index 3f980915cf0c..81e8ccd03ba3 100644
--- a/documentation/migration-guides/migration-1.4.rst
+++ b/documentation/migration-guides/migration-1.4.rst
@@ -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:
-- 
2.17.1

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

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

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index f15e72887c04..87abef9ad52f 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -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
 -----------------------
 
-- 
2.17.1

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

[Michael Opdenacker]

Hi Tom,

On 8/12/21 6:10 PM, Tom Rini wrote:
> Try and make it clearer what the final result of this bbappend example
> is.
>
> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 37077d72d451..2d8ef96e2600 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -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.

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

Thanks again,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Quentin Schulz]

Hi Tom,

Thanks for sending the patch :)


On Thu, Aug 12, 2021 at 12:10:25PM -0400, Tom Rini wrote:
> is.
> 
> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 37077d72d451..2d8ef96e2600 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -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`/

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

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

Otherwise,
Reviewed-by: Quentin Schulz <foss@0leil.net>

Thanks!
Quentin

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

[Quentin Schulz]

Hi Tom,

On Thu, Aug 12, 2021 at 12:10:27PM -0400, Tom Rini wrote:
> Use the xserver-xf86-config_%.bbappend from meta-raspberrypi to provide
> an example of having a bbappend file add files to an existing recipe.
> 
> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
>  1 file changed, 61 insertions(+)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index f15e72887c04..87abef9ad52f 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -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``/

> +xserver-xf86-config append file both from the :term:`Source Directory`.

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

> +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``/

> +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/
> +       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.

> +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/

> +: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`/

> +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?

> +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

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

[Michael Opdenacker]

Hi Quentin,

Thanks for the review!

On 8/13/21 10:21 AM, Quentin Schulz wrote:

> s/``do_fetch``/:ref:`ref-tasks-fetch`/
>
>> +``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.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Quentin Schulz]

Hi Tom,

On Thu, Aug 12, 2021 at 12:10:26PM -0400, Tom Rini wrote:
> .bbappend Files in Your Layer" section to "Appending Other Layers With
> Your Layer".  Name the current example as "Overlaying a File Using Your
> Layer".
> 
> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
>  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(-)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 2d8ef96e2600..f15e72887c04 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -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.

Reviewed-by: Quentin Schulz <foss@0leil.net>

Thanks,
Quentin

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

[Quentin Schulz]

On Fri, Aug 13, 2021 at 10:28:39AM +0200, Michael Opdenacker wrote:
> Hi Quentin,
> 
> Thanks for the review!
> 
> On 8/13/21 10:21 AM, Quentin Schulz wrote:
> 
> > s/``do_fetch``/:ref:`ref-tasks-fetch`/
> >
> >> +``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

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

[Michael Opdenacker]

On 8/13/21 10:31 AM, Quentin Schulz wrote:
> 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.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Michael Opdenacker]

Hi Tom,

Thanks for the patch!

On 8/13/21 10:29 AM, Quentin Schulz wrote:
> Hi Tom,
>
> On Thu, Aug 12, 2021 at 12:10:26PM -0400, Tom Rini wrote:
>> .bbappend Files in Your Layer" section to "Appending Other Layers With
>> Your Layer".  Name the current example as "Overlaying a File Using Your
>> Layer".
>>
>> Signed-off-by: Tom Rini <trini@konsulko.com>
>> ---
>>  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(-)
>>
>> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
>> index 2d8ef96e2600..f15e72887c04 100644
>> --- a/documentation/dev-manual/common-tasks.rst
>> +++ b/documentation/dev-manual/common-tasks.rst
>> @@ -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.
>
> Reviewed-by: Quentin Schulz <foss@0leil.net>

I'm taking your proposal, Quentin, thanks!

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

Cheers,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Michael Opdenacker]

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

On 8/13/21 10:27 AM, Quentin Schulz wrote:
> Hi Tom,
>
> On Thu, Aug 12, 2021 at 12:10:27PM -0400, Tom Rini wrote:
>> Use the xserver-xf86-config_%.bbappend from meta-raspberrypi to provide
>> an example of having a bbappend file add files to an existing recipe.
>>
>> Signed-off-by: Tom Rini <trini@konsulko.com>
>> ---
>>  documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
>>  1 file changed, 61 insertions(+)
>>
>> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
>> index f15e72887c04..87abef9ad52f 100644
>> --- a/documentation/dev-manual/common-tasks.rst
>> +++ b/documentation/dev-manual/common-tasks.rst
>> @@ -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``/
>
>> +xserver-xf86-config append file both from the :term:`Source Directory`.
> s/xserver-xf86-config/``xserver-xf86-config``/
>
>> +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``/
>
>> +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/
>> +       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.
>
>> +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/
>
>> +: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`/
>
>> +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?
>
>> +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.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Tom Rini]

On Fri, Aug 13, 2021 at 11:15:13AM +0200, Michael Opdenacker wrote:
> Tom, thanks for the patch.
> Quentin, thanks for the review.
> 
> On 8/13/21 10:27 AM, Quentin Schulz wrote:
> > Hi Tom,
> >
> > On Thu, Aug 12, 2021 at 12:10:27PM -0400, Tom Rini wrote:
> >> Use the xserver-xf86-config_%.bbappend from meta-raspberrypi to provide
> >> an example of having a bbappend file add files to an existing recipe.
> >>
> >> Signed-off-by: Tom Rini <trini@konsulko.com>
> >> ---
> >>  documentation/dev-manual/common-tasks.rst | 61 +++++++++++++++++++++++
> >>  1 file changed, 61 insertions(+)
> >>
> >> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> >> index f15e72887c04..87abef9ad52f 100644
> >> --- a/documentation/dev-manual/common-tasks.rst
> >> +++ b/documentation/dev-manual/common-tasks.rst
> >> @@ -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``/
> >
> >> +xserver-xf86-config append file both from the :term:`Source Directory`.
> > s/xserver-xf86-config/``xserver-xf86-config``/
> >
> >> +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.

> >> +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/
> >> +       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.

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

> >> +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/
> >
> >> +: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`/
> >
> >> +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?
> >
> >> +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.

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

-- 
Tom

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

[Tom Rini]

On Fri, Aug 13, 2021 at 10:27:40AM +0200, Quentin Schulz wrote:
> Hi Tom,
> 
> On Thu, Aug 12, 2021 at 12:10:27PM -0400, Tom Rini wrote:
[snip]
> > +   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.

-- 
Tom