blob: cb74df6dad9be02c6f78de0f274b98688c27438c [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!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
Brad Bishopd7bf8c12018-02-25 22:55:05 -050039 the <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050040 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
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500135 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500136 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>
Brad Bishop37a0e4d2017-12-04 01:01:44 -0500145 <listitem><para><emphasis>api-documentation:</emphasis>
146 Enables generation of API documentation during recipe
147 builds.
148 The resulting documentation is added to SDK tarballs
149 when the
150 <filename>bitbake -c populate_sdk</filename> command
151 is used.
152 See the
153 "<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding API Documentation to the Standard SDK</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500154 section in the Yocto Project Application Development and
155 the Extensible Software Development Kit (eSDK) manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -0500156 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500157 <listitem><para><emphasis>bluetooth:</emphasis> Include
158 bluetooth support (integrated BT only).</para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600159 <listitem><para><emphasis>bluez5:</emphasis> Include
160 BlueZ Version 5, which provides core Bluetooth layers and
161 protocols support.
162 <note>
163 The default value for the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400164 <filename>DISTRO FEATURES</filename> variable includes
165 "bluetooth", which causes bluez5 to be backfilled in
166 for bluetooth support.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600167 If you do not want bluez5 backfilled and would rather
168 use bluez4, you need to use the
169 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
170 variable as follows:
171 <literallayout class='monospaced'>
172 DISTRO_FEATURES_BACKFILL_CONSIDERED = "bluez5"
173 </literallayout>
174 Setting this variable tells the OpenEmbedded build
175 system that you have considered but ruled
176 out using the bluez5 feature and that bluez4 will be
177 used.
178 </note>
179 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500180 <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
181 support.</para></listitem>
182 <listitem><para><emphasis>directfb:</emphasis>
183 Include DirectFB support.
184 </para></listitem>
185 <listitem><para><emphasis>ext2:</emphasis> Include tools for
186 supporting for devices with internal HDD/Microdrive for
187 storing files (instead of Flash only devices).
188 </para></listitem>
189 <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
190 support.</para></listitem>
191 <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
192 </para></listitem>
193 <listitem><para><emphasis>irda:</emphasis> Include IrDA support.
194 </para></listitem>
195 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
196 support (e.g. keymaps will be loaded during boot).
197 </para></listitem>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500198 <listitem><para><emphasis>ldconfig:</emphasis>
199 Include support for ldconfig and
200 <filename>ld.so.conf</filename> on the target.
201 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500202 <listitem><para><emphasis>nfs:</emphasis> Include NFS client
203 support (for mounting NFS exports on device).
204 </para></listitem>
205 <listitem><para><emphasis>opengl:</emphasis>
206 Include the Open Graphics Library, which is a
207 cross-language, multi-platform application programming
208 interface used for rendering two and three-dimensional
209 graphics.</para></listitem>
210 <listitem><para><emphasis>pci:</emphasis> Include PCI bus
211 support.</para></listitem>
212 <listitem><para><emphasis>pcmcia:</emphasis> Include
213 PCMCIA/CompactFlash support.</para></listitem>
214 <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
215 support.</para></listitem>
216 <listitem><para><emphasis>ptest:</emphasis> Enables building
217 the package tests where supported by individual recipes.
218 For more information on package tests, see the
219 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500220 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500221 </para></listitem>
222 <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
223 client support (for mounting Samba/Microsoft Windows shares
224 on device).</para></listitem>
225 <listitem><para><emphasis>systemd:</emphasis> Include support
226 for this <filename>init</filename> manager, which is a full
227 replacement of for <filename>init</filename> with parallel
228 starting of services, reduced shell overhead, and other
229 features.
230 This <filename>init</filename> manager is used by many
231 distributions.</para></listitem>
232 <listitem><para><emphasis>usbgadget:</emphasis> Include USB
233 Gadget Device support (for USB networking/serial/storage).
234 </para></listitem>
235 <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
236 support (allows to connect external keyboard, mouse,
237 storage, network etc).</para></listitem>
238 <listitem><para><emphasis>wayland:</emphasis> Include the
239 Wayland display server protocol and the library that
240 supports it.</para></listitem>
241 <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
242 (integrated only).</para></listitem>
243 <listitem><para><emphasis>x11:</emphasis> Include the X server
244 and libraries.</para></listitem>
245 </itemizedlist>
246 </para>
247 </section>
248
249 <section id='ref-features-image'>
250 <title>Image Features</title>
251
252 <para>
253 The contents of images generated by the OpenEmbedded build system
254 can be controlled by the
255 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
256 and
257 <link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link>
258 variables that you typically configure in your image recipes.
259 Through these variables, you can add several different
260 predefined packages such as development utilities or packages with
261 debug information needed to investigate application problems or
262 profile applications.
263 </para>
264
265 <para>
266 The following image features are available for all images:
267 <itemizedlist>
268 <listitem><para><emphasis>allow-empty-password:</emphasis>
269 Allows Dropbear and OpenSSH to accept root logins
270 and logins from accounts having an empty password string.
271 </para></listitem>
272 <listitem><para><emphasis>dbg-pkgs:</emphasis>
273 Installs debug symbol packages for all packages installed
274 in a given image.
275 </para></listitem>
276 <listitem><para><emphasis>debug-tweaks:</emphasis>
277 Makes an image suitable for development (e.g.
278 allows root logins without passwords and enables
279 post-installation logging).
280 See the 'allow-empty-password', 'empty-root-password',
281 and 'post-install-logging' features in this list for
282 additional information.
283 </para></listitem>
284 <listitem><para><emphasis>dev-pkgs:</emphasis>
285 Installs development packages (headers and extra library
286 links) for all packages installed in a given image.
287 </para></listitem>
288 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs
289 documentation packages for all packages installed in a
290 given image.
291 </para></listitem>
292 <listitem><para><emphasis>empty-root-password:</emphasis>
293 Sets the root password to an empty string, which allows
294 logins with a blank password.
295 </para></listitem>
296 <listitem><para><emphasis>package-management:</emphasis>
297 Installs package management tools and preserves the package
298 manager database.
299 </para></listitem>
300 <listitem><para><emphasis>post-install-logging:</emphasis>
301 Enables logging postinstall script runs to
302 the <filename>/var/log/postinstall.log</filename> file
303 on first boot of the image on the target system.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500304 <note>
305 To make the <filename>/var/log</filename> directory
306 on the target persistent, use the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500307 <link linkend='var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500308 variable by setting it to "no".
309 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500310 </para></listitem>
311 <listitem><para><emphasis>ptest-pkgs:</emphasis>
312 Installs ptest packages for all ptest-enabled recipes.
313 </para></listitem>
314 <listitem><para><emphasis>read-only-rootfs:</emphasis>
315 Creates an image whose root filesystem is read-only.
316 See the
317 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500318 section in the Yocto Project Development Tasks Manual for
319 more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500320 </para></listitem>
321 <listitem><para><emphasis>splash:</emphasis>
322 Enables showing a splash screen during boot.
323 By default, this screen is provided by
324 <filename>psplash</filename>, which does allow
325 customization.
326 If you prefer to use an alternative splash screen package,
327 you can do so by setting the <filename>SPLASH</filename>
328 variable to a different package name (or names) within the
329 image recipe or at the distro configuration level.
330 </para></listitem>
331 <listitem><para><emphasis>staticdev-pkgs:</emphasis>
332 Installs static development packages, which are
333 static libraries (i.e. <filename>*.a</filename> files), for
334 all packages installed in a given image.
335 </para></listitem>
336 </itemizedlist>
337 </para>
338
339 <para>
340 Some image features are available only when you inherit the
341 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
342 class.
343 The current list of these valid features is as follows:
344 <itemizedlist>
345 <listitem><para><emphasis>eclipse-debug:</emphasis> Provides
346 Eclipse remote debugging support.
347 </para></listitem>
348 <listitem><para><emphasis>hwcodecs:</emphasis> Installs
349 hardware acceleration codecs.
350 </para></listitem>
351 <listitem><para><emphasis>nfs-server:</emphasis>
352 Installs an NFS server.
353 </para></listitem>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500354 <listitem><para><emphasis>perf:</emphasis>
355 Installs profiling tools such as
356 <filename>perf</filename>, <filename>systemtap</filename>,
357 and <filename>LTTng</filename>.
358 For general information on user-space tools, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500359 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
360 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500361 </para></listitem>
362 <listitem><para><emphasis>ssh-server-dropbear:</emphasis>
363 Installs the Dropbear minimal SSH server.
364 </para></listitem>
365 <listitem><para><emphasis>ssh-server-openssh:</emphasis>
366 Installs the OpenSSH SSH server, which is more
367 full-featured than Dropbear.
368 Note that if both the OpenSSH SSH server and the Dropbear
369 minimal SSH server are present in
370 <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
371 precedence and Dropbear will not be installed.
372 </para></listitem>
373 <listitem><para><emphasis>tools-debug:</emphasis>
374 Installs debugging tools such as
375 <filename>strace</filename> and <filename>gdb</filename>.
376 For information on GDB, see the
377 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500378 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500379 For information on tracing and profiling, see the
380 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
381 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500382 <listitem><para><emphasis>tools-sdk:</emphasis>
383 Installs a full SDK that runs on the device.
384 </para></listitem>
385 <listitem><para><emphasis>tools-testapps:</emphasis>
386 Installs device testing tools (e.g. touchscreen debugging).
387 </para></listitem>
388 <listitem><para><emphasis>x11:</emphasis>
389 Installs the X server.
390 </para></listitem>
391 <listitem><para><emphasis>x11-base:</emphasis>
392 Installs the X server with a minimal environment.
393 </para></listitem>
394 <listitem><para><emphasis>x11-sato:</emphasis>
395 Installs the OpenedHand Sato environment.
396 </para></listitem>
397 </itemizedlist>
398 </para>
399
400 </section>
401
402 <section id='ref-features-backfill'>
403 <title>Feature Backfilling</title>
404
405 <para>
406 Sometimes it is necessary in the OpenEmbedded build system to extend
407 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
408 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
409 to control functionality that was previously enabled and not able
410 to be disabled.
411 For these cases, we need to add an
412 additional feature item to appear in one of these variables,
413 but we do not want to force developers who have existing values
414 of the variables in their configuration to add the new feature
415 in order to retain the same overall level of functionality.
416 Thus, the OpenEmbedded build system has a mechanism to
417 automatically "backfill" these added features into existing
418 distro or machine configurations.
419 You can see the list of features for which this is done by
420 finding the
421 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
422 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
423 variables in the <filename>meta/conf/bitbake.conf</filename> file.
424 </para>
425
426 <para>
427 Because such features are backfilled by default into all
428 configurations as described in the previous paragraph, developers
429 who wish to disable the new features need to be able to selectively
430 prevent the backfilling from occurring.
431 They can do this by adding the undesired feature or features to the
432 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
433 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
434 variables for distro features and machine features respectively.
435 </para>
436
437 <para>
438 Here are two examples to help illustrate feature backfilling:
439 <itemizedlist>
440 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
441 Previously, PulseAudio support was enabled within the Qt and
442 GStreamer frameworks.
443 Because of this, the feature is backfilled and thus
444 enabled for all distros through the
445 <filename>DISTRO_FEATURES_BACKFILL</filename>
446 variable in the <filename>meta/conf/bitbake.conf</filename> file.
447 However, your distro needs to disable the feature.
448 You can disable the feature without affecting
449 other existing distro configurations that need PulseAudio support
450 by adding "pulseaudio" to
451 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
452 in your distro's <filename>.conf</filename> file.
453 Adding the feature to this variable when it also
454 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
455 variable prevents the build system from adding the feature to
456 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
457 the feature for that particular distro.</para></listitem>
458 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
459 Previously, real time clock (RTC) support was enabled for all
460 target devices.
461 Because of this, the feature is backfilled and thus enabled
462 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
463 variable in the <filename>meta/conf/bitbake.conf</filename> file.
464 However, your target device does not have this capability.
465 You can disable RTC support for your device without
466 affecting other machines that need RTC support
467 by adding the feature to your machine's
468 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
469 list in the machine's <filename>.conf</filename> file.
470 Adding the feature to this variable when it also
471 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
472 variable prevents the build system from adding the feature to
473 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
474 disabling RTC support for that particular machine.</para></listitem>
475 </itemizedlist>
476 </para>
477 </section>
478</chapter>
479
480<!--
481vim: expandtab tw=80 ts=4 spell spelllang=en_gb
482-->