CaROS/poky
3
1
Fork 0
mirror of https://git.yoctoproject.org/git/poky synced 2026-01-04 16:10:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

dev-manual: document how to provide confs from layer.conf

Browse Source 
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].

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
(From yocto-docs rev: e49111c280927c922ab40547c02c11772787b731)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 31e5bd3e82e11f77da2abd96eb8c17a7c8194b7c)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Steve Sakoman <steve@sakoman.com>
This commit is contained in:
Antonin Godard 2024-11-13 16:28:12 +01:00 committed by Steve Sakoman
parent 8b2a0a0eed
commit 7651767849
1 changed files with 90 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
documentation/dev-manual/layers.rst
View File

@ -644,6 +644,96 @@ 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.
.. warning::
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:`ref-conditional-layer-confs` 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 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 (unless one is set from a
:term:`configuration file` that is parsed later, such as machine or distro
configuration files).
.. _ref-conditional-layer-confs:
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 ``require`` 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 require 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 ``require`` command is conditional in
``meta-mylayer-cfg.bbclass``, even though inherited the class will have no
effect unless 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
===============