diff options
Diffstat (limited to 'documentation/ref-manual/features.rst')
| -rw-r--r-- | documentation/ref-manual/features.rst | 261 |
1 files changed, 191 insertions, 70 deletions
diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst index ded653221c..2ea946b31d 100644 --- a/documentation/ref-manual/features.rst +++ b/documentation/ref-manual/features.rst @@ -6,7 +6,7 @@ Features This chapter provides a reference of shipped machine and distro features you can include as part of your image, a reference on image features you -can select, and a reference on feature backfilling. +can select, and a reference on :ref:`ref-features-backfill`. Features provide a mechanism for working out which packages should be included in the generated images. Distributions can select which @@ -52,8 +52,6 @@ Project metadata: - *alsa:* Hardware has ALSA audio drivers -- *apm:* Hardware uses APM (or APM emulation) - - *bluetooth:* Hardware has integrated BT - *efi:* Support for booting through EFI @@ -62,6 +60,8 @@ Project metadata: - *keyboard:* Hardware has a keyboard +- *numa:* Hardware has non-uniform memory access + - *pcbios:* Support for booting through BIOS - *pci:* Hardware has a PCI bus @@ -70,6 +70,8 @@ Project metadata: - *phone:* Mobile phone (voice) support +- *qemu-usermode:* QEMU can support user-mode emulation for this machine + - *qvga:* Machine has a QVGA (320x240) display - *rtc:* Machine has a Real-Time Clock @@ -100,7 +102,9 @@ packages, and they can go beyond simply controlling the installation of a package or packages. In most cases, the presence or absence of a feature translates to the appropriate option supplied to the configure script during the :ref:`ref-tasks-configure` task for -the recipes that optionally support the feature. +the recipes that optionally support the feature. Appropriate options +must be supplied, and enabling/disabling :term:`PACKAGECONFIG` for the +concerned packages is one way of supplying such options. Some distro features are also machine features. These select features make sense to be controlled both at the machine and distribution @@ -108,11 +112,22 @@ configuration level. See the :term:`COMBINED_FEATURES` variable for more information. +.. note:: + + :term:`DISTRO_FEATURES` is normally independent of kernel configuration, + so if a feature specified in :term:`DISTRO_FEATURES` also relies on + support in the kernel, you will also need to ensure that support is + enabled in the kernel configuration. + This list only represents features as shipped with the Yocto Project -metadata: +metadata, as extra layers can define their own: + +- *3g:* Include support for cellular data. -- *alsa:* Include ALSA support (OSS compatibility kernel modules - installed if available). +- *acl:* Include :wikipedia:`Access Control List <Access-control_list>` support. + +- *alsa:* Include :wikipedia:`Advanced Linux Sound Architecture <Advanced_Linux_Sound_Architecture>` + support (OSS compatibility kernel modules installed if available). - *api-documentation:* Enables generation of API documentation during recipe builds. The resulting documentation is added to SDK tarballs @@ -125,39 +140,84 @@ metadata: - *cramfs:* Include CramFS support. +- *debuginfod:* Include support for getting ELF debugging information through + a :ref:`debuginfod <dev-manual/debugging:using the debuginfod server method>` + server. + - *directfb:* Include DirectFB support. - *ext2:* Include tools for supporting for devices with internal HDD/Microdrive for storing files (instead of Flash only devices). +- *gobject-introspection-data:* Include data to support + `GObject Introspection <https://gi.readthedocs.io/en/latest/>`__. + - *ipsec:* Include IPSec support. +- *ipv4:* Include IPv4 support. + - *ipv6:* Include IPv6 support. - *keyboard:* Include keyboard support (e.g. keymaps will be loaded during boot). +- *minidebuginfo:* Add minimal debug symbols :ref:`(minidebuginfo)<dev-manual/debugging:enabling minidebuginfo>` + to binary files containing, allowing ``coredumpctl`` and ``gdb`` to show symbolicated stack traces. + +- *multiarch:* Enable building applications with multiple architecture + support. + +- *ld-is-gold:* Use the :wikipedia:`gold <Gold_(linker)>` + linker instead of the standard GCC linker (bfd). + - *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the target. +- *lto:* Enable `Link-Time Optimisation <https://gcc.gnu.org/wiki/LinkTimeOptimization>`__. + +- *nfc:* Include support for + `Near Field Communication <https://en.wikipedia.org/wiki/Near-field_communication>`__. + - *nfs:* Include NFS client support (for mounting NFS exports on device). +- *nls:* Include National Language Support (NLS). + - *opengl:* Include the Open Graphics Library, which is a cross-language, multi-platform application programming interface used for rendering two and three-dimensional graphics. +- *overlayfs:* Include `OverlayFS <https://docs.kernel.org/filesystems/overlayfs.html>`__ + support. + +- *pam:* Include :wikipedia:`Pluggable Authentication Module (PAM) <Pluggable_authentication_module>` + support. + - *pci:* Include PCI bus support. - *pcmcia:* Include PCMCIA/CompactFlash support. +- *polkit:* Include :wikipedia:`Polkit <Polkit>` support. + - *ppp:* Include PPP dialup support. - *ptest:* Enables building the package tests where supported by individual recipes. For more information on package tests, see the - ":ref:`dev-manual/common-tasks:testing packages with ptest`" section + ":ref:`dev-manual/packages:testing packages with ptest`" section in the Yocto Project Development Tasks Manual. +- *pulseaudio:* Include support for + `PulseAudio <https://www.freedesktop.org/wiki/Software/PulseAudio/>`__. + +- *selinux:* Include support for + :wikipedia:`Security-Enhanced Linux (SELinux) <Security-Enhanced_Linux>` + (requires `meta-selinux <https://layers.openembedded.org/layerindex/layer/meta-selinux/>`__). + +- *seccomp:* Enables building applications with + :wikipedia:`seccomp <Seccomp>` support, to + allow them to strictly restrict the system calls that they are allowed + to invoke. + - *smbfs:* Include SMB networks client support (for mounting Samba/Microsoft Windows shares on device). @@ -166,6 +226,10 @@ metadata: reduced shell overhead, and other features. This ``init`` manager is used by many distributions. +- *systemd-resolved:* Include support and use ``systemd-resolved`` as the + main DNS name resolver in ``glibc`` Name Service Switch. This is a DNS + resolver daemon from ``systemd``. + - *usbgadget:* Include USB Gadget Device support (for USB networking/serial/storage). @@ -176,6 +240,11 @@ metadata: directories into their respective counterparts in the ``/usr`` directory to provide better package and application compatibility. +- *vfat:* Include :wikipedia:`FAT filesystem <File_Allocation_Table>` + support. + +- *vulkan:* Include support for the :wikipedia:`Vulkan API <Vulkan>`. + - *wayland:* Include the Wayland display server protocol and the library that supports it. @@ -183,6 +252,12 @@ metadata: - *x11:* Include the X server and libraries. +- *xattr:* Include support for + :wikipedia:`extended file attributes <Extended_file_attributes>`. + +- *zeroconf:* Include support for + `zero configuration networking <https://en.wikipedia.org/wiki/Zero-configuration_networking>`__. + .. _ref-features-image: Image Features @@ -196,19 +271,21 @@ you can add several different predefined packages such as development utilities or packages with debug information needed to investigate application problems or profile applications. -Here are the image features available for all images: +The image features available for all images are: + +- *allow-empty-password:* Allows Dropbear and OpenSSH to accept + logins from accounts having an empty password string. -- *allow-empty-password:* Allows Dropbear and OpenSSH to accept root - logins and logins from accounts having an empty password string. +- *allow-root-login:* Allows Dropbear and OpenSSH to accept root logins. - *dbg-pkgs:* Installs debug symbol packages for all packages installed in a given image. - *debug-tweaks:* Makes an image suitable for development (e.g. allows - root logins without passwords and enables post-installation logging). - See the 'allow-empty-password', 'empty-root-password', and - 'post-install-logging' features in this list for additional - information. + root logins, logins without passwords ---including root ones, and enables + post-installation logging). See the ``allow-empty-password``, + ``allow-root-login``, ``empty-root-password``, and ``post-install-logging`` + features in this list for additional information. - *dev-pkgs:* Installs development packages (headers and extra library links) for all packages installed in a given image. @@ -216,8 +293,26 @@ Here are the image features available for all images: - *doc-pkgs:* Installs documentation packages for all packages installed in a given image. -- *empty-root-password:* Sets the root password to an empty string, - which allows logins with a blank password. +- *empty-root-password:* This feature or ``debug-tweaks`` is required if + you want to allow root login with an empty password. If these features + are not present in :term:`IMAGE_FEATURES`, a non-empty password is + forced in ``/etc/passwd`` and ``/etc/shadow`` if such files exist. + + .. note:: + ``empty-root-password`` doesn't set an empty root password by itself. + You get an initial empty root password thanks to the + :oe_git:`base-passwd </openembedded-core/tree/meta/recipes-core/base-passwd/>` + and :oe_git:`shadow </openembedded-core/tree/meta/recipes-extended/shadow/>` + recipes, and the presence of ``empty-root-password`` or ``debug-tweaks`` + just disables the mechanism which forces an non-empty password for the + root user. + +- *lic-pkgs:* Installs license packages for all packages installed in a + given image. + +- *overlayfs-etc:* Configures the ``/etc`` directory to be in ``overlayfs``. + This allows to store device specific information elsewhere, especially + if the root filesystem is configured to be read-only. - *package-management:* Installs package management tools and preserves the package manager database. @@ -235,23 +330,40 @@ Here are the image features available for all images: - *read-only-rootfs:* Creates an image whose root filesystem is read-only. See the - ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`" + ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`" section in the Yocto Project Development Tasks Manual for more information. +- *read-only-rootfs-delayed-postinsts:* when specified in conjunction + with ``read-only-rootfs``, specifies that post-install scripts are + still permitted (this assumes that the root filesystem will be made + writeable for the first boot; this feature does not do anything to + ensure that - it just disables the check for post-install scripts.) + +- *serial-autologin-root:* when specified in conjunction with + ``empty-root-password`` will automatically login as root on the + serial console. This of course opens up a security hole if the + serial console is potentially accessible to an attacker, so use + with caution. + - *splash:* Enables showing a splash screen during boot. By default, this screen is provided by ``psplash``, which does allow customization. If you prefer to use an alternative splash screen - package, you can do so by setting the ``SPLASH`` variable to a + package, you can do so by setting the :term:`SPLASH` variable to a different package name (or names) within the image recipe or at the distro configuration level. +- *stateless-rootfs:*: specifies that the image should be created as + stateless - when using ``systemd``, ``systemctl-native`` will not + be run on the image, leaving the image for population at runtime by + systemd. + - *staticdev-pkgs:* Installs static development packages, which are static libraries (i.e. ``*.a`` files), for all packages installed in a given image. Some image features are available only when you inherit the -:ref:`core-image <ref-classes-core-image>` class. The current list of +:ref:`ref-classes-core-image` class. The current list of these valid features is as follows: - *hwcodecs:* Installs hardware acceleration codecs. @@ -264,6 +376,21 @@ these valid features is as follows: - *ssh-server-dropbear:* Installs the Dropbear minimal SSH server. + .. note:: + + As of the 4.1 release, the ``ssh-server-dropbear`` feature also + recommends the ``openssh-sftp-server`` package, which by default + will be pulled into the image. This is because recent versions of + the OpenSSH ``scp`` client now use the SFTP protocol, and thus + require an SFTP server to be present to connect to. However, if + you wish to use the Dropbear ssh server `without` the SFTP server + installed, you can either remove ``ssh-server-dropbear`` from + ``IMAGE_FEATURES`` and add ``dropbear`` to :term:`IMAGE_INSTALL` + instead, or alternatively still use the feature but set + :term:`BAD_RECOMMENDATIONS` as follows:: + + BAD_RECOMMENDATIONS += "openssh-sftp-server" + - *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more full-featured than Dropbear. Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server are present in @@ -272,7 +399,7 @@ these valid features is as follows: - *tools-debug:* Installs debugging tools such as ``strace`` and ``gdb``. For information on GDB, see the - ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section + ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section in the Yocto Project Development Tasks Manual. For information on tracing and profiling, see the :doc:`/profile-manual/index`. @@ -281,6 +408,8 @@ these valid features is as follows: - *tools-testapps:* Installs device testing tools (e.g. touchscreen debugging). +- *weston:* Installs Weston (reference Wayland environment). + - *x11:* Installs the X server. - *x11-base:* Installs the X server with a minimal environment. @@ -292,58 +421,50 @@ these valid features is as follows: Feature Backfilling =================== -Sometimes it is necessary in the OpenEmbedded build system to extend -:term:`MACHINE_FEATURES` or -:term:`DISTRO_FEATURES` to control functionality -that was previously enabled and not able to be disabled. For these -cases, we need to add an additional feature item to appear in one of -these variables, but we do not want to force developers who have -existing values of the variables in their configuration to add the new -feature in order to retain the same overall level of functionality. -Thus, the OpenEmbedded build system has a mechanism to automatically -"backfill" these added features into existing distro or machine +Sometimes it is necessary in the OpenEmbedded build system to +add new functionality to :term:`MACHINE_FEATURES` or +:term:`DISTRO_FEATURES`, but at the same time, allow existing +distributions or machine definitions to opt out of such new +features, to retain the same overall level of functionality. + +To make this possible, the OpenEmbedded build system has a mechanism to +automatically "backfill" features into existing distro or machine configurations. You can see the list of features for which this is done -by finding the -:term:`DISTRO_FEATURES_BACKFILL` and -:term:`MACHINE_FEATURES_BACKFILL` -variables in the ``meta/conf/bitbake.conf`` file. - -Because such features are backfilled by default into all configurations -as described in the previous paragraph, developers who wish to disable -the new features need to be able to selectively prevent the backfilling -from occurring. They can do this by adding the undesired feature or -features to the +by checking the :term:`DISTRO_FEATURES_BACKFILL` and +:term:`MACHINE_FEATURES_BACKFILL` variables in the +``meta/conf/bitbake.conf`` file. + +These two variables are paired with the :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` -or -:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` -variables for distro features and machine features respectively. - -Here are two examples to help illustrate feature backfilling: - -- *The "pulseaudio" distro feature option*: Previously, PulseAudio - support was enabled within the Qt and GStreamer frameworks. Because - of this, the feature is backfilled and thus enabled for all distros - through the :term:`DISTRO_FEATURES_BACKFILL` variable in the - ``meta/conf/bitbake.conf`` file. However, your distro needs to - disable the feature. You can disable the feature without affecting - other existing distro configurations that need PulseAudio support by - adding "pulseaudio" to :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in - your distro's ``.conf`` file. Adding the feature to this variable - when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable - prevents the build system from adding the feature to your - configuration's :term:`DISTRO_FEATURES`, effectively disabling the - feature for that particular distro. +and :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` variables +which allow distro or machine configuration maintainers to `consider` any +added feature, and decide when they wish to keep or exclude such feature, +thus preventing the backfilling from happening. + +Here are two examples to illustrate feature backfilling: + +- *The "pulseaudio" distro feature option*: Previously, PulseAudio support was + enabled within the Qt and GStreamer frameworks. Because of this, the feature + is now backfilled and thus enabled for all distros through the + :term:`DISTRO_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` + file. However, if your distro needs to disable the feature, you can do so + without affecting other existing distro configurations that need PulseAudio + support. You do this by adding "pulseaudio" to + :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in your distro's ``.conf`` + file. So, adding the feature to this variable when it also exists in the + :term:`DISTRO_FEATURES_BACKFILL` variable prevents the build system from + adding the feature to your configuration's :term:`DISTRO_FEATURES`, + effectively disabling the feature for that particular distro. - *The "rtc" machine feature option*: Previously, real time clock (RTC) support was enabled for all target devices. Because of this, the feature is backfilled and thus enabled for all machines through the - :term:`MACHINE_FEATURES_BACKFILL` variable in the - ``meta/conf/bitbake.conf`` file. However, your target device does not - have this capability. You can disable RTC support for your device - without affecting other machines that need RTC support by adding the - feature to your machine's :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` - list in the machine's ``.conf`` file. Adding the feature to this - variable when it also exists in the :term:`MACHINE_FEATURES_BACKFILL` - variable prevents the build system from adding the feature to your - configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC - support for that particular machine. + :term:`MACHINE_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` + file. However, if your target device does not have this capability, you can + disable RTC support for your device without affecting other machines + that need RTC support. You do this by adding the "rtc" feature to the + :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` list in your machine's ``.conf`` + file. So, adding the feature to this variable when it also exists in the + :term:`MACHINE_FEATURES_BACKFILL` variable prevents the build system from + adding the feature to your configuration's :term:`MACHINE_FEATURES`, + effectively disabling RTC support for that particular machine. |