From fb968f87a5a039f03bb99502832c2b51b7d70dd8 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 18 Oct 2012 13:26:39 -0700 Subject: documentation: poky-ref-manual - edits to the features backfill section. (From yocto-docs rev: 7507d73501830896602bb18677eb7b0710794f55) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/ref-features.xml | 114 ++++++++++++------------- 1 file changed, 53 insertions(+), 61 deletions(-) (limited to 'documentation') diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml index 8c3304aa72..f4d755666d 100644 --- a/documentation/poky-ref-manual/ref-features.xml +++ b/documentation/poky-ref-manual/ref-features.xml @@ -176,27 +176,39 @@ Feature Backfilling - Sometimes it is necessary to add a new feature option to the + Sometimes it is necessary to control functionality enabled by features + that are listed with MACHINE_FEATURES - or DISTRO_FEATURES - lists and have it affect all configurations. - For example, suppose new functionality is developed and it must be enabled + and DISTRO_FEATURES. + For example, some functionality exists that is enabled by default for all configurations. + For these cases, the metadata, as shipped with the Yocto Project, ensures + the feature is "backfilled" into all the specific distro + and machine configurations. + You can see how this is done by finding the + DISTRO_FEATURES_BACKFILL + and MACHINE_FEATURES_BACKFILL + variables in the meta/conf/bitbake.conf file. - 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. - + Because certain functionality is enabled across all configurations as + described in the previous paragraph, it also becomes necessary + to give the developer the ability to disable (remove) a feature + from a particular configuration. + For example, suppose you have a machine feature that needs to be + disabled but the metadata has backfilled it across all configurations as enabled. + You need to be able to remove the feature from your configuration's + MACHINE_FEATURES + without disturbing existing configurations that still + might need the functionality? + + + + Feature backfilling allows you to selectively prevent a feature from + being backfilled to MACHINE_FEATURES, + DISTRO_FEATURES, or both. + Here are two examples to help illustrate feature backfilling: @@ -204,58 +216,38 @@ 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. + Because of this, the feature is backfilled and thus + enabled for all distros through the + 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 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. - + by adding "pulseaudio" to + DISTRO_FEATURES_BACKFILL_CONSIDERED + in your distro's .conf file. + Adding the feature to this variable when it also + exists in the DISTRO_FEATURES_BACKFILL + variable prevents the build system from adding the feature to + your configuration's 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 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 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. - + affecting other machines that need RTC support + by adding the feature to your machine's + MACHINE_FEATURES_BACKFILL_CONSIDERED + list in the machine's .conf file. + Adding the feature to this variable when it also + exists in the MACHINE_FEATURES_BACKFILL + variable prevents the build system from adding the feature to + your configuration's MACHINE_FEATURES, effectively + disabling RTC support for that particular machine. -- cgit v1.2.3-54-g00ecf