From b7e951a842d06f07d9aad20d39129c9522468ce3 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 18 Oct 2012 10:12:10 -0700 Subject: documentation: poky-ref-manual - updates to feature backfill section. (From yocto-docs rev: aaf1156398033d50add5ac3944aa575917c7f7de) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/ref-features.xml | 119 ++++++++++++++++--------- 1 file changed, 76 insertions(+), 43 deletions(-) (limited to 'documentation/poky-ref-manual') diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml index c42a4fd807..8c3304aa72 100644 --- a/documentation/poky-ref-manual/ref-features.xml +++ b/documentation/poky-ref-manual/ref-features.xml @@ -176,54 +176,87 @@ Feature Backfilling - Sometimes, it is necessary for a new feature to be added to control existing - functionality that was previously enabled by default and not able to be disabled. - In order to ensure that the feature remains enabled for users with existing - configurations that upgrade to a new version of the core metadata without that - configuration having to be changed, while still allowing others who want to turn - the feature off to do so, the backfilling mechanism was introduced. - This - functionality is available for DISTRO_FEATURES - and MACHINE_FEATURES. + Sometimes it is necessary to add a new feature option to the + MACHINE_FEATURES + or DISTRO_FEATURES + lists and have it affect all configurations. + For example, suppose new functionality is developed and it must be enabled + by default for all configurations. - An example is the "pulseaudio" distro feature. - Previously, PulseAudio support - was enabled within the Qt and GStreamer frameworks. - However some users desired - to be able to disable this. - To allow this to be disabled without affecting - existing configurations in which PulseAudio support should remain enabled, - "pulseaudio" was added to - DISTRO_FEATURES_BACKFILL - within meta/conf/bitbake.conf. - This means that "pulseaudio" - is automatically added to DISTRO_FEATURES without the distro - configuration needing to be updated to do so itself. - Those who do not want PulseAudio support can add "pulseaudio" to - DISTRO_FEATURES_BACKFILL_CONSIDERED - in their distro .conf file and this will disable adding "pulseaudio" to - DISTRO_FEATURES. - + Sometimes it is also necessary to disable (remove) a feature + option, which has been previously enabled by default, from the machine or distro lists. + For example, perhaps a mandatory distro feature becomes optional. + How can you remove the feature option from the + DISTRO_FEATURES list + without disturbing all the existing configurations that still + might need the feature? + Feature backfilling allows you "backfill" the feature into all the + configurations and then lets you selectively prevent the feature from + being added to MACHINE_FEATURES and + DISTRO_FEATURES lists. + - Another example is the "rtc" machine feature. - Previously, real time clock (RTC) - support was enabled for all target devices. - However certain targets do not have - this capability. - To allow this to be disabled by such machines without affecting - other machines in which RTC support should remain enabled, "rtc" was added to - MACHINE_FEATURES_BACKFILL - within meta/conf/bitbake.conf. - This means that "rtc" - is automatically added to MACHINE_FEATURES without the - machine configuration needing to be updated to do so itself. - For machines that not need RTC support can add "rtc" to - MACHINE_FEATURES_BACKFILL_CONSIDERED - in their machine .conf file and this will disable adding "rtc" to - MACHINE_FEATURES. + Here are two examples to help illustrate feature backfilling: + + The "pulseaudio" distro feature option: + Previously, PulseAudio support was enabled within the Qt and + GStreamer frameworks. + However, you might need to disable the feature for your + distro. + You can disable the feature without affecting + other existing distro configurations that need PulseAudio support + by doing the following: + + Add "pulseaudio" to + DISTRO_FEATURES_BACKFILL + within your meta/conf/bitbake.conf file. + Adding the feature option causes the build process + to automatically add "pulseaudio" to + DISTRO_FEATURES without the need to + update any distro configurations. + This step by itself enables the feature + for all distros and consequently ensures that existing + configurations that still need the feature are + undisturbed. + Add "pulseaudio" to + DISTRO_FEATURES_BACKFILL_CONSIDERED + in your distro's .conf file. + Adding the feature option to this variable when it also + exists in the DISTRO_FEATURES_BACKFILL + variable prevents the build system from adding the feature option to + 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. + However, your target device does not have this capability. + You can disable RTC support for your device without + affecting other machines where RTC support should remain enabled + by doing the following: + + Add "rtc" to MACHINE_FEATURES_BACKFILL + within your meta/conf/bitbake.conf. + Adding the feature option causes the build process + to automatically add "rtc" to + MACHINE_FEATURES without the need to + update any machine configurations. + This step by itself enables RTC support for all machines + and consequently ensures that existing configurations + that still need the feature are undisturbed. + Add "rtc" to + MACHINE_FEATURES_BACKFILL_CONSIDERED + in your machine's .conf file. + Adding the feature option to this variable when it also + exists in the MACHINE_FEATURES_BACKFILL + variable prevents the build system from adding the feature option to + MACHINE_FEATURES, effectively disabling + RTC support for feature that particular machine. + + -- cgit v1.2.3-54-g00ecf