summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-features.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-features.xml')
-rw-r--r--documentation/ref-manual/ref-features.xml420
1 files changed, 420 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000000..230cabd155
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,420 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-features'>
6 <title>Features</title>
7
8 <para>
9 This chapter provides a reference of shipped machine and distro features
10 you can include as part of your image, a reference on image features you can
11 select, and a reference on feature backfilling.
12 </para>
13
14 <para>
15 Features provide a mechanism for working out which packages
16 should be included in the generated images.
17 Distributions can select which features they want to support through the
18 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
19 variable, which is set or appended to in a distribution's configuration file such as
20 <filename>poky.conf</filename>,
21 <filename>poky-tiny.conf</filename>,
22 <filename>poky-lsb.conf</filename> and so forth.
23 Machine features are set in the
24 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
25 variable, which is set in the machine configuration file and
26 specifies the hardware features for a given machine.
27 </para>
28
29 <para>
30 These two variables combine to work out which kernel modules,
31 utilities, and other packages to include.
32 A given distribution can support a selected subset of features so some machine features might not
33 be included if the distribution itself does not support them.
34 </para>
35
36 <para>
37 One method you can use to determine which recipes are checking to see if a
38 particular feature is contained or not is to <filename>grep</filename> through
39 the <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
40 for the feature.
41 Here is an example that discovers the recipes whose build is potentially
42 changed based on a given feature:
43 <literallayout class='monospaced'>
44 $ cd poky
45 $ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>'
46 </literallayout>
47 </para>
48
49 <section id='ref-features-machine'>
50 <title>Machine Features</title>
51
52 <para>
53 The items below are features you can use with
54 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
55 Features do not have a one-to-one correspondence to packages, and they can
56 go beyond simply controlling the installation of a package or packages.
57 Sometimes a feature can influence how certain recipes are built.
58 For example, a feature might determine whether a particular configure option
59 is specified within the
60 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
61 task for a particular recipe.
62 </para>
63
64 <para>
65 This feature list only represents features as shipped with the Yocto Project metadata:
66 <itemizedlist>
67 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
68 </para></listitem>
69 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
70 </para></listitem>
71 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
72 </para></listitem>
73 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
74 </para></listitem>
75 <listitem><para><emphasis>efi:</emphasis> Support for booting through EFI
76 </para></listitem>
77 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
78 </para></listitem>
79 <listitem><para><emphasis>irda:</emphasis> Hardware has IrDA support
80 </para></listitem>
81 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
82 </para></listitem>
83 <listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS
84 </para></listitem>
85 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
86 </para></listitem>
87 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
88 </para></listitem>
89 <listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support
90 </para></listitem>
91 <listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display
92 </para></listitem>
93 <listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock
94 </para></listitem>
95 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
96 </para></listitem>
97 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
98 </para></listitem>
99 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
100 </para></listitem>
101 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
102 </para></listitem>
103 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
104 </para></listitem>
105 <listitem><para><emphasis>vfat:</emphasis> FAT file system support
106 </para></listitem>
107 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
108 </para></listitem>
109 </itemizedlist>
110 </para>
111 </section>
112
113 <section id='ref-features-distro'>
114 <title>Distro Features</title>
115
116 <para>
117 The items below are features you can use with
118 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
119 to enable features across your distribution.
120 Features do not have a one-to-one correspondence to packages,
121 and they can go beyond simply controlling the installation of a
122 package or packages.
123 In most cases, the presence or absence of a feature translates to
124 the appropriate option supplied to the configure script during the
125 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
126 task for the recipes that optionally
127 support the feature.
128 </para>
129
130 <para>
131 Some distro features are also machine features.
132 These select features make sense to be controlled both at
133 the machine and distribution configuration level.
134 See the
135 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></ulink>
136 variable for more information.
137 </para>
138
139 <para>
140 This list only represents features as shipped with the Yocto Project metadata:
141 <itemizedlist>
142 <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
143 (OSS compatibility kernel modules installed if available).
144 </para></listitem>
145 <listitem><para><emphasis>bluetooth:</emphasis> Include
146 bluetooth support (integrated BT only).</para></listitem>
147 <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
148 support.</para></listitem>
149 <listitem><para><emphasis>directfb:</emphasis>
150 Include DirectFB support.
151 </para></listitem>
152 <listitem><para><emphasis>ext2:</emphasis> Include tools for
153 supporting for devices with internal HDD/Microdrive for
154 storing files (instead of Flash only devices).
155 </para></listitem>
156 <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
157 support.</para></listitem>
158 <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
159 </para></listitem>
160 <listitem><para><emphasis>irda:</emphasis> Include IrDA support.
161 </para></listitem>
162 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
163 support (e.g. keymaps will be loaded during boot).
164 </para></listitem>
165 <listitem><para><emphasis>nfs:</emphasis> Include NFS client
166 support (for mounting NFS exports on device).
167 </para></listitem>
168 <listitem><para><emphasis>opengl:</emphasis>
169 Include the Open Graphics Library, which is a
170 cross-language, multi-platform application programming
171 interface used for rendering two and three-dimensional
172 graphics.</para></listitem>
173 <listitem><para><emphasis>pci:</emphasis> Include PCI bus
174 support.</para></listitem>
175 <listitem><para><emphasis>pcmcia:</emphasis> Include
176 PCMCIA/CompactFlash support.</para></listitem>
177 <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
178 support.</para></listitem>
179 <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
180 client support (for mounting Samba/Microsoft Windows shares
181 on device).</para></listitem>
182 <listitem><para><emphasis>systemd:</emphasis> Include support
183 for this <filename>init</filename> manager, which is a full
184 replacement of for <filename>init</filename> with parallel
185 starting of services, reduced shell overhead, and other
186 features.
187 This <filename>init</filename> manager is used by many
188 distributions.</para></listitem>
189 <listitem><para><emphasis>usbgadget:</emphasis> Include USB
190 Gadget Device support (for USB networking/serial/storage).
191 </para></listitem>
192 <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
193 support (allows to connect external keyboard, mouse,
194 storage, network etc).</para></listitem>
195 <listitem><para><emphasis>wayland:</emphasis> Include the
196 Wayland display server protocol and the library that
197 supports it.</para></listitem>
198 <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
199 (integrated only).</para></listitem>
200 <listitem><para><emphasis>x11:</emphasis> Include the X server
201 and libraries.</para></listitem>
202 </itemizedlist>
203 </para>
204 </section>
205
206 <section id='ref-features-image'>
207 <title>Image Features</title>
208
209 <para>
210 The contents of images generated by the OpenEmbedded build system
211 can be controlled by the
212 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
213 and
214 <link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link>
215 variables that you typically configure in your image recipes.
216 Through these variables, you can add several different
217 predefined packages such as development utilities or packages with
218 debug information needed to investigate application problems or
219 profile applications.
220 </para>
221
222 <para>
223 The following image features are available for all images:
224 <itemizedlist>
225 <listitem><para><emphasis>dbg-pkgs:</emphasis>
226 Installs debug symbol packages for all packages installed
227 in a given image.
228 </para></listitem>
229 <listitem><para><emphasis>debug-tweaks:</emphasis>
230 Makes an image suitable for development (e.g.
231 allows root logins without passwords).
232 </para></listitem>
233 <listitem><para><emphasis>dev-pkgs:</emphasis>
234 Installs development packages (headers and extra library
235 links) for all packages installed in a given image.
236 </para></listitem>
237 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs
238 documentation packages for all packages installed in a
239 given image.
240 </para></listitem>
241 <listitem><para><emphasis>package-management:</emphasis>
242 Installs package management tools and preserves the package
243 manager database.
244 </para></listitem>
245 <listitem><para><emphasis>ptest-pkgs:</emphasis>
246 Installs ptest packages for all ptest-enabled recipes.
247 </para></listitem>
248 <listitem><para><emphasis>read-only-rootfs:</emphasis>
249 Creates an image whose root filesystem is read-only.
250 See the
251 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
252 section in the Yocto Project Development Manual for more
253 information.
254 </para></listitem>
255 <listitem><para><emphasis>splash:</emphasis>
256 Enables showing a splash screen during boot.
257 By default, this screen is provided by
258 <filename>psplash</filename>, which does allow
259 customization.
260 If you prefer to use an alternative splash screen package,
261 you can do so by setting the <filename>SPLASH</filename>
262 variable to a different package name (or names) within the
263 image recipe or at the distro configuration level.
264 </para></listitem>
265 <listitem><para><emphasis>staticdev-pkgs:</emphasis>
266 Installs static development packages, which are
267 static libraries (i.e. <filename>*.a</filename> files), for
268 all packages installed in a given image.
269 </para></listitem>
270 </itemizedlist>
271 </para>
272
273 <para>
274 Some image features are available only when you inherit the
275 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
276 class.
277 The current list of these valid features is as follows:
278 <itemizedlist>
279 <listitem><para><emphasis>eclipse-debug:</emphasis> Provides
280 Eclipse remote debugging support.
281 </para></listitem>
282 <listitem><para><emphasis>hwcodecs:</emphasis> Installs
283 hardware acceleration codecs.
284 </para></listitem>
285 <listitem><para><emphasis>nfs-server:</emphasis>
286 Installs an NFS server.
287 </para></listitem>
288 <listitem><para><emphasis>qt4-pkgs:</emphasis>
289 Supports Qt4/X11 and demo applications.
290 </para></listitem>
291 <listitem><para><emphasis>ssh-server-dropbear:</emphasis>
292 Installs the Dropbear minimal SSH server.
293 </para></listitem>
294 <listitem><para><emphasis>ssh-server-openssh:</emphasis>
295 Installs the OpenSSH SSH server, which is more
296 full-featured than Dropbear.
297 Note that if both the OpenSSH SSH server and the Dropbear
298 minimal SSH server are present in
299 <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
300 precedence and Dropbear will not be installed.
301 </para></listitem>
302 <listitem><para><emphasis>tools-debug:</emphasis>
303 Installs debugging tools such as
304 <filename>strace</filename> and <filename>gdb</filename>.
305 For information on GDB, see the
306 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
307 section in the Yocto Project Development Manual.
308 For information on tracing and profiling, see the
309 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
310 </para></listitem>
311 <listitem><para><emphasis>tools-profile:</emphasis>
312 Installs profiling tools such as
313 <filename>oprofile</filename>, <filename>exmap</filename>,
314 and <filename>LTTng</filename>.
315 For general information on user-space tools, see the
316 "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>"
317 section in the Yocto Project Application Developer's
318 Guide.
319 </para></listitem>
320 <listitem><para><emphasis>tools-sdk:</emphasis>
321 Installs a full SDK that runs on the device.
322 </para></listitem>
323 <listitem><para><emphasis>tools-testapps:</emphasis>
324 Installs device testing tools (e.g. touchscreen debugging).
325 </para></listitem>
326 <listitem><para><emphasis>x11:</emphasis>
327 Installs the X server.
328 </para></listitem>
329 <listitem><para><emphasis>x11-base:</emphasis>
330 Installs the X server with a minimal environment.
331 </para></listitem>
332 <listitem><para><emphasis>x11-sato:</emphasis>
333 Installs the OpenedHand Sato environment.
334 </para></listitem>
335 </itemizedlist>
336 </para>
337
338 </section>
339
340 <section id='ref-features-backfill'>
341 <title>Feature Backfilling</title>
342
343 <para>
344 Sometimes it is necessary in the OpenEmbedded build system to extend
345 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
346 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
347 to control functionality that was previously enabled and not able
348 to be disabled.
349 For these cases, we need to add an
350 additional feature item to appear in one of these variables,
351 but we do not want to force developers who have existing values
352 of the variables in their configuration to add the new feature
353 in order to retain the same overall level of functionality.
354 Thus, the OpenEmbedded build system has a mechanism to
355 automatically "backfill" these added features into existing
356 distro or machine configurations.
357 You can see the list of features for which this is done by
358 finding the
359 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
360 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
361 variables in the <filename>meta/conf/bitbake.conf</filename> file.
362 </para>
363
364 <para>
365 Because such features are backfilled by default into all
366 configurations as described in the previous paragraph, developers
367 who wish to disable the new features need to be able to selectively
368 prevent the backfilling from occurring.
369 They can do this by adding the undesired feature or features to the
370 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
371 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
372 variables for distro features and machine features respectively.
373 </para>
374
375 <para>
376 Here are two examples to help illustrate feature backfilling:
377 <itemizedlist>
378 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
379 Previously, PulseAudio support was enabled within the Qt and
380 GStreamer frameworks.
381 Because of this, the feature is backfilled and thus
382 enabled for all distros through the
383 <filename>DISTRO_FEATURES_BACKFILL</filename>
384 variable in the <filename>meta/conf/bitbake.conf</filename> file.
385 However, your distro needs to disable the feature.
386 You can disable the feature without affecting
387 other existing distro configurations that need PulseAudio support
388 by adding "pulseaudio" to
389 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
390 in your distro's <filename>.conf</filename> file.
391 Adding the feature to this variable when it also
392 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
393 variable prevents the build system from adding the feature to
394 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
395 the feature for that particular distro.</para></listitem>
396 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
397 Previously, real time clock (RTC) support was enabled for all
398 target devices.
399 Because of this, the feature is backfilled and thus enabled
400 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
401 variable in the <filename>meta/conf/bitbake.conf</filename> file.
402 However, your target device does not have this capability.
403 You can disable RTC support for your device without
404 affecting other machines that need RTC support
405 by adding the feature to your machine's
406 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
407 list in the machine's <filename>.conf</filename> file.
408 Adding the feature to this variable when it also
409 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
410 variable prevents the build system from adding the feature to
411 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
412 disabling RTC support for that particular machine.</para></listitem>
413 </itemizedlist>
414 </para>
415 </section>
416</chapter>
417
418<!--
419vim: expandtab tw=80 ts=4 spell spelllang=en_gb
420-->