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.xml124
1 files changed, 62 insertions, 62 deletions
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
index ec70547314..77c31275ae 100644
--- a/documentation/poky-ref-manual/ref-features.xml
+++ b/documentation/poky-ref-manual/ref-features.xml
@@ -7,7 +7,7 @@
7 7
8 <para> 8 <para>
9 Features provide a mechanism for working out which packages 9 Features provide a mechanism for working out which packages
10 should be included in the generated images. 10 should be included in the generated images.
11 Distributions can select which features they want to support through the 11 Distributions can select which features they want to support through the
12 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> 12 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
13 variable, which is set in the <filename>poky.conf</filename> distribution configuration file. 13 variable, which is set in the <filename>poky.conf</filename> distribution configuration file.
@@ -19,16 +19,16 @@
19 19
20 <para> 20 <para>
21 These two variables combine to work out which kernel modules, 21 These two variables combine to work out which kernel modules,
22 utilities, and other packages to include. 22 utilities, and other packages to include.
23 A given distribution can support a selected subset of features so some machine features might not 23 A given distribution can support a selected subset of features so some machine features might not
24 be included if the distribution itself does not support them. 24 be included if the distribution itself does not support them.
25 </para> 25 </para>
26 26
27 <para> 27 <para>
28 One method you can use to determine which recipes are checking to see if a 28 One method you can use to determine which recipes are checking to see if a
29 particular feature is contained or not is to <filename>grep</filename> through 29 particular feature is contained or not is to <filename>grep</filename> through
30 the metadata for the feature. 30 the metadata for the feature.
31 Here is an example that discovers the recipes whose build is potentially 31 Here is an example that discovers the recipes whose build is potentially
32 changed based on a given feature: 32 changed based on a given feature:
33 <literallayout class='monospaced'> 33 <literallayout class='monospaced'>
34 $ cd $HOME/poky 34 $ cd $HOME/poky
@@ -38,21 +38,21 @@
38 38
39 <para> 39 <para>
40 This chapter provides a reference of shipped machine and distro features 40 This chapter provides a reference of shipped machine and distro features
41 you can include as part of the image, a reference on image types you can 41 you can include as part of the image, a reference on image types you can
42 build, and a reference on feature backfilling. 42 build, and a reference on feature backfilling.
43 </para> 43 </para>
44 44
45 45
46 <section id='ref-features-distro'> 46 <section id='ref-features-distro'>
47 <title>Distro</title> 47 <title>Distro</title>
48 48
49 <para> 49 <para>
50 The items below are features you can use with 50 The items below are features you can use with
51 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. 51 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
52 Features do not have a one-to-one correspondence to packages, and they can 52 Features do not have a one-to-one correspondence to packages, and they can
53 go beyond simply controlling the installation of a package or packages. 53 go beyond simply controlling the installation of a package or packages.
54 Sometimes a feature can influence how certain recipes are built. 54 Sometimes a feature can influence how certain recipes are built.
55 For example, a feature might determine whether a particular configure option 55 For example, a feature might determine whether a particular configure option
56 is specified within <filename>do_configure</filename> for a particular 56 is specified within <filename>do_configure</filename> for a particular
57 recipe. 57 recipe.
58 </para> 58 </para>
@@ -60,7 +60,7 @@
60 <para> 60 <para>
61 This list only represents features as shipped with the Yocto Project metadata: 61 This list only represents features as shipped with the Yocto Project metadata:
62 <itemizedlist> 62 <itemizedlist>
63 <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility 63 <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility
64 kernel modules will be installed if available).</para></listitem> 64 kernel modules will be installed if available).</para></listitem>
65 <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only) 65 <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only)
66 </para></listitem> 66 </para></listitem>
@@ -69,7 +69,7 @@
69 </para></listitem> 69 </para></listitem>
70 <listitem><para><emphasis>irda:</emphasis> Include Irda support 70 <listitem><para><emphasis>irda:</emphasis> Include Irda support
71 </para></listitem> 71 </para></listitem>
72 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be 72 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be
73 loaded during boot). 73 loaded during boot).
74 </para></listitem> 74 </para></listitem>
75 <listitem><para><emphasis>pci:</emphasis> Include PCI bus support 75 <listitem><para><emphasis>pci:</emphasis> Include PCI bus support
@@ -103,12 +103,12 @@
103 <title>Machine</title> 103 <title>Machine</title>
104 104
105 <para> 105 <para>
106 The items below are features you can use with 106 The items below are features you can use with
107 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. 107 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
108 Features do not have a one-to-one correspondence to packages, and they can 108 Features do not have a one-to-one correspondence to packages, and they can
109 go beyond simply controlling the installation of a package or packages. 109 go beyond simply controlling the installation of a package or packages.
110 Sometimes a feature can influence how certain recipes are built. 110 Sometimes a feature can influence how certain recipes are built.
111 For example, a feature might determine whether a particular configure option 111 For example, a feature might determine whether a particular configure option
112 is specified within <filename>do_configure</filename> for a particular 112 is specified within <filename>do_configure</filename> for a particular
113 recipe. 113 recipe.
114 </para> 114 </para>
@@ -154,7 +154,7 @@
154 <title>Images</title> 154 <title>Images</title>
155 155
156 <para> 156 <para>
157 The contents of images generated by the OpenEmbedded build system can be controlled by the 157 The contents of images generated by the OpenEmbedded build system can be controlled by the
158 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> 158 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
159 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> 159 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
160 variables that you typically configure in your image recipes. 160 variables that you typically configure in your image recipes.
@@ -164,48 +164,48 @@
164 </para> 164 </para>
165 165
166 <para> 166 <para>
167 Current list of 167 Current list of
168 <filename>IMAGE_FEATURES</filename> contains the following: 168 <filename>IMAGE_FEATURES</filename> contains the following:
169 <itemizedlist> 169 <itemizedlist>
170 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot. 170 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
171 By default, this screen is provided by <filename>psplash</filename>, which does 171 By default, this screen is provided by <filename>psplash</filename>, which does
172 allow customization. 172 allow customization.
173 If you prefer to use an alternative splash screen package, you can do so by 173 If you prefer to use an alternative splash screen package, you can do so by
174 setting the <filename>SPLASH</filename> variable 174 setting the <filename>SPLASH</filename> variable
175 to a different package name (or names) within the image recipe or at the distro 175 to a different package name (or names) within the image recipe or at the distro
176 configuration level.</para></listitem> 176 configuration level.</para></listitem>
177 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal 177 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
178 SSH server. 178 SSH server.
179 </para></listitem> 179 </para></listitem>
180 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server, 180 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
181 which is more full-featured than Dropbear. 181 which is more full-featured than Dropbear.
182 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server 182 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
183 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take 183 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
184 precedence and Dropbear will not be installed.</para></listitem> 184 precedence and Dropbear will not be installed.</para></listitem>
185 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem> 185 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
186 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a 186 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
187 minimal environment.</para></listitem> 187 minimal environment.</para></listitem>
188 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment. 188 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
189 </para></listitem> 189 </para></listitem>
190 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device. 190 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
191 </para></listitem> 191 </para></listitem>
192 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as 192 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
193 <filename>strace</filename> and <filename>gdb</filename>. 193 <filename>strace</filename> and <filename>gdb</filename>.
194 </para></listitem> 194 </para></listitem>
195 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as 195 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
196 <filename>oprofile</filename>, <filename>exmap</filename>, and 196 <filename>oprofile</filename>, <filename>exmap</filename>, and
197 <filename>LTTng</filename>.</para></listitem> 197 <filename>LTTng</filename>.</para></listitem>
198 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g. 198 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
199 touchscreen debugging).</para></listitem> 199 touchscreen debugging).</para></listitem>
200 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem> 200 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
201 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and 201 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
202 extra library links) for all packages installed in a given image.</para></listitem> 202 extra library links) for all packages installed in a given image.</para></listitem>
203 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development 203 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
204 packages (i.e. static libraries containing <filename>*.a</filename> files) for all 204 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
205 packages installed in a given image.</para></listitem> 205 packages installed in a given image.</para></listitem>
206 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages 206 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
207 installed in a given image.</para></listitem> 207 installed in a given image.</para></listitem>
208 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages 208 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
209 installed in a given image.</para></listitem> 209 installed in a given image.</para></listitem>
210 </itemizedlist> 210 </itemizedlist>
211 </para> 211 </para>
@@ -218,30 +218,30 @@
218 Sometimes it is necessary in the OpenEmbedded build system to extend 218 Sometimes it is necessary in the OpenEmbedded build system to extend
219 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> 219 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
220 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> 220 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
221 to control functionality that was previously enabled and not able 221 to control functionality that was previously enabled and not able
222 to be disabled. 222 to be disabled.
223 For these cases, we need to add an 223 For these cases, we need to add an
224 additional feature item to appear in one of these variables, 224 additional feature item to appear in one of these variables,
225 but we do not want to force developers who have existing values 225 but we do not want to force developers who have existing values
226 of the variables in their configuration to add the new feature 226 of the variables in their configuration to add the new feature
227 in order to retain the same overall level of functionality. 227 in order to retain the same overall level of functionality.
228 Thus, the OpenEmbedded build system has a mechanism to 228 Thus, the OpenEmbedded build system has a mechanism to
229 automatically "backfill" these added features into existing 229 automatically "backfill" these added features into existing
230 distro or machine configurations. 230 distro or machine configurations.
231 You can see the list of features for which this is done by 231 You can see the list of features for which this is done by
232 finding the 232 finding the
233 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> 233 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
234 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link> 234 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
235 variables in the <filename>meta/conf/bitbake.conf</filename> file. 235 variables in the <filename>meta/conf/bitbake.conf</filename> file.
236 </para> 236 </para>
237 237
238 <para> 238 <para>
239 Because such features are backfilled by default into all 239 Because such features are backfilled by default into all
240 configurations as described in the previous paragraph, developers 240 configurations as described in the previous paragraph, developers
241 who wish to disable the new features need to be able to selectively 241 who wish to disable the new features need to be able to selectively
242 prevent the backfilling from occurring. 242 prevent the backfilling from occurring.
243 They can do this by adding the undesired feature or features to the 243 They can do this by adding the undesired feature or features to the
244 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> 244 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
245 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link> 245 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
246 variables for distro features and machine features respectively. 246 variables for distro features and machine features respectively.
247 </para> 247 </para>
@@ -249,46 +249,46 @@
249 <para> 249 <para>
250 Here are two examples to help illustrate feature backfilling: 250 Here are two examples to help illustrate feature backfilling:
251 <itemizedlist> 251 <itemizedlist>
252 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: 252 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
253 Previously, PulseAudio support was enabled within the Qt and 253 Previously, PulseAudio support was enabled within the Qt and
254 GStreamer frameworks. 254 GStreamer frameworks.
255 Because of this, the feature is backfilled and thus 255 Because of this, the feature is backfilled and thus
256 enabled for all distros through the 256 enabled for all distros through the
257 <filename>DISTRO_FEATURES_BACKFILL</filename> 257 <filename>DISTRO_FEATURES_BACKFILL</filename>
258 variable in the <filename>meta/conf/bitbake.conf</filename> file. 258 variable in the <filename>meta/conf/bitbake.conf</filename> file.
259 However, your distro needs to disable the feature. 259 However, your distro needs to disable the feature.
260 You can disable the feature without affecting 260 You can disable the feature without affecting
261 other existing distro configurations that need PulseAudio support 261 other existing distro configurations that need PulseAudio support
262 by adding "pulseaudio" to 262 by adding "pulseaudio" to
263 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename> 263 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
264 in your distro's <filename>.conf</filename> file. 264 in your distro's <filename>.conf</filename> file.
265 Adding the feature to this variable when it also 265 Adding the feature to this variable when it also
266 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename> 266 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
267 variable prevents the build system from adding the feature to 267 variable prevents the build system from adding the feature to
268 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling 268 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
269 the feature for that particular distro.</para></listitem> 269 the feature for that particular distro.</para></listitem>
270 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>: 270 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
271 Previously, real time clock (RTC) support was enabled for all 271 Previously, real time clock (RTC) support was enabled for all
272 target devices. 272 target devices.
273 Because of this, the feature is backfilled and thus enabled 273 Because of this, the feature is backfilled and thus enabled
274 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename> 274 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
275 variable in the <filename>meta/conf/bitbake.conf</filename> file. 275 variable in the <filename>meta/conf/bitbake.conf</filename> file.
276 However, your target device does not have this capability. 276 However, your target device does not have this capability.
277 You can disable RTC support for your device without 277 You can disable RTC support for your device without
278 affecting other machines that need RTC support 278 affecting other machines that need RTC support
279 by adding the feature to your machine's 279 by adding the feature to your machine's
280 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename> 280 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
281 list in the machine's <filename>.conf</filename> file. 281 list in the machine's <filename>.conf</filename> file.
282 Adding the feature to this variable when it also 282 Adding the feature to this variable when it also
283 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename> 283 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
284 variable prevents the build system from adding the feature to 284 variable prevents the build system from adding the feature to
285 your configuration's <filename>MACHINE_FEATURES</filename>, effectively 285 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
286 disabling RTC support for that particular machine.</para></listitem> 286 disabling RTC support for that particular machine.</para></listitem>
287 </itemizedlist> 287 </itemizedlist>
288 </para> 288 </para>
289 </section> 289 </section>
290</chapter> 290</chapter>
291 291
292<!-- 292<!--
293vim: expandtab tw=80 ts=4 spell spelllang=en_gb 293vim: expandtab tw=80 ts=4 spell spelllang=en_gb
294--> 294-->