diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2023-02-28 19:07:13 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2023-03-20 13:16:52 +0000 |
commit | 8c49eb57b63bc867296a2853a3d132fed58add26 (patch) | |
tree | 4f1ea9cd8c50b52fa4fe989a7e117f01cdb4d27d /documentation | |
parent | f559a61295b36836f35f820c0ba74ffaed4dc13e (diff) | |
download | poky-8c49eb57b63bc867296a2853a3d132fed58add26.tar.gz |
ref-manual: clarify explanations about feature backfilling
(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>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/ref-manual/classes.rst | 5 | ||||
-rw-r--r-- | documentation/ref-manual/features.rst | 92 | ||||
-rw-r--r-- | documentation/ref-manual/variables.rst | 50 |
3 files changed, 78 insertions, 69 deletions
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 7ff0fcb335..e8dec31b00 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst | |||
@@ -858,8 +858,9 @@ introspection. This functionality is only enabled if the | |||
858 | 858 | ||
859 | .. note:: | 859 | .. note:: |
860 | 860 | ||
861 | This functionality is backfilled by default and, if not applicable, | 861 | This functionality is :ref:`backfilled <ref-features-backfill>` by default |
862 | should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or | 862 | and, if not applicable, should be disabled through |
863 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or | ||
863 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively. | 864 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively. |
864 | 865 | ||
865 | .. _ref-classes-grub-efi: | 866 | .. _ref-classes-grub-efi: |
diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst index 051bf9320a..5a064329f1 100644 --- a/documentation/ref-manual/features.rst +++ b/documentation/ref-manual/features.rst | |||
@@ -6,7 +6,7 @@ Features | |||
6 | 6 | ||
7 | This chapter provides a reference of shipped machine and distro features | 7 | This chapter provides a reference of shipped machine and distro features |
8 | you can include as part of your image, a reference on image features you | 8 | you can include as part of your image, a reference on image features you |
9 | can select, and a reference on feature backfilling. | 9 | can select, and a reference on :ref:`ref-features-backfill`. |
10 | 10 | ||
11 | Features provide a mechanism for working out which packages should be | 11 | Features provide a mechanism for working out which packages should be |
12 | included in the generated images. Distributions can select which | 12 | included in the generated images. Distributions can select which |
@@ -416,58 +416,50 @@ these valid features is as follows: | |||
416 | Feature Backfilling | 416 | Feature Backfilling |
417 | =================== | 417 | =================== |
418 | 418 | ||
419 | Sometimes it is necessary in the OpenEmbedded build system to extend | 419 | Sometimes it is necessary in the OpenEmbedded build system to |
420 | :term:`MACHINE_FEATURES` or | 420 | add new functionality to :term:`MACHINE_FEATURES` or |
421 | :term:`DISTRO_FEATURES` to control functionality | 421 | :term:`DISTRO_FEATURES`, but at the same time, allow existing |
422 | that was previously enabled and not able to be disabled. For these | 422 | distributions or machine definitions to opt out of such new |
423 | cases, we need to add an additional feature item to appear in one of | 423 | features, to retain the same overall level of functionality. |
424 | these variables, but we do not want to force developers who have | 424 | |
425 | existing values of the variables in their configuration to add the new | 425 | To make this possible, the OpenEmbedded build system has a mechanism to |
426 | feature in order to retain the same overall level of functionality. | 426 | automatically "backfill" features into existing distro or machine |
427 | Thus, the OpenEmbedded build system has a mechanism to automatically | ||
428 | "backfill" these added features into existing distro or machine | ||
429 | configurations. You can see the list of features for which this is done | 427 | configurations. You can see the list of features for which this is done |
430 | by finding the | 428 | by checking the :term:`DISTRO_FEATURES_BACKFILL` and |
431 | :term:`DISTRO_FEATURES_BACKFILL` and | 429 | :term:`MACHINE_FEATURES_BACKFILL` variables in the |
432 | :term:`MACHINE_FEATURES_BACKFILL` | 430 | ``meta/conf/bitbake.conf`` file. |
433 | variables in the ``meta/conf/bitbake.conf`` file. | 431 | |
434 | 432 | These two variables are paired with the | |
435 | Because such features are backfilled by default into all configurations | ||
436 | as described in the previous paragraph, developers who wish to disable | ||
437 | the new features need to be able to selectively prevent the backfilling | ||
438 | from occurring. They can do this by adding the undesired feature or | ||
439 | features to the | ||
440 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | 433 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` |
441 | or | 434 | and :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` variables |
442 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` | 435 | which allow distro or machine configuration maintainers to `consider` any |
443 | variables for distro features and machine features respectively. | 436 | added feature, and decide when they wish to keep or exclude such feature, |
444 | 437 | thus preventing the backfilling from happening. | |
445 | Here are two examples to help illustrate feature backfilling: | 438 | |
446 | 439 | Here are two examples to illustrate feature backfilling: | |
447 | - *The "pulseaudio" distro feature option*: Previously, PulseAudio | 440 | |
448 | support was enabled within the Qt and GStreamer frameworks. Because | 441 | - *The "pulseaudio" distro feature option*: Previously, PulseAudio support was |
449 | of this, the feature is backfilled and thus enabled for all distros | 442 | enabled within the Qt and GStreamer frameworks. Because of this, the feature |
450 | through the :term:`DISTRO_FEATURES_BACKFILL` variable in the | 443 | is now backfilled and thus enabled for all distros through the |
451 | ``meta/conf/bitbake.conf`` file. However, your distro needs to | 444 | :term:`DISTRO_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` |
452 | disable the feature. You can disable the feature without affecting | 445 | file. However, if your distro needs to disable the feature, you can do so |
453 | other existing distro configurations that need PulseAudio support by | 446 | without affecting other existing distro configurations that need PulseAudio |
454 | adding "pulseaudio" to :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in | 447 | support. You do this by adding "pulseaudio" to |
455 | your distro's ``.conf`` file. Adding the feature to this variable | 448 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in your distro's ``.conf`` |
456 | when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable | 449 | file. So, adding the feature to this variable when it also exists in the |
457 | prevents the build system from adding the feature to your | 450 | :term:`DISTRO_FEATURES_BACKFILL` variable prevents the build system from |
458 | configuration's :term:`DISTRO_FEATURES`, effectively disabling the | 451 | adding the feature to your configuration's :term:`DISTRO_FEATURES`, |
459 | feature for that particular distro. | 452 | effectively disabling the feature for that particular distro. |
460 | 453 | ||
461 | - *The "rtc" machine feature option*: Previously, real time clock (RTC) | 454 | - *The "rtc" machine feature option*: Previously, real time clock (RTC) |
462 | support was enabled for all target devices. Because of this, the | 455 | support was enabled for all target devices. Because of this, the |
463 | feature is backfilled and thus enabled for all machines through the | 456 | feature is backfilled and thus enabled for all machines through the |
464 | :term:`MACHINE_FEATURES_BACKFILL` variable in the | 457 | :term:`MACHINE_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` |
465 | ``meta/conf/bitbake.conf`` file. However, your target device does not | 458 | file. However, if your target device does not have this capability, you can |
466 | have this capability. You can disable RTC support for your device | 459 | disable RTC support for your device without affecting other machines |
467 | without affecting other machines that need RTC support by adding the | 460 | that need RTC support. You do this by adding the "rtc" feature to the |
468 | feature to your machine's :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` | 461 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` list in your machine's ``.conf`` |
469 | list in the machine's ``.conf`` file. Adding the feature to this | 462 | file. So, adding the feature to this variable when it also exists in the |
470 | variable when it also exists in the :term:`MACHINE_FEATURES_BACKFILL` | 463 | :term:`MACHINE_FEATURES_BACKFILL` variable prevents the build system from |
471 | variable prevents the build system from adding the feature to your | 464 | adding the feature to your configuration's :term:`MACHINE_FEATURES`, |
472 | configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC | 465 | effectively disabling RTC support for that particular machine. |
473 | support for that particular machine. | ||
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 9b581599e3..2e32e264db 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst | |||
@@ -2111,19 +2111,27 @@ system and gives an overview of their function and contents. | |||
2111 | provide with this variable, see the ":ref:`ref-features-distro`" section. | 2111 | provide with this variable, see the ":ref:`ref-features-distro`" section. |
2112 | 2112 | ||
2113 | :term:`DISTRO_FEATURES_BACKFILL` | 2113 | :term:`DISTRO_FEATURES_BACKFILL` |
2114 | Features to be added to :term:`DISTRO_FEATURES` if not also present in | 2114 | A space-separated list of features to be added to :term:`DISTRO_FEATURES` |
2115 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. | 2115 | if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. |
2116 | 2116 | ||
2117 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | 2117 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is |
2118 | not intended to be user-configurable. It is best to just reference | 2118 | not intended to be user-configurable. It is best to just reference |
2119 | the variable to see which distro features are being backfilled for | 2119 | the variable to see which distro features are being |
2120 | all distro configurations. See the ":ref:`ref-features-backfill`" section | 2120 | :ref:`backfilled <ref-features-backfill>` for all distro configurations. |
2121 | for more information. | ||
2122 | 2121 | ||
2123 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | 2122 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` |
2124 | Features from :term:`DISTRO_FEATURES_BACKFILL` that should not be | 2123 | A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL` |
2125 | backfilled (i.e. added to :term:`DISTRO_FEATURES`) during the build. See | 2124 | that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added |
2126 | the ":ref:`ref-features-backfill`" section for more information. | 2125 | to :term:`DISTRO_FEATURES`) during the build. |
2126 | |||
2127 | This corresponds to an opt-out mechanism. When new default distro | ||
2128 | features are introduced, distribution maintainers can review (`consider`) | ||
2129 | them and decide to exclude them from the | ||
2130 | :ref:`backfilled <ref-features-backfill>` features. Therefore, the | ||
2131 | combination of :term:`DISTRO_FEATURES_BACKFILL` and | ||
2132 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to | ||
2133 | add new default features without breaking existing distributions. | ||
2134 | |||
2127 | 2135 | ||
2128 | :term:`DISTRO_FEATURES_DEFAULT` | 2136 | :term:`DISTRO_FEATURES_DEFAULT` |
2129 | A convenience variable that gives you the default list of distro | 2137 | 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. | |||
5129 | shipped, see the ":ref:`ref-features-machine`" section. | 5137 | shipped, see the ":ref:`ref-features-machine`" section. |
5130 | 5138 | ||
5131 | :term:`MACHINE_FEATURES_BACKFILL` | 5139 | :term:`MACHINE_FEATURES_BACKFILL` |
5132 | Features to be added to :term:`MACHINE_FEATURES` if not also present in | 5140 | A list of space-separated features to be added to |
5141 | :term:`MACHINE_FEATURES` if not also present in | ||
5133 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. | 5142 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. |
5134 | 5143 | ||
5135 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | 5144 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is not |
5136 | not intended to be user-configurable. It is best to just reference | 5145 | intended to be user-configurable. It is best to just reference the |
5137 | the variable to see which machine features are being backfilled for | 5146 | variable to see which machine features are being |
5138 | all machine configurations. See the ":ref:`ref-features-backfill`" | 5147 | :ref:`backfilled <ref-features-backfill>` for all machine configurations. |
5139 | section for more information. | ||
5140 | 5148 | ||
5141 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` | 5149 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` |
5142 | Features from :term:`MACHINE_FEATURES_BACKFILL` that should not be | 5150 | A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL` |
5143 | backfilled (i.e. added to :term:`MACHINE_FEATURES`) during the build. See | 5151 | that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added |
5144 | the ":ref:`ref-features-backfill`" section for more information. | 5152 | to :term:`MACHINE_FEATURES`) during the build. |
5153 | |||
5154 | This corresponds to an opt-out mechanism. When new default machine | ||
5155 | features are introduced, machine definition maintainers can review | ||
5156 | (`consider`) them and decide to exclude them from the | ||
5157 | :ref:`backfilled <ref-features-backfill>` features. Therefore, the | ||
5158 | combination of :term:`MACHINE_FEATURES_BACKFILL` and | ||
5159 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to | ||
5160 | add new default features without breaking existing machine definitions. | ||
5145 | 5161 | ||
5146 | :term:`MACHINEOVERRIDES` | 5162 | :term:`MACHINEOVERRIDES` |
5147 | A colon-separated list of overrides that apply to the current | 5163 | A colon-separated list of overrides that apply to the current |