path: root/documentation
diff options
authorScott Rifenbark <>2012-10-18 17:12:10 (GMT)
committerRichard Purdie <>2012-10-19 16:38:55 (GMT)
commitb7e951a842d06f07d9aad20d39129c9522468ce3 (patch)
tree27c68abc51467e2f9ae82150755220b18752c4c5 /documentation
parentcc345014baaf8edb99234eb3573d96c8013a7e14 (diff)
documentation: poky-ref-manual - updates to feature backfill section.
(From yocto-docs rev: aaf1156398033d50add5ac3944aa575917c7f7de) Signed-off-by: Scott Rifenbark <> Signed-off-by: Richard Purdie <>
Diffstat (limited to 'documentation')
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 @@
176 <title>Feature Backfilling</title> 176 <title>Feature Backfilling</title>
177 177
178 <para> 178 <para>
179 Sometimes, it is necessary for a new feature to be added to control existing 179 Sometimes it is necessary to add a new feature option to the
180 functionality that was previously enabled by default and not able to be disabled. 180 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
181 In order to ensure that the feature remains enabled for users with existing 181 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
182 configurations that upgrade to a new version of the core metadata without that 182 lists and have it affect all configurations.
183 configuration having to be changed, while still allowing others who want to turn 183 For example, suppose new functionality is developed and it must be enabled
184 the feature off to do so, the backfilling mechanism was introduced. 184 by default for all configurations.
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> 185 </para>
189 186
190 <para> 187 <para>
191 An example is the "pulseaudio" distro feature. 188 Sometimes it is also necessary to disable (remove) a feature
192 Previously, PulseAudio support 189 option, which has been previously enabled by default, from the machine or distro lists.
193 was enabled within the Qt and GStreamer frameworks. 190 For example, perhaps a mandatory distro feature becomes optional.
194 However some users desired 191 How can you remove the feature option from the
195 to be able to disable this. 192 <filename>DISTRO_FEATURES</filename> list
196 To allow this to be disabled without affecting 193 without disturbing all the existing configurations that still
197 existing configurations in which PulseAudio support should remain enabled, 194 might need the feature?
198 "pulseaudio" was added to 195 Feature backfilling allows you "backfill" the feature into all the
199 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename> 196 configurations and then lets you selectively prevent the feature from
200 within <filename>meta/conf/bitbake.conf</filename>. 197 being added to <filename>MACHINE_FEATURES</filename> and
201 This means that "pulseaudio" 198 <filename>DISTRO_FEATURES</filename> lists.
202 is automatically added to <filename>DISTRO_FEATURES</filename> without the distro 199 </para>
203 configuration needing to be updated to do so itself.
204 Those who do not want PulseAudio support can add "pulseaudio" to
206 in their distro <filename>.conf</filename> file and this will disable adding "pulseaudio" to
207 <filename>DISTRO_FEATURES</filename>.
208 </para>
209 200
210 <para> 201 <para>
211 Another example is the "rtc" machine feature. 202 Here are two examples to help illustrate feature backfilling:
212 Previously, real time clock (RTC) 203 <itemizedlist>
213 support was enabled for all target devices. 204 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
214 However certain targets do not have 205 Previously, PulseAudio support was enabled within the Qt and
215 this capability. 206 GStreamer frameworks.
216 To allow this to be disabled by such machines without affecting 207 However, you might need to disable the feature for your
217 other machines in which RTC support should remain enabled, "rtc" was added to 208 distro.
218 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename> 209 You can disable the feature without affecting
219 within <filename>meta/conf/bitbake.conf</filename>. 210 other existing distro configurations that need PulseAudio support
220 This means that "rtc" 211 by doing the following:
221 is automatically added to <filename>MACHINE_FEATURES</filename> without the 212 <itemizedlist>
222 machine configuration needing to be updated to do so itself. 213 <listitem><para>Add "pulseaudio" to
223 For machines that not need RTC support can add "rtc" to 214 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
224 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename> 215 within your <filename>meta/conf/bitbake.conf</filename> file.
225 in their machine <filename>.conf</filename> file and this will disable adding "rtc" to 216 Adding the feature option causes the build process
226 <filename>MACHINE_FEATURES</filename>. 217 to automatically add "pulseaudio" to
218 <filename>DISTRO_FEATURES</filename> without the need to
219 update any distro configurations.
220 This step by itself enables the feature
221 for all distros and consequently ensures that existing
222 configurations that still need the feature are
223 undisturbed.</para></listitem>
224 <listitem><para>Add "pulseaudio" to
226 in your distro's <filename>.conf</filename> file.
227 Adding the feature option to this variable when it also
228 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
229 variable prevents the build system from adding the feature option to
230 <filename>DISTRO_FEATURES</filename>, effectively disabling
231 the feature for that particular distro.</para></listitem>
232 </itemizedlist></para></listitem>
233 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
234 Previously, real time clock (RTC) support was enabled for all
235 target devices.
236 However, your target device does not have this capability.
237 You can disable RTC support for your device without
238 affecting other machines where RTC support should remain enabled
239 by doing the following:
240 <itemizedlist>
241 <listitem><para>Add "rtc" to <filename>MACHINE_FEATURES_BACKFILL</filename>
242 within your <filename>meta/conf/bitbake.conf</filename>.
243 Adding the feature option causes the build process
244 to automatically add "rtc" to
245 <filename>MACHINE_FEATURES</filename> without the need to
246 update any machine configurations.
247 This step by itself enables RTC support for all machines
248 and consequently ensures that existing configurations
249 that still need the feature are undisturbed.</para></listitem>
250 <listitem><para>Add "rtc" to
252 in your machine's <filename>.conf</filename> file.
253 Adding the feature option to this variable when it also
254 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
255 variable prevents the build system from adding the feature option to
256 <filename>MACHINE_FEATURES</filename>, effectively disabling
257 RTC support for feature that particular machine.</para></listitem>
258 </itemizedlist></para></listitem>
259 </itemizedlist>
227 </para> 260 </para>
228 </section> 261 </section>
229</chapter> 262</chapter>