diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-10-18 10:12:10 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2012-10-19 17:38:50 +0100 |
commit | 45b98aa5617224592aeea1d80d8ce90530087e23 (patch) | |
tree | d2b5beaf80116abb28cebf688c5c031f80db49e0 /documentation | |
parent | 93ecafc466129289541699a3c2312987efaac345 (diff) | |
download | ast2050-yocto-poky-45b98aa5617224592aeea1d80d8ce90530087e23.zip ast2050-yocto-poky-45b98aa5617224592aeea1d80d8ce90530087e23.tar.gz |
documentation: poky-ref-manual - updates to feature backfill section.
(From yocto-docs rev: aaf1156398033d50add5ac3944aa575917c7f7de)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/poky-ref-manual/ref-features.xml | 119 |
1 files changed, 76 insertions, 43 deletions
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml index c42a4fd..8c3304a 100644 --- a/documentation/poky-ref-manual/ref-features.xml +++ b/documentation/poky-ref-manual/ref-features.xml @@ -176,54 +176,87 @@ <title>Feature Backfilling</title> <para> - 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 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> - and <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>. + Sometimes it is necessary to add a new feature option to the + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> + or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + lists and have it affect all configurations. + For example, suppose new functionality is developed and it must be enabled + by default for all configurations. </para> <para> - 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 - <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename> - within <filename>meta/conf/bitbake.conf</filename>. - This means that "pulseaudio" - is automatically added to <filename>DISTRO_FEATURES</filename> without the distro - configuration needing to be updated to do so itself. - Those who do not want PulseAudio support can add "pulseaudio" to - <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename> - in their distro <filename>.conf</filename> file and this will disable adding "pulseaudio" to - <filename>DISTRO_FEATURES</filename>. - </para> + 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 + <filename>DISTRO_FEATURES</filename> 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 <filename>MACHINE_FEATURES</filename> and + <filename>DISTRO_FEATURES</filename> lists. + </para> <para> - 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 - <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename> - within <filename>meta/conf/bitbake.conf</filename>. - This means that "rtc" - is automatically added to <filename>MACHINE_FEATURES</filename> without the - machine configuration needing to be updated to do so itself. - For machines that not need RTC support can add "rtc" to - <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename> - in their machine <filename>.conf</filename> file and this will disable adding "rtc" to - <filename>MACHINE_FEATURES</filename>. + Here are two examples to help illustrate feature backfilling: + <itemizedlist> + <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: + 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: + <itemizedlist> + <listitem><para>Add "pulseaudio" to + <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> + within your <filename>meta/conf/bitbake.conf</filename> file. + Adding the feature option causes the build process + to automatically add "pulseaudio" to + <filename>DISTRO_FEATURES</filename> 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.</para></listitem> + <listitem><para>Add "pulseaudio" to + <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> + in your distro's <filename>.conf</filename> file. + Adding the feature option to this variable when it also + exists in the <filename>DISTRO_FEATURES_BACKFILL</filename> + variable prevents the build system from adding the feature option to + <filename>DISTRO_FEATURES</filename>, effectively disabling + the feature for that particular distro.</para></listitem> + </itemizedlist></para></listitem> + <listitem><para><emphasis>The "rtc" machine feature option</emphasis>: + 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: + <itemizedlist> + <listitem><para>Add "rtc" to <filename>MACHINE_FEATURES_BACKFILL</filename> + within your <filename>meta/conf/bitbake.conf</filename>. + Adding the feature option causes the build process + to automatically add "rtc" to + <filename>MACHINE_FEATURES</filename> 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.</para></listitem> + <listitem><para>Add "rtc" to + <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename> + in your machine's <filename>.conf</filename> file. + Adding the feature option to this variable when it also + exists in the <filename>MACHINE_FEATURES_BACKFILL</filename> + variable prevents the build system from adding the feature option to + <filename>MACHINE_FEATURES</filename>, effectively disabling + RTC support for feature that particular machine.</para></listitem> + </itemizedlist></para></listitem> + </itemizedlist> </para> </section> </chapter> |