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