mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-30 21:32:13 +02:00
Code Issues Packages Projects Releases Wiki Activity

ref-manual: clarify explanations about feature backfilling

Browse Source 
(From yocto-docs rev: edae43e60230ad5f2384f0a518b42fc08efc699e)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Joshua Watt <JPEWhacker@gmail.com>
CC: Martin Jansa <martin.jansa@gmail.com>
CC: Tom Hochstein <tom.hochstein@nxp.com>
CC: Richard Purdie <richard.purdie@linuxfoundation.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Michael Opdenacker
2023-02-28 19:07:13 +01:00
committed by Richard Purdie
parent f559a61295
commit 8c49eb57b6
3 changed files with 75 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
documentation/ref-manual/classes.rst
View File

@@ -858,8 +858,9 @@ introspection. This functionality is only enabled if the
.. note::
This functionality is backfilled by default and, if not applicable,
should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
This functionality is :ref:`backfilled <ref-features-backfill>` by default
and, if not applicable, should be disabled through
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
.. _ref-classes-grub-efi:

86
documentation/ref-manual/features.rst
View File

@@ -6,7 +6,7 @@ Features
This chapter provides a reference of shipped machine and distro features
you can include as part of your image, a reference on image features you
can select, and a reference on feature backfilling.
can select, and a reference on :ref:`ref-features-backfill`.
Features provide a mechanism for working out which packages should be
included in the generated images. Distributions can select which
@@ -416,58 +416,50 @@ these valid features is as follows:
Feature Backfilling
===================
Sometimes it is necessary in the OpenEmbedded build system to extend
:term:`MACHINE_FEATURES` or
:term:`DISTRO_FEATURES` to control functionality
that was previously enabled and not able to be disabled. For these
cases, we need to add an additional feature item to appear in one of
these variables, but we do not want to force developers who have
existing values of the variables in their configuration to add the new
feature in order to retain the same overall level of functionality.
Thus, the OpenEmbedded build system has a mechanism to automatically
"backfill" these added features into existing distro or machine
Sometimes it is necessary in the OpenEmbedded build system to
add new functionality to :term:`MACHINE_FEATURES` or
:term:`DISTRO_FEATURES`, but at the same time, allow existing
distributions or machine definitions to opt out of such new
features, to retain the same overall level of functionality.
To make this possible, the OpenEmbedded build system has a mechanism to
automatically "backfill" features into existing distro or machine
configurations. You can see the list of features for which this is done
by finding the
:term:`DISTRO_FEATURES_BACKFILL` and
:term:`MACHINE_FEATURES_BACKFILL`
variables in the ``meta/conf/bitbake.conf`` file.
by checking the :term:`DISTRO_FEATURES_BACKFILL` and
:term:`MACHINE_FEATURES_BACKFILL` variables in the
``meta/conf/bitbake.conf`` file.
Because such features are backfilled by default into all configurations
as described in the previous paragraph, developers who wish to disable
the new features need to be able to selectively prevent the backfilling
from occurring. They can do this by adding the undesired feature or
features to the
These two variables are paired with the
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
or
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
variables for distro features and machine features respectively.
and :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` variables
which allow distro or machine configuration maintainers to `consider` any
added feature, and decide when they wish to keep or exclude such feature,
thus preventing the backfilling from happening.
Here are two examples to help illustrate feature backfilling:
Here are two examples to illustrate feature backfilling:
- *The "pulseaudio" distro feature option*: Previously, PulseAudio
support was enabled within the Qt and GStreamer frameworks. Because
of this, the feature is backfilled and thus enabled for all distros
through the :term:`DISTRO_FEATURES_BACKFILL` variable in the
``meta/conf/bitbake.conf`` file. However, your distro needs to
disable the feature. You can disable the feature without affecting
other existing distro configurations that need PulseAudio support by
adding "pulseaudio" to :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in
your distro's ``.conf`` file. Adding the feature to this variable
when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable
prevents the build system from adding the feature to your
configuration's :term:`DISTRO_FEATURES`, effectively disabling the
feature for that particular distro.
- *The "pulseaudio" distro feature option*: Previously, PulseAudio support was
enabled within the Qt and GStreamer frameworks. Because of this, the feature
is now backfilled and thus enabled for all distros through the
:term:`DISTRO_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf``
file. However, if your distro needs to disable the feature, you can do so
without affecting other existing distro configurations that need PulseAudio
support. You do this by adding "pulseaudio" to
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in your distro's ``.conf``
file. So, adding the feature to this variable when it also exists in the
:term:`DISTRO_FEATURES_BACKFILL` variable prevents the build system from
adding the feature to your configuration's :term:`DISTRO_FEATURES`,
effectively disabling the feature for that particular distro.
- *The "rtc" machine feature option*: Previously, real time clock (RTC)
support was enabled for all target devices. Because of this, the
feature is backfilled and thus enabled for all machines through the
:term:`MACHINE_FEATURES_BACKFILL` variable in the
``meta/conf/bitbake.conf`` file. However, your target device does not
have this capability. You can disable RTC support for your device
without affecting other machines that need RTC support by adding the
feature to your machine's :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
list in the machine's ``.conf`` file. Adding the feature to this
variable when it also exists in the :term:`MACHINE_FEATURES_BACKFILL`
variable prevents the build system from adding the feature to your
configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC
support for that particular machine.
:term:`MACHINE_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf``
file. However, if your target device does not have this capability, you can
disable RTC support for your device without affecting other machines
that need RTC support. You do this by adding the "rtc" feature to the
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` list in your machine's ``.conf``
file. So, adding the feature to this variable when it also exists in the
:term:`MACHINE_FEATURES_BACKFILL` variable prevents the build system from
adding the feature to your configuration's :term:`MACHINE_FEATURES`,
effectively disabling RTC support for that particular machine.

50
documentation/ref-manual/variables.rst
View File

@@ -2111,19 +2111,27 @@ system and gives an overview of their function and contents.
provide with this variable, see the ":ref:`ref-features-distro`" section.
:term:`DISTRO_FEATURES_BACKFILL`
Features to be added to :term:`DISTRO_FEATURES` if not also present in
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
A space-separated list of features to be added to :term:`DISTRO_FEATURES`
if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
This variable is set in the ``meta/conf/bitbake.conf`` file. It is
not intended to be user-configurable. It is best to just reference
the variable to see which distro features are being backfilled for
all distro configurations. See the ":ref:`ref-features-backfill`" section
for more information.
the variable to see which distro features are being
:ref:`backfilled <ref-features-backfill>` for all distro configurations.
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
Features from :term:`DISTRO_FEATURES_BACKFILL` that should not be
backfilled (i.e. added to :term:`DISTRO_FEATURES`) during the build. See
the ":ref:`ref-features-backfill`" section for more information.
A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL`
that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
to :term:`DISTRO_FEATURES`) during the build.
This corresponds to an opt-out mechanism. When new default distro
features are introduced, distribution maintainers can review (`consider`)
them and decide to exclude them from the
:ref:`backfilled <ref-features-backfill>` features. Therefore, the
combination of :term:`DISTRO_FEATURES_BACKFILL` and
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to
add new default features without breaking existing distributions.
:term:`DISTRO_FEATURES_DEFAULT`
A convenience variable that gives you the default list of distro
@@ -5129,19 +5137,27 @@ system and gives an overview of their function and contents.
shipped, see the ":ref:`ref-features-machine`" section.
:term:`MACHINE_FEATURES_BACKFILL`
Features to be added to :term:`MACHINE_FEATURES` if not also present in
A list of space-separated features to be added to
:term:`MACHINE_FEATURES` if not also present in
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
This variable is set in the ``meta/conf/bitbake.conf`` file. It is
not intended to be user-configurable. It is best to just reference
the variable to see which machine features are being backfilled for
all machine configurations. See the ":ref:`ref-features-backfill`"
section for more information.
This variable is set in the ``meta/conf/bitbake.conf`` file. It is not
intended to be user-configurable. It is best to just reference the
variable to see which machine features are being
:ref:`backfilled <ref-features-backfill>` for all machine configurations.
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
Features from :term:`MACHINE_FEATURES_BACKFILL` that should not be
backfilled (i.e. added to :term:`MACHINE_FEATURES`) during the build. See
the ":ref:`ref-features-backfill`" section for more information.
A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL`
that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
to :term:`MACHINE_FEATURES`) during the build.
This corresponds to an opt-out mechanism. When new default machine
features are introduced, machine definition maintainers can review
(`consider`) them and decide to exclude them from the
:ref:`backfilled <ref-features-backfill>` features. Therefore, the
combination of :term:`MACHINE_FEATURES_BACKFILL` and
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to
add new default features without breaking existing machine definitions.
:term:`MACHINEOVERRIDES`
A colon-separated list of overrides that apply to the current