summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/ref-features.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/poky-ref-manual/ref-features.xml')
-rw-r--r--documentation/poky-ref-manual/ref-features.xml114
1 files changed, 53 insertions, 61 deletions
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
index 8c3304aa72..f4d755666d 100644
--- a/documentation/poky-ref-manual/ref-features.xml
+++ b/documentation/poky-ref-manual/ref-features.xml
@@ -176,27 +176,39 @@
176 <title>Feature Backfilling</title> 176 <title>Feature Backfilling</title>
177 177
178 <para> 178 <para>
179 Sometimes it is necessary to add a new feature option to the 179 Sometimes it is necessary to control functionality enabled by features
180 that are listed with
180 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> 181 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
181 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> 182 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
182 lists and have it affect all configurations. 183 For example, some functionality exists that is enabled
183 For example, suppose new functionality is developed and it must be enabled
184 by default for all configurations. 184 by default for all configurations.
185 For these cases, the metadata, as shipped with the Yocto Project, ensures
186 the feature is "backfilled" into all the specific distro
187 and machine configurations.
188 You can see how this is done by finding the
189 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
190 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
191 variables in the <filename>meta/conf/bitbake.conf</filename> file.
185 </para> 192 </para>
186 193
187 <para> 194 <para>
188 Sometimes it is also necessary to disable (remove) a feature 195 Because certain functionality is enabled across all configurations as
189 option, which has been previously enabled by default, from the machine or distro lists. 196 described in the previous paragraph, it also becomes necessary
190 For example, perhaps a mandatory distro feature becomes optional. 197 to give the developer the ability to disable (remove) a feature
191 How can you remove the feature option from the 198 from a particular configuration.
192 <filename>DISTRO_FEATURES</filename> list 199 For example, suppose you have a machine feature that needs to be
193 without disturbing all the existing configurations that still 200 disabled but the metadata has backfilled it across all configurations as enabled.
194 might need the feature? 201 You need to be able to remove the feature from your configuration's
195 Feature backfilling allows you "backfill" the feature into all the 202 <filename>MACHINE_FEATURES</filename>
196 configurations and then lets you selectively prevent the feature from 203 without disturbing existing configurations that still
197 being added to <filename>MACHINE_FEATURES</filename> and 204 might need the functionality?
198 <filename>DISTRO_FEATURES</filename> lists. 205 </para>
199 </para> 206
207 <para>
208 Feature backfilling allows you to selectively prevent a feature from
209 being backfilled to <filename>MACHINE_FEATURES</filename>,
210 <filename>DISTRO_FEATURES</filename>, or both.
211 </para>
200 212
201 <para> 213 <para>
202 Here are two examples to help illustrate feature backfilling: 214 Here are two examples to help illustrate feature backfilling:
@@ -204,58 +216,38 @@
204 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: 216 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
205 Previously, PulseAudio support was enabled within the Qt and 217 Previously, PulseAudio support was enabled within the Qt and
206 GStreamer frameworks. 218 GStreamer frameworks.
207 However, you might need to disable the feature for your 219 Because of this, the feature is backfilled and thus
208 distro. 220 enabled for all distros through the
221 <filename>DISTRO_FEATURES_BACKFILL</filename>
222 variable in the <filename>meta/conf/bitbake.conf</filename> file.
223 However, your distro needs to disable the feature.
209 You can disable the feature without affecting 224 You can disable the feature without affecting
210 other existing distro configurations that need PulseAudio support 225 other existing distro configurations that need PulseAudio support
211 by doing the following: 226 by adding "pulseaudio" to
212 <itemizedlist> 227 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
213 <listitem><para>Add "pulseaudio" to 228 in your distro's <filename>.conf</filename> file.
214 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> 229 Adding the feature to this variable when it also
215 within your <filename>meta/conf/bitbake.conf</filename> file. 230 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
216 Adding the feature option causes the build process 231 variable prevents the build system from adding the feature to
217 to automatically add "pulseaudio" to 232 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
218 <filename>DISTRO_FEATURES</filename> without the need to 233 the feature for that particular distro.</para></listitem>
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
225 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
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 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
234 Previously, real time clock (RTC) support was enabled for all 235 Previously, real time clock (RTC) support was enabled for all
235 target devices. 236 target devices.
237 Because of this, the feature is backfilled and thus enabled
238 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
239 variable in the <filename>meta/conf/bitbake.conf</filename> file.
236 However, your target device does not have this capability. 240 However, your target device does not have this capability.
237 You can disable RTC support for your device without 241 You can disable RTC support for your device without
238 affecting other machines where RTC support should remain enabled 242 affecting other machines that need RTC support
239 by doing the following: 243 by adding the feature to your machine's
240 <itemizedlist> 244 <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
241 <listitem><para>Add "rtc" to <filename>MACHINE_FEATURES_BACKFILL</filename> 245 list in the machine's <filename>.conf</filename> file.
242 within your <filename>meta/conf/bitbake.conf</filename>. 246 Adding the feature to this variable when it also
243 Adding the feature option causes the build process 247 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
244 to automatically add "rtc" to 248 variable prevents the build system from adding the feature to
245 <filename>MACHINE_FEATURES</filename> without the need to 249 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
246 update any machine configurations. 250 disabling RTC support for that particular machine.</para></listitem>
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
251 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
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> 251 </itemizedlist>
260 </para> 252 </para>
261 </section> 253 </section>