blob: 31d24b8c287c7c3e5f8cc73034e328bd8cb8840b [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3********
4Features
5********
6
7This chapter provides a reference of shipped machine and distro features
8you can include as part of your image, a reference on image features you
9can select, and a reference on feature backfilling.
10
11Features provide a mechanism for working out which packages should be
12included in the generated images. Distributions can select which
13features they want to support through the ``DISTRO_FEATURES`` variable,
14which is set or appended to in a distribution's configuration file such
15as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth.
16Machine features are set in the ``MACHINE_FEATURES`` variable, which is
17set in the machine configuration file and specifies the hardware
18features for a given machine.
19
20These two variables combine to work out which kernel modules, utilities,
21and other packages to include. A given distribution can support a
22selected subset of features so some machine features might not be
23included if the distribution itself does not support them.
24
25One method you can use to determine which recipes are checking to see if
26a particular feature is contained or not is to ``grep`` through the
27:term:`Metadata` for the feature. Here is an example that
28discovers the recipes whose build is potentially changed based on a
Andrew Geisslerc926e172021-05-07 16:11:35 -050029given feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050030
31 $ cd poky
32 $ git grep 'contains.*MACHINE_FEATURES.*feature'
33
34.. _ref-features-machine:
35
36Machine Features
37================
38
39The items below are features you can use with
40:term:`MACHINE_FEATURES`. Features do not have a
41one-to-one correspondence to packages, and they can go beyond simply
42controlling the installation of a package or packages. Sometimes a
43feature can influence how certain recipes are built. For example, a
44feature might determine whether a particular configure option is
45specified within the :ref:`ref-tasks-configure` task
46for a particular recipe.
47
48This feature list only represents features as shipped with the Yocto
49Project metadata:
50
51- *acpi:* Hardware has ACPI (x86/x86_64 only)
52
53- *alsa:* Hardware has ALSA audio drivers
54
55- *apm:* Hardware uses APM (or APM emulation)
56
57- *bluetooth:* Hardware has integrated BT
58
59- *efi:* Support for booting through EFI
60
61- *ext2:* Hardware HDD or Microdrive
62
63- *keyboard:* Hardware has a keyboard
64
65- *pcbios:* Support for booting through BIOS
66
67- *pci:* Hardware has a PCI bus
68
69- *pcmcia:* Hardware has PCMCIA or CompactFlash sockets
70
71- *phone:* Mobile phone (voice) support
72
73- *qvga:* Machine has a QVGA (320x240) display
74
75- *rtc:* Machine has a Real-Time Clock
76
77- *screen:* Hardware has a screen
78
79- *serial:* Hardware has serial support (usually RS232)
80
81- *touchscreen:* Hardware has a touchscreen
82
83- *usbgadget:* Hardware is USB gadget device capable
84
85- *usbhost:* Hardware is USB Host capable
86
87- *vfat:* FAT file system support
88
89- *wifi:* Hardware has integrated WiFi
90
91.. _ref-features-distro:
92
93Distro Features
94===============
95
96The items below are features you can use with
97:term:`DISTRO_FEATURES` to enable features across
98your distribution. Features do not have a one-to-one correspondence to
99packages, and they can go beyond simply controlling the installation of
100a package or packages. In most cases, the presence or absence of a
101feature translates to the appropriate option supplied to the configure
102script during the :ref:`ref-tasks-configure` task for
103the recipes that optionally support the feature.
104
105Some distro features are also machine features. These select features
106make sense to be controlled both at the machine and distribution
107configuration level. See the
108:term:`COMBINED_FEATURES` variable for more
109information.
110
111This list only represents features as shipped with the Yocto Project
112metadata:
113
114- *alsa:* Include ALSA support (OSS compatibility kernel modules
115 installed if available).
116
117- *api-documentation:* Enables generation of API documentation during
118 recipe builds. The resulting documentation is added to SDK tarballs
119 when the ``bitbake -c populate_sdk`` command is used. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600120 ":ref:`sdk-manual/appendix-customizing-standard:adding api documentation to the standard sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121 section in the Yocto Project Application Development and the
122 Extensible Software Development Kit (eSDK) manual.
123
124- *bluetooth:* Include bluetooth support (integrated BT only).
125
126- *cramfs:* Include CramFS support.
127
128- *directfb:* Include DirectFB support.
129
130- *ext2:* Include tools for supporting for devices with internal
131 HDD/Microdrive for storing files (instead of Flash only devices).
132
133- *ipsec:* Include IPSec support.
134
135- *ipv6:* Include IPv6 support.
136
137- *keyboard:* Include keyboard support (e.g. keymaps will be loaded
138 during boot).
139
140- *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the
141 target.
142
143- *nfs:* Include NFS client support (for mounting NFS exports on
144 device).
145
146- *opengl:* Include the Open Graphics Library, which is a
147 cross-language, multi-platform application programming interface used
148 for rendering two and three-dimensional graphics.
149
150- *pci:* Include PCI bus support.
151
152- *pcmcia:* Include PCMCIA/CompactFlash support.
153
154- *ppp:* Include PPP dialup support.
155
156- *ptest:* Enables building the package tests where supported by
157 individual recipes. For more information on package tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600158 ":ref:`dev-manual/common-tasks:testing packages with ptest`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500159 in the Yocto Project Development Tasks Manual.
160
161- *smbfs:* Include SMB networks client support (for mounting
162 Samba/Microsoft Windows shares on device).
163
164- *systemd:* Include support for this ``init`` manager, which is a full
165 replacement of for ``init`` with parallel starting of services,
166 reduced shell overhead, and other features. This ``init`` manager is
167 used by many distributions.
168
169- *usbgadget:* Include USB Gadget Device support (for USB
170 networking/serial/storage).
171
172- *usbhost:* Include USB Host support (allows to connect external
173 keyboard, mouse, storage, network etc).
174
175- *usrmerge:* Merges the ``/bin``, ``/sbin``, ``/lib``, and ``/lib64``
176 directories into their respective counterparts in the ``/usr``
177 directory to provide better package and application compatibility.
178
179- *wayland:* Include the Wayland display server protocol and the
180 library that supports it.
181
182- *wifi:* Include WiFi support (integrated only).
183
184- *x11:* Include the X server and libraries.
185
186.. _ref-features-image:
187
188Image Features
189==============
190
191The contents of images generated by the OpenEmbedded build system can be
192controlled by the :term:`IMAGE_FEATURES` and
193:term:`EXTRA_IMAGE_FEATURES` variables that
194you typically configure in your image recipes. Through these variables,
195you can add several different predefined packages such as development
196utilities or packages with debug information needed to investigate
197application problems or profile applications.
198
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700199Here are the image features available for all images:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500200
201- *allow-empty-password:* Allows Dropbear and OpenSSH to accept root
202 logins and logins from accounts having an empty password string.
203
204- *dbg-pkgs:* Installs debug symbol packages for all packages installed
205 in a given image.
206
207- *debug-tweaks:* Makes an image suitable for development (e.g. allows
208 root logins without passwords and enables post-installation logging).
209 See the 'allow-empty-password', 'empty-root-password', and
210 'post-install-logging' features in this list for additional
211 information.
212
213- *dev-pkgs:* Installs development packages (headers and extra library
214 links) for all packages installed in a given image.
215
216- *doc-pkgs:* Installs documentation packages for all packages
217 installed in a given image.
218
219- *empty-root-password:* Sets the root password to an empty string,
220 which allows logins with a blank password.
221
222- *package-management:* Installs package management tools and preserves
223 the package manager database.
224
225- *post-install-logging:* Enables logging postinstall script runs to
226 the ``/var/log/postinstall.log`` file on first boot of the image on
227 the target system.
228
229 .. note::
230
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500231 To make the ``/var/log`` directory on the target persistent, use the
232 :term:`VOLATILE_LOG_DIR` variable by setting it to "no".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500233
234- *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes.
235
236- *read-only-rootfs:* Creates an image whose root filesystem is
237 read-only. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600238 ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500239 section in the Yocto Project Development Tasks Manual for more
240 information.
241
242- *splash:* Enables showing a splash screen during boot. By default,
243 this screen is provided by ``psplash``, which does allow
244 customization. If you prefer to use an alternative splash screen
245 package, you can do so by setting the ``SPLASH`` variable to a
246 different package name (or names) within the image recipe or at the
247 distro configuration level.
248
249- *staticdev-pkgs:* Installs static development packages, which are
250 static libraries (i.e. ``*.a`` files), for all packages installed in
251 a given image.
252
253Some image features are available only when you inherit the
254:ref:`core-image <ref-classes-core-image>` class. The current list of
255these valid features is as follows:
256
257- *hwcodecs:* Installs hardware acceleration codecs.
258
259- *nfs-server:* Installs an NFS server.
260
261- *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and
262 ``LTTng``. For general information on user-space tools, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600263 :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500264
265- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server.
266
267- *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more
268 full-featured than Dropbear. Note that if both the OpenSSH SSH server
269 and the Dropbear minimal SSH server are present in
270 ``IMAGE_FEATURES``, then OpenSSH will take precedence and Dropbear
271 will not be installed.
272
273- *tools-debug:* Installs debugging tools such as ``strace`` and
274 ``gdb``. For information on GDB, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600275 ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500276 in the Yocto Project Development Tasks Manual. For information on
Andrew Geissler09209ee2020-12-13 08:44:15 -0600277 tracing and profiling, see the :doc:`/profile-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500278
279- *tools-sdk:* Installs a full SDK that runs on the device.
280
281- *tools-testapps:* Installs device testing tools (e.g. touchscreen
282 debugging).
283
284- *x11:* Installs the X server.
285
286- *x11-base:* Installs the X server with a minimal environment.
287
288- *x11-sato:* Installs the OpenedHand Sato environment.
289
290.. _ref-features-backfill:
291
292Feature Backfilling
293===================
294
295Sometimes it is necessary in the OpenEmbedded build system to extend
296:term:`MACHINE_FEATURES` or
297:term:`DISTRO_FEATURES` to control functionality
298that was previously enabled and not able to be disabled. For these
299cases, we need to add an additional feature item to appear in one of
300these variables, but we do not want to force developers who have
301existing values of the variables in their configuration to add the new
302feature in order to retain the same overall level of functionality.
303Thus, the OpenEmbedded build system has a mechanism to automatically
304"backfill" these added features into existing distro or machine
305configurations. You can see the list of features for which this is done
306by finding the
307:term:`DISTRO_FEATURES_BACKFILL` and
308:term:`MACHINE_FEATURES_BACKFILL`
309variables in the ``meta/conf/bitbake.conf`` file.
310
311Because such features are backfilled by default into all configurations
312as described in the previous paragraph, developers who wish to disable
313the new features need to be able to selectively prevent the backfilling
314from occurring. They can do this by adding the undesired feature or
315features to the
316:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
317or
318:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
319variables for distro features and machine features respectively.
320
321Here are two examples to help illustrate feature backfilling:
322
323- *The "pulseaudio" distro feature option*: Previously, PulseAudio
324 support was enabled within the Qt and GStreamer frameworks. Because
325 of this, the feature is backfilled and thus enabled for all distros
326 through the ``DISTRO_FEATURES_BACKFILL`` variable in the
327 ``meta/conf/bitbake.conf`` file. However, your distro needs to
328 disable the feature. You can disable the feature without affecting
329 other existing distro configurations that need PulseAudio support by
330 adding "pulseaudio" to ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` in
331 your distro's ``.conf`` file. Adding the feature to this variable
332 when it also exists in the ``DISTRO_FEATURES_BACKFILL`` variable
333 prevents the build system from adding the feature to your
334 configuration's ``DISTRO_FEATURES``, effectively disabling the
335 feature for that particular distro.
336
337- *The "rtc" machine feature option*: Previously, real time clock (RTC)
338 support was enabled for all target devices. Because of this, the
339 feature is backfilled and thus enabled for all machines through the
340 ``MACHINE_FEATURES_BACKFILL`` variable in the
341 ``meta/conf/bitbake.conf`` file. However, your target device does not
342 have this capability. You can disable RTC support for your device
343 without affecting other machines that need RTC support by adding the
344 feature to your machine's ``MACHINE_FEATURES_BACKFILL_CONSIDERED``
345 list in the machine's ``.conf`` file. Adding the feature to this
346 variable when it also exists in the ``MACHINE_FEATURES_BACKFILL``
347 variable prevents the build system from adding the feature to your
348 configuration's ``MACHINE_FEATURES``, effectively disabling RTC
349 support for that particular machine.