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