[PATCH v2 0/2] Document how to provide configuration from layer.conf

[PATCH v2 0/2] Document how to provide configuration from layer.conf

[Antonin Godard]

This series documents how to provide configurations from layer.conf, be
it unconditionally or conditionally. I wanted to reference a file in
bitbake, so I added the :bitbake_git: new term for that.

This is a attempt at closing
https://bugzilla.yoctoproject.org/show_bug.cgi?id=12688.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v2:
- Create an `.. attention::` block to tell users _not_ to set
  unconditional confs from layer.conf.
- Fix typos reported by Quentin (thanks!)
- Add "Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>" on first
  commit (thanks!).
- Simplify "your layer is part of BBLAYERS" 🡒 "your layer is part of the
  build".
- Fix code blocks spacing (three spaces).
- Link to v1: https://lore.kernel.org/r/20241030-layer-confs-v1-0-0f7dcf460e27@bootlin.com

---
Antonin Godard (2):
      conf.py: add a bitbake_git extlink
      dev-manual: document how to provide confs from layer.conf

 documentation/conf.py               |  1 +
 documentation/dev-manual/layers.rst | 86 +++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
---
base-commit: 13caec1386708d8609dff5f42956d2329a074f37
change-id: 20241030-layer-confs-54c26ece97d3

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

[PATCH v2 1/2] conf.py: add a bitbake_git extlink

[Antonin Godard]

To make references to the bitbake repo, add an extlink for it and use it
in the docs with ":bitbake_git:`lib/bb/utils.py </tree/lib/bb/utils.py>`".

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/documentation/conf.py b/documentation/conf.py
index c7dd4e03fc0e99176a0fa2f74fda58efaf0af9b2..b0e7c91eb5d8e4e855c0ca46351586cdf237fcb3 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -90,6 +90,7 @@ rst_prolog = """
 
 # external links and substitutions
 extlinks = {
+    'bitbake_git': ('https://git.openembedded.org/bitbake%s', None),
     'cve_mitre': ('https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s', 'CVE-%s'),
     'cve_nist': ('https://nvd.nist.gov/vuln/detail/CVE-%s', 'CVE-%s'),
     'yocto_home': ('https://www.yoctoproject.org%s', None),

-- 
2.46.1

[PATCH v2 2/2] dev-manual: document how to provide confs from layer.conf

[Antonin Godard]

Add a section on providing global level configuration from the
layer.conf file. Since this file is parsed at an earlier stage in the
parsing process, it's not possible to combine bb.utils.contains and
{DISTRO,MACHINE}_FEATURES to conditionally set some configurations.

This patch documents:

- First that this file can be used for providing such configuration.
- Then demonstrate how to conditionally provide them, using a technique
  that is currently used in meta-virtualization
  (https://git.yoctoproject.org/meta-virtualization/tree/conf/layer.conf#n50).

Fixes [YOCTO #12688].

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/layers.rst | 86 +++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index 91889bd0ae391c7b6e62068778ae5c180c840762..e449fd43ad86c9a027e317e49b6e2f2f340a08d4 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -644,6 +644,92 @@ variable and append the layer's root name::
    order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake
    might address this.
 
+Providing Global-level Configurations With Your Layer
+-----------------------------------------------------
+
+When creating a layer, you may need to define configurations that should take
+effect globally in your build environment when the layer is part of the build.
+The ``layer.conf`` file is a :term:`configuration file` that affects the build
+system globally, so it is a candidate for this use-case.
+
+.. attention::
+
+   Providing unconditional global level configuration from the ``layer.conf``
+   file is *not* a good practice, and should be avoided. For this reason, the
+   section :ref:`Conditionally Provide Global-level Configurations With Your
+   Layer` below shows how the ``layer.conf`` file can be used to provide
+   configurations only if a certain condition is met.
+
+For example, if your layer provides a Linux kernel recipe named
+``linux-custom``, you may want to define the :term:`PREFERRED_PROVIDER` for the
+``linux-custom`` recipe::
+
+  PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
+
+This can be defined in the ``layer.conf`` file. If your layer is at the last
+position in the :term:`BBLAYERS` list, it will take precedence over previous
+``PREFERRED_PROVIDER_virtual/kernel`` assignments.
+
+Conditionally Provide Global-level Configurations With Your Layer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In some cases, your layer may provide global configurations only if some
+features it provides are enabled. Since the ``layer.conf`` file is parsed at an
+earlier stage in the parsing process, the :term:`DISTRO_FEATURES` and
+:term:`MACHINE_FEATURES` variables are not yet available to ``layer.conf``, and
+declaring conditional assignments based on these variables is not possible. The
+following technique shows a way to bypass this limitation by using the
+:term:`USER_CLASSES` variable and a conditional ``include`` command.
+
+In the following steps, let's assume our layer is named ``meta-mylayer`` and
+that this layer defines a custom :ref:`distro feature <ref-features-distro>`
+named ``mylayer-kernel``. We will set the :term:`PREFERRED_PROVIDER` variable
+for the kernel only if our feature ``mylayer-kernel`` is part of the
+:term:`DISTRO_FEATURES`:
+
+#. Create an include file in the directory
+   ``meta-mylayer/conf/distro/include/``, for example a file named
+   ``mylayer-kernel-provider.inc`` that sets the kernel provider to
+   ``linux-custom``::
+
+      PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
+
+#. Provide a path to this include file in your ``layer.conf``::
+
+      META_MYLAYER_KERNEL_PROVIDER_PATH = "${LAYERDIR}/conf/distro/include/mylayer-kernel-provider.inc"
+
+#. Create a new class in ``meta-mylayer/classes-global/``, for example a class
+   ``meta-mylayer-cfg.bbclass``. Make it conditionally include the file
+   ``mylayer-kernel-provider.inc`` defined above, using the variable
+   ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``::
+
+      require ${@bb.utils.contains('DISTRO_FEATURES', 'mylayer-kernel', '${META_MYLAYER_KERNEL_PROVIDER_PATH}', '', d)}
+
+   For details on the ``bb.utils.contains`` function, see its definition in
+   :bitbake_git:`lib/bb/utils.py </tree/lib/bb/utils.py>`.
+
+   .. note::
+
+      The ``require`` command is designed to not fail if the function
+      ``bb.utils.contains`` returns an empty string.
+
+#. Back to your ``layer.conf`` file, add the class ``meta-mylayer-cfg`` class to
+   the :term:`USER_CLASSES` variable::
+
+      USER_CLASSES:append = " meta-mylayer-cfg"
+
+   This will add the class ``meta-mylayer-cfg`` to the list of classes to
+   globally inherit. Since the ``include`` command is conditional in
+   ``meta-mylayer-cfg.bbclass``, even though inherited the class will have no
+   effect until the feature ``mylayer-kernel`` is enabled through
+   :term:`DISTRO_FEATURES`.
+
+This technique can also be used for :ref:`Machine features
+<ref-features-machine>` by following the same steps. Though not mandatory, it is
+recommended to put include files for :term:`DISTRO_FEATURES` in your layer's
+``conf/distro/include`` and the ones for :term:`MACHINE_FEATURES` in your
+layer's ``conf/machine/include``.
+
 Managing Layers
 ===============
 

-- 
2.46.1

Re: [PATCH v2 2/2] dev-manual: document how to provide confs from layer.conf

[Quentin Schulz]

Hi Antonin,

On 11/12/24 12:32 PM, Antonin Godard wrote:
> Add a section on providing global level configuration from the
> layer.conf file. Since this file is parsed at an earlier stage in the
> parsing process, it's not possible to combine bb.utils.contains and
> {DISTRO,MACHINE}_FEATURES to conditionally set some configurations.
> 
> This patch documents:
> 
> - First that this file can be used for providing such configuration.
> - Then demonstrate how to conditionally provide them, using a technique
>    that is currently used in meta-virtualization
>    (https://git.yoctoproject.org/meta-virtualization/tree/conf/layer.conf#n50).
> 
> Fixes [YOCTO #12688].
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/dev-manual/layers.rst | 86 +++++++++++++++++++++++++++++++++++++
>   1 file changed, 86 insertions(+)
> 
> diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
> index 91889bd0ae391c7b6e62068778ae5c180c840762..e449fd43ad86c9a027e317e49b6e2f2f340a08d4 100644
> --- a/documentation/dev-manual/layers.rst
> +++ b/documentation/dev-manual/layers.rst
> @@ -644,6 +644,92 @@ variable and append the layer's root name::
>      order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake
>      might address this.
>   
> +Providing Global-level Configurations With Your Layer
> +-----------------------------------------------------
> +
> +When creating a layer, you may need to define configurations that should take
> +effect globally in your build environment when the layer is part of the build.
> +The ``layer.conf`` file is a :term:`configuration file` that affects the build
> +system globally, so it is a candidate for this use-case.
> +
> +.. attention::

I would recommend using .. note or .. warning admonitions over other ones.

Right now it seems we have mainly .. note, but also a handful of .. 
admonition and a couple of .. tip so maybe that's not the best advice.

Anyway, why this suggestion?
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
"""
Admonitions: attention, caution, danger, error, hint, important, note, 
tip, warning and the generic admonition. (Most themes style only “note” 
and “warning” specially.)
"""

> +
> +   Providing unconditional global level configuration from the ``layer.conf``
> +   file is *not* a good practice, and should be avoided. For this reason, the
> +   section :ref:`Conditionally Provide Global-level Configurations With Your
> +   Layer` below shows how the ``layer.conf`` file can be used to provide
> +   configurations only if a certain condition is met.
> +
> +For example, if your layer provides a Linux kernel recipe named
> +``linux-custom``, you may want to define the :term:`PREFERRED_PROVIDER` for the
> +``linux-custom`` recipe::

"""
you may want to make :term:`PREFERRED_PROVIDER` for the Linux kernel 
virtual provider point to the ``linux-custom`` recipe.
"""

Because we are not setting PREFERRED_PROVIDER **for** the linux-custom 
recipe, we want to have virtual/kernel point at linux-custom (and it's 
set outside of that recipe). Moreover, the content of PREFERRED_PROVIDER 
for the linux-custom recipe isn't really of importance, it's more for 
other recipes depending on *a* kernel (e.g. kernel-modules, image 
recipes, etc...).

Not happy about the way I phrased it so maybe you can suggest something 
better here?

> +
> +  PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
> +
> +This can be defined in the ``layer.conf`` file. If your layer is at the last
> +position in the :term:`BBLAYERS` list, it will take precedence over previous
> +``PREFERRED_PROVIDER_virtual/kernel`` assignments.
> +

Mmmmm, except if the machine configuration file sets it too with "="?

> +Conditionally Provide Global-level Configurations With Your Layer
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In some cases, your layer may provide global configurations only if some
> +features it provides are enabled. Since the ``layer.conf`` file is parsed at an
> +earlier stage in the parsing process, the :term:`DISTRO_FEATURES` and
> +:term:`MACHINE_FEATURES` variables are not yet available to ``layer.conf``, and
> +declaring conditional assignments based on these variables is not possible. The
> +following technique shows a way to bypass this limitation by using the
> +:term:`USER_CLASSES` variable and a conditional ``include`` command.
> +
> +In the following steps, let's assume our layer is named ``meta-mylayer`` and
> +that this layer defines a custom :ref:`distro feature <ref-features-distro>`
> +named ``mylayer-kernel``. We will set the :term:`PREFERRED_PROVIDER` variable
> +for the kernel only if our feature ``mylayer-kernel`` is part of the
> +:term:`DISTRO_FEATURES`:
> +
> +#. Create an include file in the directory
> +   ``meta-mylayer/conf/distro/include/``, for example a file named
> +   ``mylayer-kernel-provider.inc`` that sets the kernel provider to
> +   ``linux-custom``::
> +
> +      PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
> +
> +#. Provide a path to this include file in your ``layer.conf``::
> +
> +      META_MYLAYER_KERNEL_PROVIDER_PATH = "${LAYERDIR}/conf/distro/include/mylayer-kernel-provider.inc"
> +
> +#. Create a new class in ``meta-mylayer/classes-global/``, for example a class
> +   ``meta-mylayer-cfg.bbclass``. Make it conditionally include the file
> +   ``mylayer-kernel-provider.inc`` defined above, using the variable
> +   ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``::
> +
> +      require ${@bb.utils.contains('DISTRO_FEATURES', 'mylayer-kernel', '${META_MYLAYER_KERNEL_PROVIDER_PATH}', '', d)}
> +
> +   For details on the ``bb.utils.contains`` function, see its definition in
> +   :bitbake_git:`lib/bb/utils.py </tree/lib/bb/utils.py>`.
> +
> +   .. note::
> +
> +      The ``require`` command is designed to not fail if the function
> +      ``bb.utils.contains`` returns an empty string.
> +
> +#. Back to your ``layer.conf`` file, add the class ``meta-mylayer-cfg`` class to
> +   the :term:`USER_CLASSES` variable::
> +
> +      USER_CLASSES:append = " meta-mylayer-cfg"
> +
> +   This will add the class ``meta-mylayer-cfg`` to the list of classes to
> +   globally inherit. Since the ``include`` command is conditional in
> +   ``meta-mylayer-cfg.bbclass``, even though inherited the class will have no
> +   effect until the feature ``mylayer-kernel`` is enabled through
> +   :term:`DISTRO_FEATURES`.
> +

Since you go to such great lengths to explain how to create the bbclass, 
require it conditionally, etc... Maybe provide how to "enable through 
DISTRO_FEATURES" so we have the complete picture?

> +This technique can also be used for :ref:`Machine features

s/for/with/ ?

Looks good otherwise :)

Cheers,
Quentin

Re: [PATCH v2 2/2] dev-manual: document how to provide confs from layer.conf

[Antonin Godard]

Hi Quentin,

On Wed Nov 13, 2024 at 10:58 AM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 11/12/24 12:32 PM, Antonin Godard wrote:
>> Add a section on providing global level configuration from the
>> layer.conf file. Since this file is parsed at an earlier stage in the
>> parsing process, it's not possible to combine bb.utils.contains and
>> {DISTRO,MACHINE}_FEATURES to conditionally set some configurations.
>> 
>> This patch documents:
>> 
>> - First that this file can be used for providing such configuration.
>> - Then demonstrate how to conditionally provide them, using a technique
>>    that is currently used in meta-virtualization
>>    (https://git.yoctoproject.org/meta-virtualization/tree/conf/layer.conf#n50).
>> 
>> Fixes [YOCTO #12688].
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/dev-manual/layers.rst | 86 +++++++++++++++++++++++++++++++++++++
>>   1 file changed, 86 insertions(+)
>> 
>> diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
>> index 91889bd0ae391c7b6e62068778ae5c180c840762..e449fd43ad86c9a027e317e49b6e2f2f340a08d4 100644
>> --- a/documentation/dev-manual/layers.rst
>> +++ b/documentation/dev-manual/layers.rst
>> @@ -644,6 +644,92 @@ variable and append the layer's root name::
>>      order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake
>>      might address this.
>>   
>> +Providing Global-level Configurations With Your Layer
>> +-----------------------------------------------------
>> +
>> +When creating a layer, you may need to define configurations that should take
>> +effect globally in your build environment when the layer is part of the build.
>> +The ``layer.conf`` file is a :term:`configuration file` that affects the build
>> +system globally, so it is a candidate for this use-case.
>> +
>> +.. attention::
>
> I would recommend using .. note or .. warning admonitions over other ones.
>
> Right now it seems we have mainly .. note, but also a handful of .. 
> admonition and a couple of .. tip so maybe that's not the best advice.
>
> Anyway, why this suggestion?
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
> """
> Admonitions: attention, caution, danger, error, hint, important, note, 
> tip, warning and the generic admonition. (Most themes style only “note” 
> and “warning” specially.)
> """

Thanks for the tip to the doc. I'll replace that with a warning instead.
Also there was a usage of `.. attention` for the bblock patches, I'll send a
patch to replace that.

>> +
>> +   Providing unconditional global level configuration from the ``layer.conf``
>> +   file is *not* a good practice, and should be avoided. For this reason, the
>> +   section :ref:`Conditionally Provide Global-level Configurations With Your
>> +   Layer` below shows how the ``layer.conf`` file can be used to provide
>> +   configurations only if a certain condition is met.
>> +
>> +For example, if your layer provides a Linux kernel recipe named
>> +``linux-custom``, you may want to define the :term:`PREFERRED_PROVIDER` for the
>> +``linux-custom`` recipe::
>
> """
> you may want to make :term:`PREFERRED_PROVIDER` for the Linux kernel 
> virtual provider point to the ``linux-custom`` recipe.
> """
>
> Because we are not setting PREFERRED_PROVIDER **for** the linux-custom 
> recipe, we want to have virtual/kernel point at linux-custom (and it's 
> set outside of that recipe). Moreover, the content of PREFERRED_PROVIDER 
> for the linux-custom recipe isn't really of importance, it's more for 
> other recipes depending on *a* kernel (e.g. kernel-modules, image 
> recipes, etc...).

That's correct, I get exactly what you mean and re-reading my sentence with that
in mind does bother me too. :)

> Not happy about the way I phrased it so maybe you can suggest something 
> better here?

How about simply:

"""
you may want to make :term:`PREFERRED_PROVIDER_virtual/kernel
<PREFERRED_PROVIDER>` point to ``linux-custom``:
"""

>> +
>> +  PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
>> +
>> +This can be defined in the ``layer.conf`` file. If your layer is at the last
>> +position in the :term:`BBLAYERS` list, it will take precedence over previous
>> +``PREFERRED_PROVIDER_virtual/kernel`` assignments.
>> +
>
> Mmmmm, except if the machine configuration file sets it too with "="?

Also from local.conf, etc. I guess so what about:

"""
it will take precedence over previous ``PREFERRED_PROVIDER_virtual/kernel``
assignments (unless it is set from another :term:`configuration file` such as
machine configuration files).
"""

>> +Conditionally Provide Global-level Configurations With Your Layer
>> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> +
>> +In some cases, your layer may provide global configurations only if some
>> +features it provides are enabled. Since the ``layer.conf`` file is parsed at an
>> +earlier stage in the parsing process, the :term:`DISTRO_FEATURES` and
>> +:term:`MACHINE_FEATURES` variables are not yet available to ``layer.conf``, and
>> +declaring conditional assignments based on these variables is not possible. The
>> +following technique shows a way to bypass this limitation by using the
>> +:term:`USER_CLASSES` variable and a conditional ``include`` command.
>> +
>> +In the following steps, let's assume our layer is named ``meta-mylayer`` and
>> +that this layer defines a custom :ref:`distro feature <ref-features-distro>`
>> +named ``mylayer-kernel``. We will set the :term:`PREFERRED_PROVIDER` variable
>> +for the kernel only if our feature ``mylayer-kernel`` is part of the
>> +:term:`DISTRO_FEATURES`:
>> +
>> +#. Create an include file in the directory
>> +   ``meta-mylayer/conf/distro/include/``, for example a file named
>> +   ``mylayer-kernel-provider.inc`` that sets the kernel provider to
>> +   ``linux-custom``::
>> +
>> +      PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
>> +
>> +#. Provide a path to this include file in your ``layer.conf``::
>> +
>> +      META_MYLAYER_KERNEL_PROVIDER_PATH = "${LAYERDIR}/conf/distro/include/mylayer-kernel-provider.inc"
>> +
>> +#. Create a new class in ``meta-mylayer/classes-global/``, for example a class
>> +   ``meta-mylayer-cfg.bbclass``. Make it conditionally include the file
>> +   ``mylayer-kernel-provider.inc`` defined above, using the variable
>> +   ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``::
>> +
>> +      require ${@bb.utils.contains('DISTRO_FEATURES', 'mylayer-kernel', '${META_MYLAYER_KERNEL_PROVIDER_PATH}', '', d)}
>> +
>> +   For details on the ``bb.utils.contains`` function, see its definition in
>> +   :bitbake_git:`lib/bb/utils.py </tree/lib/bb/utils.py>`.
>> +
>> +   .. note::
>> +
>> +      The ``require`` command is designed to not fail if the function
>> +      ``bb.utils.contains`` returns an empty string.
>> +
>> +#. Back to your ``layer.conf`` file, add the class ``meta-mylayer-cfg`` class to
>> +   the :term:`USER_CLASSES` variable::
>> +
>> +      USER_CLASSES:append = " meta-mylayer-cfg"
>> +
>> +   This will add the class ``meta-mylayer-cfg`` to the list of classes to
>> +   globally inherit. Since the ``include`` command is conditional in
>> +   ``meta-mylayer-cfg.bbclass``, even though inherited the class will have no
>> +   effect until the feature ``mylayer-kernel`` is enabled through
>> +   :term:`DISTRO_FEATURES`.
>> +
>
> Since you go to such great lengths to explain how to create the bbclass, 
> require it conditionally, etc... Maybe provide how to "enable through 
> DISTRO_FEATURES" so we have the complete picture?

Good idea!

>> +This technique can also be used for :ref:`Machine features
>
> s/for/with/ ?

+1, thanks :)

> Looks good otherwise :)
>
> Cheers,
> Quentin

Thank you!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [PATCH v2 2/2] dev-manual: document how to provide confs from layer.conf

[Quentin Schulz]

Hi Antonin,

On 11/13/24 3:16 PM, Antonin Godard wrote:
> Hi Quentin,
> 
> On Wed Nov 13, 2024 at 10:58 AM CET, Quentin Schulz wrote:
>> Hi Antonin,
>>
>> On 11/12/24 12:32 PM, Antonin Godard wrote:
>>> Add a section on providing global level configuration from the
>>> layer.conf file. Since this file is parsed at an earlier stage in the
>>> parsing process, it's not possible to combine bb.utils.contains and
>>> {DISTRO,MACHINE}_FEATURES to conditionally set some configurations.
>>>
>>> This patch documents:
>>>
>>> - First that this file can be used for providing such configuration.
>>> - Then demonstrate how to conditionally provide them, using a technique
>>>     that is currently used in meta-virtualization
>>>     (https://git.yoctoproject.org/meta-virtualization/tree/conf/layer.conf#n50).
>>>
>>> Fixes [YOCTO #12688].
>>>
>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>> ---
>>>    documentation/dev-manual/layers.rst | 86 +++++++++++++++++++++++++++++++++++++
>>>    1 file changed, 86 insertions(+)
>>>
>>> diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
>>> index 91889bd0ae391c7b6e62068778ae5c180c840762..e449fd43ad86c9a027e317e49b6e2f2f340a08d4 100644
>>> --- a/documentation/dev-manual/layers.rst
>>> +++ b/documentation/dev-manual/layers.rst
>>> @@ -644,6 +644,92 @@ variable and append the layer's root name::
>>>       order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake
>>>       might address this.
>>>    
>>> +Providing Global-level Configurations With Your Layer
>>> +-----------------------------------------------------
>>> +
>>> +When creating a layer, you may need to define configurations that should take
>>> +effect globally in your build environment when the layer is part of the build.
>>> +The ``layer.conf`` file is a :term:`configuration file` that affects the build
>>> +system globally, so it is a candidate for this use-case.
>>> +
>>> +.. attention::
>>
>> I would recommend using .. note or .. warning admonitions over other ones.
>>
>> Right now it seems we have mainly .. note, but also a handful of ..
>> admonition and a couple of .. tip so maybe that's not the best advice.
>>
>> Anyway, why this suggestion?
>> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
>> """
>> Admonitions: attention, caution, danger, error, hint, important, note,
>> tip, warning and the generic admonition. (Most themes style only “note”
>> and “warning” specially.)
>> """
> 
> Thanks for the tip to the doc. I'll replace that with a warning instead.
> Also there was a usage of `.. attention` for the bblock patches, I'll send a
> patch to replace that.
> 

Ah yes, haven't pulled yocto-docs in a while :)

>>> +
>>> +   Providing unconditional global level configuration from the ``layer.conf``
>>> +   file is *not* a good practice, and should be avoided. For this reason, the
>>> +   section :ref:`Conditionally Provide Global-level Configurations With Your
>>> +   Layer` below shows how the ``layer.conf`` file can be used to provide
>>> +   configurations only if a certain condition is met.
>>> +
>>> +For example, if your layer provides a Linux kernel recipe named
>>> +``linux-custom``, you may want to define the :term:`PREFERRED_PROVIDER` for the
>>> +``linux-custom`` recipe::
>>
>> """
>> you may want to make :term:`PREFERRED_PROVIDER` for the Linux kernel
>> virtual provider point to the ``linux-custom`` recipe.
>> """
>>
>> Because we are not setting PREFERRED_PROVIDER **for** the linux-custom
>> recipe, we want to have virtual/kernel point at linux-custom (and it's
>> set outside of that recipe). Moreover, the content of PREFERRED_PROVIDER
>> for the linux-custom recipe isn't really of importance, it's more for
>> other recipes depending on *a* kernel (e.g. kernel-modules, image
>> recipes, etc...).
> 
> That's correct, I get exactly what you mean and re-reading my sentence with that
> in mind does bother me too. :)
> 
>> Not happy about the way I phrased it so maybe you can suggest something
>> better here?
> 
> How about simply:
> 
> """
> you may want to make :term:`PREFERRED_PROVIDER_virtual/kernel
> <PREFERRED_PROVIDER>` point to ``linux-custom``:
> """
> 

Works for me!

>>> +
>>> +  PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
>>> +
>>> +This can be defined in the ``layer.conf`` file. If your layer is at the last
>>> +position in the :term:`BBLAYERS` list, it will take precedence over previous
>>> +``PREFERRED_PROVIDER_virtual/kernel`` assignments.
>>> +
>>
>> Mmmmm, except if the machine configuration file sets it too with "="?
> 
> Also from local.conf, etc. I guess so what about:
> 
> """
> it will take precedence over previous ``PREFERRED_PROVIDER_virtual/kernel``
> assignments (unless it is set from another :term:`configuration file` such as
> machine configuration files).
> """
> 

another configuration file that is parsed later, such as machine or 
distro configuration files.

?

Cheers,
Quentin

Re: [PATCH v2 2/2] dev-manual: document how to provide confs from layer.conf

[Antonin Godard]

On Wed Nov 13, 2024 at 3:20 PM CET, Quentin Schulz wrote:
[...]
>>>> +
>>>> +  PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
>>>> +
>>>> +This can be defined in the ``layer.conf`` file. If your layer is at the last
>>>> +position in the :term:`BBLAYERS` list, it will take precedence over previous
>>>> +``PREFERRED_PROVIDER_virtual/kernel`` assignments.
>>>> +
>>>
>>> Mmmmm, except if the machine configuration file sets it too with "="?
>> 
>> Also from local.conf, etc. I guess so what about:
>> 
>> """
>> it will take precedence over previous ``PREFERRED_PROVIDER_virtual/kernel``
>> assignments (unless it is set from another :term:`configuration file` such as
>> machine configuration files).
>> """
>> 
>
> another configuration file that is parsed later, such as machine or 
> distro configuration files.
>
> ?

Yep, this looks good. :)

> Cheers,
> Quentin

I'll send a v3 shortly. :)

Thank you,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com