diff options
author | Paul Eggleton <paul.eggleton@linux.intel.com> | 2012-10-10 14:38:35 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2012-10-15 14:45:12 +0100 |
commit | 88924d6deae40513354919eae60d32a0c173bb7f (patch) | |
tree | 3ddb500d352d24cdba7cda34f669cd383adfc79c | |
parent | 5abdefd89c5e4a999ccbd55a516b9267412a2719 (diff) | |
download | ast2050-yocto-poky-88924d6deae40513354919eae60d32a0c173bb7f.zip ast2050-yocto-poky-88924d6deae40513354919eae60d32a0c173bb7f.tar.gz |
documentation: poky-ref-manual - New backfill variables and section.
Document DISTRO_FEATURES_BACKFILL and MACHINE_FEATURES_BACKFILL. We may
wish to expand upon this in future, but at least this explains what
these variables are for and how to use them.
Also add a link from the DISTRO_FEATURES entry to the section that lists
valid DISTRO_FEATURES items.
(From yocto-docs rev: 018af5c28b44464ae66646780ade910bdcab2bef)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/poky-ref-manual/ref-features.xml | 55 | ||||
-rw-r--r-- | documentation/poky-ref-manual/ref-variables.xml | 54 |
2 files changed, 108 insertions, 1 deletions
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml index 159d56d..c42a4fd 100644 --- a/documentation/poky-ref-manual/ref-features.xml +++ b/documentation/poky-ref-manual/ref-features.xml @@ -171,6 +171,61 @@ </itemizedlist> </para> </section> + + <section id='ref-features-backfill'> + <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>. + </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> + + <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>. + </para> + </section> </chapter> <!-- diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml index 2baed37..ca89a43 100644 --- a/documentation/poky-ref-manual/ref-variables.xml +++ b/documentation/poky-ref-manual/ref-variables.xml @@ -483,7 +483,35 @@ <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm> <glossdef> - <para>The features of the distribution.</para> + <para>The features enabled for the distribution. + For a list of valid features, see the + "<link linkend='ref-features-distro'>Distro</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm> + <glossdef> + <para>Features to be added to + <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> + if not also present in + <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>. + See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for + more information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm> + <glossdef> + <para>Features from + <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename> + that should not be added to + <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>. + See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for + more information. + </para> </glossdef> </glossentry> @@ -1536,6 +1564,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm> + <glossdef> + <para>Features to be added to + <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> + if not also present in + <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>. + See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for + more information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm> + <glossdef> + <para>Features from + <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename> + that should not be added to + <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>. + See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for + more information. + </para> + </glossdef> + </glossentry> + <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm> <glossdef> <para>The email address of the distribution maintainer.</para> |