summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPaul Eggleton <paul.eggleton@linux.intel.com>2012-10-10 14:38:35 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-10-15 14:45:12 +0100
commit88924d6deae40513354919eae60d32a0c173bb7f (patch)
tree3ddb500d352d24cdba7cda34f669cd383adfc79c
parent5abdefd89c5e4a999ccbd55a516b9267412a2719 (diff)
downloadpoky-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.xml55
-rw-r--r--documentation/poky-ref-manual/ref-variables.xml54
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 159d56dabc..c42a4fd807 100644
--- a/documentation/poky-ref-manual/ref-features.xml
+++ b/documentation/poky-ref-manual/ref-features.xml
@@ -171,6 +171,61 @@
171 </itemizedlist> 171 </itemizedlist>
172 </para> 172 </para>
173 </section> 173 </section>
174
175 <section id='ref-features-backfill'>
176 <title>Feature Backfilling</title>
177
178 <para>
179 Sometimes, it is necessary for a new feature to be added to control existing
180 functionality that was previously enabled by default and not able to be disabled.
181 In order to ensure that the feature remains enabled for users with existing
182 configurations that upgrade to a new version of the core metadata without that
183 configuration having to be changed, while still allowing others who want to turn
184 the feature off to do so, the backfilling mechanism was introduced.
185 This
186 functionality is available for <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
187 and <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
188 </para>
189
190 <para>
191 An example is the "pulseaudio" distro feature.
192 Previously, PulseAudio support
193 was enabled within the Qt and GStreamer frameworks.
194 However some users desired
195 to be able to disable this.
196 To allow this to be disabled without affecting
197 existing configurations in which PulseAudio support should remain enabled,
198 "pulseaudio" was added to
199 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
200 within <filename>meta/conf/bitbake.conf</filename>.
201 This means that "pulseaudio"
202 is automatically added to <filename>DISTRO_FEATURES</filename> without the distro
203 configuration needing to be updated to do so itself.
204 Those who do not want PulseAudio support can add "pulseaudio" to
205 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>
206 in their distro <filename>.conf</filename> file and this will disable adding "pulseaudio" to
207 <filename>DISTRO_FEATURES</filename>.
208 </para>
209
210 <para>
211 Another example is the "rtc" machine feature.
212 Previously, real time clock (RTC)
213 support was enabled for all target devices.
214 However certain targets do not have
215 this capability.
216 To allow this to be disabled by such machines without affecting
217 other machines in which RTC support should remain enabled, "rtc" was added to
218 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
219 within <filename>meta/conf/bitbake.conf</filename>.
220 This means that "rtc"
221 is automatically added to <filename>MACHINE_FEATURES</filename> without the
222 machine configuration needing to be updated to do so itself.
223 For machines that not need RTC support can add "rtc" to
224 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>
225 in their machine <filename>.conf</filename> file and this will disable adding "rtc" to
226 <filename>MACHINE_FEATURES</filename>.
227 </para>
228 </section>
174</chapter> 229</chapter>
175 230
176<!-- 231<!--
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 2baed3788c..ca89a432fc 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -483,7 +483,35 @@
483 483
484 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm> 484 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
485 <glossdef> 485 <glossdef>
486 <para>The features of the distribution.</para> 486 <para>The features enabled for the distribution.
487 For a list of valid features, see the
488 "<link linkend='ref-features-distro'>Distro</link>"
489 section.
490 </para>
491 </glossdef>
492 </glossentry>
493
494 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
495 <glossdef>
496 <para>Features to be added to
497 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
498 if not also present in
499 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
500 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
501 more information.
502 </para>
503 </glossdef>
504 </glossentry>
505
506 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
507 <glossdef>
508 <para>Features from
509 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
510 that should not be added to
511 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>.
512 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
513 more information.
514 </para>
487 </glossdef> 515 </glossdef>
488 </glossentry> 516 </glossentry>
489 517
@@ -1536,6 +1564,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1536 </glossdef> 1564 </glossdef>
1537 </glossentry> 1565 </glossentry>
1538 1566
1567 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
1568 <glossdef>
1569 <para>Features to be added to
1570 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
1571 if not also present in
1572 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1573 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1574 more information.
1575 </para>
1576 </glossdef>
1577 </glossentry>
1578
1579 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
1580 <glossdef>
1581 <para>Features from
1582 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
1583 that should not be added to
1584 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
1585 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1586 more information.
1587 </para>
1588 </glossdef>
1589 </glossentry>
1590
1539 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm> 1591 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
1540 <glossdef> 1592 <glossdef>
1541 <para>The email address of the distribution maintainer.</para> 1593 <para>The email address of the distribution maintainer.</para>