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 :ref:`ref-features-backfill`. 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- *bluetooth:* Hardware has integrated BT 56 57- *efi:* Support for booting through EFI 58 59- *ext2:* Hardware HDD or Microdrive 60 61- *keyboard:* Hardware has a keyboard 62 63- *numa:* Hardware has non-uniform memory access 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- *qemu-usermode:* QEMU can support user-mode emulation for this machine 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. Appropriate options 106must be supplied, and enabling/disabling :term:`PACKAGECONFIG` for the 107concerned packages is one way of supplying such options. 108 109Some distro features are also machine features. These select features 110make sense to be controlled both at the machine and distribution 111configuration level. See the 112:term:`COMBINED_FEATURES` variable for more 113information. 114 115.. note:: 116 117 :term:`DISTRO_FEATURES` is normally independent of kernel configuration, 118 so if a feature specified in :term:`DISTRO_FEATURES` also relies on 119 support in the kernel, you will also need to ensure that support is 120 enabled in the kernel configuration. 121 122This list only represents features as shipped with the Yocto Project 123metadata, as extra layers can define their own: 124 125- *3g:* Include support for cellular data. 126 127- *acl:* Include :wikipedia:`Access Control List <Access-control_list>` support. 128 129- *alsa:* Include :wikipedia:`Advanced Linux Sound Architecture <Advanced_Linux_Sound_Architecture>` 130 support (OSS compatibility kernel modules installed if available). 131 132- *api-documentation:* Enables generation of API documentation during 133 recipe builds. The resulting documentation is added to SDK tarballs 134 when the ``bitbake -c populate_sdk`` command is used. See the 135 ":ref:`sdk-manual/appendix-customizing-standard:adding api documentation to the standard sdk`" 136 section in the Yocto Project Application Development and the 137 Extensible Software Development Kit (eSDK) manual. 138 139- *bluetooth:* Include bluetooth support (integrated BT only). 140 141- *cramfs:* Include CramFS support. 142 143- *debuginfod:* Include support for getting ELF debugging information through 144 a :ref:`debuginfod <dev-manual/debugging:using the debuginfod server method>` 145 server. 146 147- *directfb:* Include DirectFB support. 148 149- *ext2:* Include tools for supporting for devices with internal 150 HDD/Microdrive for storing files (instead of Flash only devices). 151 152- *gobject-introspection-data:* Include data to support 153 `GObject Introspection <https://gi.readthedocs.io/en/latest/>`__. 154 155- *ipsec:* Include IPSec support. 156 157- *ipv4:* Include IPv4 support. 158 159- *ipv6:* Include IPv6 support. 160 161- *keyboard:* Include keyboard support (e.g. keymaps will be loaded 162 during boot). 163 164- *minidebuginfo:* Add minimal debug symbols :ref:`(minidebuginfo)<dev-manual/debugging:enabling minidebuginfo>` 165 to binary files containing, allowing ``coredumpctl`` and ``gdb`` to show symbolicated stack traces. 166 167- *multiarch:* Enable building applications with multiple architecture 168 support. 169 170- *ld-is-gold:* Use the :wikipedia:`gold <Gold_(linker)>` 171 linker instead of the standard GCC linker (bfd). 172 173- *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the 174 target. 175 176- *lto:* Enable `Link-Time Optimisation <https://gcc.gnu.org/wiki/LinkTimeOptimization>`__. 177 178- *nfc:* Include support for 179 `Near Field Communication <https://en.wikipedia.org/wiki/Near-field_communication>`__. 180 181- *nfs:* Include NFS client support (for mounting NFS exports on 182 device). 183 184- *nls:* Include National Language Support (NLS). 185 186- *opengl:* Include the Open Graphics Library, which is a 187 cross-language, multi-platform application programming interface used 188 for rendering two and three-dimensional graphics. 189 190- *overlayfs:* Include `OverlayFS <https://docs.kernel.org/filesystems/overlayfs.html>`__ 191 support. 192 193- *pam:* Include :wikipedia:`Pluggable Authentication Module (PAM) <Pluggable_authentication_module>` 194 support. 195 196- *pci:* Include PCI bus support. 197 198- *pcmcia:* Include PCMCIA/CompactFlash support. 199 200- *polkit:* Include :wikipedia:`Polkit <Polkit>` support. 201 202- *ppp:* Include PPP dialup support. 203 204- *ptest:* Enables building the package tests where supported by 205 individual recipes. For more information on package tests, see the 206 ":ref:`dev-manual/packages:testing packages with ptest`" section 207 in the Yocto Project Development Tasks Manual. 208 209- *pulseaudio:* Include support for 210 `PulseAudio <https://www.freedesktop.org/wiki/Software/PulseAudio/>`__. 211 212- *selinux:* Include support for 213 :wikipedia:`Security-Enhanced Linux (SELinux) <Security-Enhanced_Linux>` 214 (requires `meta-selinux <https://layers.openembedded.org/layerindex/layer/meta-selinux/>`__). 215 216- *seccomp:* Enables building applications with 217 :wikipedia:`seccomp <Seccomp>` support, to 218 allow them to strictly restrict the system calls that they are allowed 219 to invoke. 220 221- *smbfs:* Include SMB networks client support (for mounting 222 Samba/Microsoft Windows shares on device). 223 224- *systemd:* Include support for this ``init`` manager, which is a full 225 replacement of for ``init`` with parallel starting of services, 226 reduced shell overhead, and other features. This ``init`` manager is 227 used by many distributions. 228 229- *systemd-resolved:* Include support and use ``systemd-resolved`` as the 230 main DNS name resolver in ``glibc`` Name Service Switch. This is a DNS 231 resolver daemon from ``systemd``. 232 233- *usbgadget:* Include USB Gadget Device support (for USB 234 networking/serial/storage). 235 236- *usbhost:* Include USB Host support (allows to connect external 237 keyboard, mouse, storage, network etc). 238 239- *usrmerge:* Merges the ``/bin``, ``/sbin``, ``/lib``, and ``/lib64`` 240 directories into their respective counterparts in the ``/usr`` 241 directory to provide better package and application compatibility. 242 243- *vfat:* Include :wikipedia:`FAT filesystem <File_Allocation_Table>` 244 support. 245 246- *vulkan:* Include support for the :wikipedia:`Vulkan API <Vulkan>`. 247 248- *wayland:* Include the Wayland display server protocol and the 249 library that supports it. 250 251- *wifi:* Include WiFi support (integrated only). 252 253- *x11:* Include the X server and libraries. 254 255- *xattr:* Include support for 256 :wikipedia:`extended file attributes <Extended_file_attributes>`. 257 258- *zeroconf:* Include support for 259 `zero configuration networking <https://en.wikipedia.org/wiki/Zero-configuration_networking>`__. 260 261.. _ref-features-image: 262 263Image Features 264============== 265 266The contents of images generated by the OpenEmbedded build system can be 267controlled by the :term:`IMAGE_FEATURES` and 268:term:`EXTRA_IMAGE_FEATURES` variables that 269you typically configure in your image recipes. Through these variables, 270you can add several different predefined packages such as development 271utilities or packages with debug information needed to investigate 272application problems or profile applications. 273 274The image features available for all images are: 275 276- *allow-empty-password:* Allows Dropbear and OpenSSH to accept 277 logins from accounts having an empty password string. 278 279- *allow-root-login:* Allows Dropbear and OpenSSH to accept root logins. 280 281- *dbg-pkgs:* Installs debug symbol packages for all packages installed 282 in a given image. 283 284- *debug-tweaks:* Makes an image suitable for development (e.g. allows 285 root logins, logins without passwords ---including root ones, and enables 286 post-installation logging). See the ``allow-empty-password``, 287 ``allow-root-login``, ``empty-root-password``, and ``post-install-logging`` 288 features in this list for additional information. 289 290- *dev-pkgs:* Installs development packages (headers and extra library 291 links) for all packages installed in a given image. 292 293- *doc-pkgs:* Installs documentation packages for all packages 294 installed in a given image. 295 296- *empty-root-password:* This feature or ``debug-tweaks`` is required if 297 you want to allow root login with an empty password. If these features 298 are not present in :term:`IMAGE_FEATURES`, a non-empty password is 299 forced in ``/etc/passwd`` and ``/etc/shadow`` if such files exist. 300 301 .. note:: 302 ``empty-root-password`` doesn't set an empty root password by itself. 303 You get an initial empty root password thanks to the 304 :oe_git:`base-passwd </openembedded-core/tree/meta/recipes-core/base-passwd/>` 305 and :oe_git:`shadow </openembedded-core/tree/meta/recipes-extended/shadow/>` 306 recipes, and the presence of ``empty-root-password`` or ``debug-tweaks`` 307 just disables the mechanism which forces an non-empty password for the 308 root user. 309 310- *lic-pkgs:* Installs license packages for all packages installed in a 311 given image. 312 313- *overlayfs-etc:* Configures the ``/etc`` directory to be in ``overlayfs``. 314 This allows to store device specific information elsewhere, especially 315 if the root filesystem is configured to be read-only. 316 317- *package-management:* Installs package management tools and preserves 318 the package manager database. 319 320- *post-install-logging:* Enables logging postinstall script runs to 321 the ``/var/log/postinstall.log`` file on first boot of the image on 322 the target system. 323 324 .. note:: 325 326 To make the ``/var/log`` directory on the target persistent, use the 327 :term:`VOLATILE_LOG_DIR` variable by setting it to "no". 328 329- *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes. 330 331- *read-only-rootfs:* Creates an image whose root filesystem is 332 read-only. See the 333 ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`" 334 section in the Yocto Project Development Tasks Manual for more 335 information. 336 337- *read-only-rootfs-delayed-postinsts:* when specified in conjunction 338 with ``read-only-rootfs``, specifies that post-install scripts are 339 still permitted (this assumes that the root filesystem will be made 340 writeable for the first boot; this feature does not do anything to 341 ensure that - it just disables the check for post-install scripts.) 342 343- *serial-autologin-root:* when specified in conjunction with 344 ``empty-root-password`` will automatically login as root on the 345 serial console. This of course opens up a security hole if the 346 serial console is potentially accessible to an attacker, so use 347 with caution. 348 349- *splash:* Enables showing a splash screen during boot. By default, 350 this screen is provided by ``psplash``, which does allow 351 customization. If you prefer to use an alternative splash screen 352 package, you can do so by setting the :term:`SPLASH` variable to a 353 different package name (or names) within the image recipe or at the 354 distro configuration level. 355 356- *stateless-rootfs:*: specifies that the image should be created as 357 stateless - when using ``systemd``, ``systemctl-native`` will not 358 be run on the image, leaving the image for population at runtime by 359 systemd. 360 361- *staticdev-pkgs:* Installs static development packages, which are 362 static libraries (i.e. ``*.a`` files), for all packages installed in 363 a given image. 364 365Some image features are available only when you inherit the 366:ref:`ref-classes-core-image` class. The current list of 367these valid features is as follows: 368 369- *hwcodecs:* Installs hardware acceleration codecs. 370 371- *nfs-server:* Installs an NFS server. 372 373- *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and 374 ``LTTng``. For general information on user-space tools, see the 375 :doc:`/sdk-manual/index` manual. 376 377- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server. 378 379 .. note:: 380 381 As of the 4.1 release, the ``ssh-server-dropbear`` feature also 382 recommends the ``openssh-sftp-server`` package, which by default 383 will be pulled into the image. This is because recent versions of 384 the OpenSSH ``scp`` client now use the SFTP protocol, and thus 385 require an SFTP server to be present to connect to. However, if 386 you wish to use the Dropbear ssh server `without` the SFTP server 387 installed, you can either remove ``ssh-server-dropbear`` from 388 ``IMAGE_FEATURES`` and add ``dropbear`` to :term:`IMAGE_INSTALL` 389 instead, or alternatively still use the feature but set 390 :term:`BAD_RECOMMENDATIONS` as follows:: 391 392 BAD_RECOMMENDATIONS += "openssh-sftp-server" 393 394- *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more 395 full-featured than Dropbear. Note that if both the OpenSSH SSH server 396 and the Dropbear minimal SSH server are present in 397 :term:`IMAGE_FEATURES`, then OpenSSH will take precedence and Dropbear 398 will not be installed. 399 400- *tools-debug:* Installs debugging tools such as ``strace`` and 401 ``gdb``. For information on GDB, see the 402 ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section 403 in the Yocto Project Development Tasks Manual. For information on 404 tracing and profiling, see the :doc:`/profile-manual/index`. 405 406- *tools-sdk:* Installs a full SDK that runs on the device. 407 408- *tools-testapps:* Installs device testing tools (e.g. touchscreen 409 debugging). 410 411- *weston:* Installs Weston (reference Wayland environment). 412 413- *x11:* Installs the X server. 414 415- *x11-base:* Installs the X server with a minimal environment. 416 417- *x11-sato:* Installs the OpenedHand Sato environment. 418 419.. _ref-features-backfill: 420 421Feature Backfilling 422=================== 423 424Sometimes it is necessary in the OpenEmbedded build system to 425add new functionality to :term:`MACHINE_FEATURES` or 426:term:`DISTRO_FEATURES`, but at the same time, allow existing 427distributions or machine definitions to opt out of such new 428features, to retain the same overall level of functionality. 429 430To make this possible, the OpenEmbedded build system has a mechanism to 431automatically "backfill" features into existing distro or machine 432configurations. You can see the list of features for which this is done 433by checking the :term:`DISTRO_FEATURES_BACKFILL` and 434:term:`MACHINE_FEATURES_BACKFILL` variables in the 435``meta/conf/bitbake.conf`` file. 436 437These two variables are paired with the 438:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 439and :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` variables 440which allow distro or machine configuration maintainers to `consider` any 441added feature, and decide when they wish to keep or exclude such feature, 442thus preventing the backfilling from happening. 443 444Here are two examples to illustrate feature backfilling: 445 446- *The "pulseaudio" distro feature option*: Previously, PulseAudio support was 447 enabled within the Qt and GStreamer frameworks. Because of this, the feature 448 is now backfilled and thus enabled for all distros through the 449 :term:`DISTRO_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` 450 file. However, if your distro needs to disable the feature, you can do so 451 without affecting other existing distro configurations that need PulseAudio 452 support. You do this by adding "pulseaudio" to 453 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in your distro's ``.conf`` 454 file. So, adding the feature to this variable when it also exists in the 455 :term:`DISTRO_FEATURES_BACKFILL` variable prevents the build system from 456 adding the feature to your configuration's :term:`DISTRO_FEATURES`, 457 effectively disabling the feature for that particular distro. 458 459- *The "rtc" machine feature option*: Previously, real time clock (RTC) 460 support was enabled for all target devices. Because of this, the 461 feature is backfilled and thus enabled for all machines through the 462 :term:`MACHINE_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` 463 file. However, if your target device does not have this capability, you can 464 disable RTC support for your device without affecting other machines 465 that need RTC support. You do this by adding the "rtc" feature to the 466 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` list in your machine's ``.conf`` 467 file. So, adding the feature to this variable when it also exists in the 468 :term:`MACHINE_FEATURES_BACKFILL` variable prevents the build system from 469 adding the feature to your configuration's :term:`MACHINE_FEATURES`, 470 effectively disabling RTC support for that particular machine. 471