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