diff options
Diffstat (limited to 'documentation/poky-ref-manual/ref-features.xml')
-rw-r--r-- | documentation/poky-ref-manual/ref-features.xml | 124 |
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 | <!-- |
293 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb | 293 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb |
294 | --> | 294 | --> |