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- *qemu-usermode:* QEMU can support user-mode emulation for this machine 76 77- *qvga:* Machine has a QVGA (320x240) display 78 79- *rtc:* Machine has a Real-Time Clock 80 81- *screen:* Hardware has a screen 82 83- *serial:* Hardware has serial support (usually RS232) 84 85- *touchscreen:* Hardware has a touchscreen 86 87- *usbgadget:* Hardware is USB gadget device capable 88 89- *usbhost:* Hardware is USB Host capable 90 91- *vfat:* FAT file system support 92 93- *wifi:* Hardware has integrated WiFi 94 95.. _ref-features-distro: 96 97Distro Features 98=============== 99 100The items below are features you can use with 101:term:`DISTRO_FEATURES` to enable features across 102your distribution. Features do not have a one-to-one correspondence to 103packages, and they can go beyond simply controlling the installation of 104a package or packages. In most cases, the presence or absence of a 105feature translates to the appropriate option supplied to the configure 106script during the :ref:`ref-tasks-configure` task for 107the recipes that optionally support the feature. Appropriate options 108must be supplied, and enabling/disabling :term:`PACKAGECONFIG` for the 109concerned packages is one way of supplying such options. 110 111Some distro features are also machine features. These select features 112make sense to be controlled both at the machine and distribution 113configuration level. See the 114:term:`COMBINED_FEATURES` variable for more 115information. 116 117.. note:: 118 119 :term:`DISTRO_FEATURES` is normally independent of kernel configuration, 120 so if a feature specified in :term:`DISTRO_FEATURES` also relies on 121 support in the kernel, you will also need to ensure that support is 122 enabled in the kernel configuration. 123 124This list only represents features as shipped with the Yocto Project 125metadata, as extra layers can define their own: 126 127- *3g:* Include support for cellular data. 128 129- *acl:* Include :wikipedia:`Access Control List <Access-control_list>` support. 130 131- *alsa:* Include :wikipedia:`Advanced Linux Sound Architecture <Advanced_Linux_Sound_Architecture>` 132 support (OSS compatibility kernel modules installed if available). 133 134- *api-documentation:* Enables generation of API documentation during 135 recipe builds. The resulting documentation is added to SDK tarballs 136 when the ``bitbake -c populate_sdk`` command is used. See the 137 ":ref:`sdk-manual/appendix-customizing-standard:adding api documentation to the standard sdk`" 138 section in the Yocto Project Application Development and the 139 Extensible Software Development Kit (eSDK) manual. 140 141- *bluetooth:* Include bluetooth support (integrated BT only). 142 143- *cramfs:* Include CramFS support. 144 145- *debuginfod:* Include support for getting ELF debugging information through 146 a :ref:`debuginfod <dev-manual/debugging:using the debuginfod server method>` 147 server. 148 149- *directfb:* Include DirectFB support. 150 151- *ext2:* Include tools for supporting for devices with internal 152 HDD/Microdrive for storing files (instead of Flash only devices). 153 154- *gobject-introspection-data:* Include data to support 155 `GObject Introspection <https://gi.readthedocs.io/en/latest/>`__. 156 157- *ipsec:* Include IPSec support. 158 159- *ipv4:* Include IPv4 support. 160 161- *ipv6:* Include IPv6 support. 162 163- *keyboard:* Include keyboard support (e.g. keymaps will be loaded 164 during boot). 165 166- *multiarch:* Enable building applications with multiple architecture 167 support. 168 169- *ld-is-gold:* Use the :wikipedia:`gold <Gold_(linker)>` 170 linker instead of the standard GCC linker (bfd). 171 172- *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the 173 target. 174 175- *lto:* Enable `Link-Time Optimisation <https://gcc.gnu.org/wiki/LinkTimeOptimization>`__. 176 177- *nfc:* Include support for 178 `Near Field Communication <https://en.wikipedia.org/wiki/Near-field_communication>`__. 179 180- *nfs:* Include NFS client support (for mounting NFS exports on 181 device). 182 183- *nls:* Include National Language Support (NLS). 184 185- *opengl:* Include the Open Graphics Library, which is a 186 cross-language, multi-platform application programming interface used 187 for rendering two and three-dimensional graphics. 188 189- *overlayfs:* Include `OverlayFS <https://docs.kernel.org/filesystems/overlayfs.html>`__ 190 support. 191 192- *pam:* Include :wikipedia:`Pluggable Authentication Module (PAM) <Pluggable_authentication_module>` 193 support. 194 195- *pci:* Include PCI bus support. 196 197- *pcmcia:* Include PCMCIA/CompactFlash support. 198 199- *polkit:* Include :wikipedia:`Polkit <Polkit>` support. 200 201- *ppp:* Include PPP dialup support. 202 203- *ptest:* Enables building the package tests where supported by 204 individual recipes. For more information on package tests, see the 205 ":ref:`dev-manual/packages:testing packages with ptest`" section 206 in the Yocto Project Development Tasks Manual. 207 208- *pulseaudio:* Include support for 209 `PulseAudio <https://www.freedesktop.org/wiki/Software/PulseAudio/>`__. 210 211- *selinux:* Include support for 212 :wikipedia:`Security-Enhanced Linux (SELinux) <Security-Enhanced_Linux>` 213 (requires `meta-selinux <https://layers.openembedded.org/layerindex/layer/meta-selinux/>`__). 214 215- *seccomp:* Enables building applications with 216 :wikipedia:`seccomp <Seccomp>` support, to 217 allow them to strictly restrict the system calls that they are allowed 218 to invoke. 219 220- *smbfs:* Include SMB networks client support (for mounting 221 Samba/Microsoft Windows shares on device). 222 223- *systemd:* Include support for this ``init`` manager, which is a full 224 replacement of for ``init`` with parallel starting of services, 225 reduced shell overhead, and other features. This ``init`` manager is 226 used by many distributions. 227 228- *usbgadget:* Include USB Gadget Device support (for USB 229 networking/serial/storage). 230 231- *usbhost:* Include USB Host support (allows to connect external 232 keyboard, mouse, storage, network etc). 233 234- *usrmerge:* Merges the ``/bin``, ``/sbin``, ``/lib``, and ``/lib64`` 235 directories into their respective counterparts in the ``/usr`` 236 directory to provide better package and application compatibility. 237 238- *vfat:* Include :wikipedia:`FAT filesystem <File_Allocation_Table>` 239 support. 240 241- *vulkan:* Include support for the :wikipedia:`Vulkan API <Vulkan>`. 242 243- *wayland:* Include the Wayland display server protocol and the 244 library that supports it. 245 246- *wifi:* Include WiFi support (integrated only). 247 248- *x11:* Include the X server and libraries. 249 250- *xattr:* Include support for 251 :wikipedia:`extended file attributes <Extended_file_attributes>`. 252 253- *zeroconf:* Include support for 254 `zero configuration networking <https://en.wikipedia.org/wiki/Zero-configuration_networking>`__. 255 256.. _ref-features-image: 257 258Image Features 259============== 260 261The contents of images generated by the OpenEmbedded build system can be 262controlled by the :term:`IMAGE_FEATURES` and 263:term:`EXTRA_IMAGE_FEATURES` variables that 264you typically configure in your image recipes. Through these variables, 265you can add several different predefined packages such as development 266utilities or packages with debug information needed to investigate 267application problems or profile applications. 268 269Here are the image features available for all images: 270 271- *allow-empty-password:* Allows Dropbear and OpenSSH to accept 272 logins from accounts having an empty password string. 273 274- *allow-root-login:* Allows Dropbear and OpenSSH to accept root logins. 275 276- *dbg-pkgs:* Installs debug symbol packages for all packages installed 277 in a given image. 278 279- *debug-tweaks:* Makes an image suitable for development (e.g. allows 280 root logins, logins without passwords ---including root ones, and enables 281 post-installation logging). See the ``allow-empty-password``, 282 ``allow-root-login``, ``empty-root-password``, and ``post-install-logging`` 283 features in this list for additional information. 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 or ``debug-tweaks`` is required if 292 you want to allow root login with an empty password. If these features 293 are not present in :term:`IMAGE_FEATURES`, a non-empty password is 294 forced in ``/etc/passwd`` and ``/etc/shadow`` if such files exist. 295 296 .. note:: 297 ``empty-root-passwd`` 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-passwd`` or ``debug-tweaks`` 302 just disables the mechanism which forces an non-empty password for the 303 root user. 304 305- *lic-pkgs:* Installs license packages for all packages installed in a 306 given image. 307 308- *overlayfs-etc:* Configures the ``/etc`` directory to be in ``overlayfs``. 309 This allows to store device specific information elsewhere, especially 310 if the root filesystem is configured to be read-only. 311 312- *package-management:* Installs package management tools and preserves 313 the package manager database. 314 315- *post-install-logging:* Enables logging postinstall script runs to 316 the ``/var/log/postinstall.log`` file on first boot of the image on 317 the target system. 318 319 .. note:: 320 321 To make the ``/var/log`` directory on the target persistent, use the 322 :term:`VOLATILE_LOG_DIR` variable by setting it to "no". 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 ``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 extend 420:term:`MACHINE_FEATURES` or 421:term:`DISTRO_FEATURES` to control functionality 422that was previously enabled and not able to be disabled. For these 423cases, we need to add an additional feature item to appear in one of 424these variables, but we do not want to force developers who have 425existing values of the variables in their configuration to add the new 426feature in order to retain the same overall level of functionality. 427Thus, the OpenEmbedded build system has a mechanism to automatically 428"backfill" these added features into existing distro or machine 429configurations. You can see the list of features for which this is done 430by finding the 431:term:`DISTRO_FEATURES_BACKFILL` and 432:term:`MACHINE_FEATURES_BACKFILL` 433variables in the ``meta/conf/bitbake.conf`` file. 434 435Because such features are backfilled by default into all configurations 436as described in the previous paragraph, developers who wish to disable 437the new features need to be able to selectively prevent the backfilling 438from occurring. They can do this by adding the undesired feature or 439features to the 440:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 441or 442:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` 443variables for distro features and machine features respectively. 444 445Here are two examples to help illustrate feature backfilling: 446 447- *The "pulseaudio" distro feature option*: Previously, PulseAudio 448 support was enabled within the Qt and GStreamer frameworks. Because 449 of this, the feature is backfilled and thus enabled for all distros 450 through the :term:`DISTRO_FEATURES_BACKFILL` variable in the 451 ``meta/conf/bitbake.conf`` file. However, your distro needs to 452 disable the feature. You can disable the feature without affecting 453 other existing distro configurations that need PulseAudio support by 454 adding "pulseaudio" to :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in 455 your distro's ``.conf`` file. Adding the feature to this variable 456 when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable 457 prevents the build system from adding the feature to your 458 configuration's :term:`DISTRO_FEATURES`, effectively disabling the 459 feature for that particular distro. 460 461- *The "rtc" machine feature option*: Previously, real time clock (RTC) 462 support was enabled for all target devices. Because of this, the 463 feature is backfilled and thus enabled for all machines through the 464 :term:`MACHINE_FEATURES_BACKFILL` variable in the 465 ``meta/conf/bitbake.conf`` file. However, your target device does not 466 have this capability. You can disable RTC support for your device 467 without affecting other machines that need RTC support by adding the 468 feature to your machine's :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` 469 list in the machine's ``.conf`` file. Adding the feature to this 470 variable when it also exists in the :term:`MACHINE_FEATURES_BACKFILL` 471 variable prevents the build system from adding the feature to your 472 configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC 473 support for that particular machine. 474