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- *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 120 ":ref:`sdk-manual/appendix-customizing-standard:adding api documentation to the standard sdk`" 121 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 158 ":ref:`dev-manual/common-tasks:testing packages with ptest`" section 159 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 199Here are the image features available for all images: 200 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 231 To make the ``/var/log`` directory on the target persistent, use the 232 :term:`VOLATILE_LOG_DIR` variable by setting it to "no". 233 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 238 ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`" 239 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 263 :doc:`/sdk-manual/index` manual. 264 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 :term:`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 275 ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section 276 in the Yocto Project Development Tasks Manual. For information on 277 tracing and profiling, see the :doc:`/profile-manual/index`. 278 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 :term:`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 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in 331 your distro's ``.conf`` file. Adding the feature to this variable 332 when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable 333 prevents the build system from adding the feature to your 334 configuration's :term:`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 :term:`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 :term:`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 :term:`MACHINE_FEATURES_BACKFILL` 347 variable prevents the build system from adding the feature to your 348 configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC 349 support for that particular machine. 350