sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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>
This commit is contained in:
Paul Eggleton 2012-10-10 14:38:35 -07:00 committed by Richard Purdie
parent 5abdefd89c
commit 88924d6dea
2 changed files with 108 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
documentation/poky-ref-manual/ref-features.xml
View File

@ -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>
<!--

54
documentation/poky-ref-manual/ref-variables.xml
View File

@ -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>