diff options
Diffstat (limited to 'documentation/ref-manual/ref-features.xml')
| -rw-r--r-- | documentation/ref-manual/ref-features.xml | 461 |
1 files changed, 0 insertions, 461 deletions
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml deleted file mode 100644 index 8cab5ec3a8..0000000000 --- a/documentation/ref-manual/ref-features.xml +++ /dev/null @@ -1,461 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='ref-features'> - <title>Features</title> - - <para> - 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. - </para> - - <para> - Features provide a mechanism for working out which packages - should be included in the generated images. - Distributions can select which features they want to support through the - <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> - variable, which is set or appended to in a distribution's configuration file such as - <filename>poky.conf</filename>, - <filename>poky-tiny.conf</filename>, - <filename>poky-lsb.conf</filename> and so forth. - Machine features are set in the - <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> - variable, which is set in the machine configuration file and - specifies the hardware features for a given machine. - </para> - - <para> - These two variables combine to work out which kernel modules, - utilities, and other packages to include. - A given distribution can support a selected subset of features so some machine features might not - be included if the distribution itself does not support them. - </para> - - <para> - One method you can use to determine which recipes are checking to see if a - particular feature is contained or not is to <filename>grep</filename> through - the <link linkend='metadata'>Metadata</link> - for the feature. - Here is an example that discovers the recipes whose build is potentially - changed based on a given feature: - <literallayout class='monospaced'> - $ cd poky - $ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>' - </literallayout> - </para> - - <section id='ref-features-machine'> - <title>Machine Features</title> - - <para> - The items below are features you can use with - <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. - Features do not have a one-to-one correspondence to packages, and they can - go beyond simply controlling the installation of a package or packages. - Sometimes a feature can influence how certain recipes are built. - For example, a feature might determine whether a particular configure option - is specified within the - <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - task for a particular recipe. - </para> - - <para> - This feature list only represents features as shipped with the Yocto Project metadata: - <itemizedlist> - <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only) - </para></listitem> - <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers - </para></listitem> - <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation) - </para></listitem> - <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT - </para></listitem> - <listitem><para><emphasis>efi:</emphasis> Support for booting through EFI - </para></listitem> - <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive - </para></listitem> - <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard - </para></listitem> - <listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS - </para></listitem> - <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus - </para></listitem> - <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets - </para></listitem> - <listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support - </para></listitem> - <listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display - </para></listitem> - <listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock - </para></listitem> - <listitem><para><emphasis>screen:</emphasis> Hardware has a screen - </para></listitem> - <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232) - </para></listitem> - <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen - </para></listitem> - <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable - </para></listitem> - <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable - </para></listitem> - <listitem><para><emphasis>vfat:</emphasis> FAT file system support - </para></listitem> - <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='ref-features-distro'> - <title>Distro Features</title> - - <para> - The items below are features you can use with - <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> - to enable features across your distribution. - Features do not have a one-to-one correspondence to 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 - <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - task for the recipes that optionally - support the feature. - </para> - - <para> - Some distro features are also machine features. - These select features make sense to be controlled both at - the machine and distribution configuration level. - See the - <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link> - variable for more information. - </para> - - <para> - This list only represents features as shipped with the Yocto Project metadata: - <itemizedlist> - <listitem><para><emphasis>alsa:</emphasis> Include ALSA support - (OSS compatibility kernel modules installed if available). - </para></listitem> - <listitem><para><emphasis>api-documentation:</emphasis> - Enables generation of API documentation during recipe - builds. - The resulting documentation is added to SDK tarballs - when the - <filename>bitbake -c populate_sdk</filename> command - is used. - See the - "<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding API Documentation to the Standard SDK</ulink>" - section in the Yocto Project Application Development and - the Extensible Software Development Kit (eSDK) manual. - </para></listitem> - <listitem><para><emphasis>bluetooth:</emphasis> Include - bluetooth support (integrated BT only).</para></listitem> - <listitem><para><emphasis>cramfs:</emphasis> Include CramFS - support.</para></listitem> - <listitem><para><emphasis>directfb:</emphasis> - Include DirectFB support. - </para></listitem> - <listitem><para><emphasis>ext2:</emphasis> Include tools for - supporting for devices with internal HDD/Microdrive for - storing files (instead of Flash only devices). - </para></listitem> - <listitem><para><emphasis>ipsec:</emphasis> Include IPSec - support.</para></listitem> - <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support. - </para></listitem> - <listitem><para><emphasis>keyboard:</emphasis> Include keyboard - support (e.g. keymaps will be loaded during boot). - </para></listitem> - <listitem><para><emphasis>ldconfig:</emphasis> - Include support for ldconfig and - <filename>ld.so.conf</filename> on the target. - </para></listitem> - <listitem><para><emphasis>nfs:</emphasis> Include NFS client - support (for mounting NFS exports on device). - </para></listitem> - <listitem><para><emphasis>opengl:</emphasis> - Include the Open Graphics Library, which is a - cross-language, multi-platform application programming - interface used for rendering two and three-dimensional - graphics.</para></listitem> - <listitem><para><emphasis>pci:</emphasis> Include PCI bus - support.</para></listitem> - <listitem><para><emphasis>pcmcia:</emphasis> Include - PCMCIA/CompactFlash support.</para></listitem> - <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup - support.</para></listitem> - <listitem><para><emphasis>ptest:</emphasis> Enables building - the package tests where supported by individual recipes. - For more information on package tests, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>" - section in the Yocto Project Development Tasks Manual. - </para></listitem> - <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks - client support (for mounting Samba/Microsoft Windows shares - on device).</para></listitem> - <listitem><para><emphasis>systemd:</emphasis> Include support - for this <filename>init</filename> manager, which is a full - replacement of for <filename>init</filename> with parallel - starting of services, reduced shell overhead, and other - features. - This <filename>init</filename> manager is used by many - distributions.</para></listitem> - <listitem><para><emphasis>usbgadget:</emphasis> Include USB - Gadget Device support (for USB networking/serial/storage). - </para></listitem> - <listitem><para><emphasis>usbhost:</emphasis> Include USB Host - support (allows to connect external keyboard, mouse, - storage, network etc).</para></listitem> - <listitem><para><emphasis>usrmerge:</emphasis> Merges the - <filename>/bin</filename>, <filename>/sbin</filename>, - <filename>/lib</filename>, and <filename>/lib64</filename> - directories into their respective counterparts in the - <filename>/usr</filename> directory to provide better package - and application compatibility.</para></listitem> - <listitem><para><emphasis>wayland:</emphasis> Include the - Wayland display server protocol and the library that - supports it.</para></listitem> - <listitem><para><emphasis>wifi:</emphasis> Include WiFi support - (integrated only).</para></listitem> - <listitem><para><emphasis>x11:</emphasis> Include the X server - and libraries.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='ref-features-image'> - <title>Image Features</title> - - <para> - The contents of images generated by the OpenEmbedded build system - can be controlled by the - <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> - and - <link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link> - variables that you typically configure in your image recipes. - Through these variables, you can add several different - predefined packages such as development utilities or packages with - debug information needed to investigate application problems or - profile applications. - </para> - - <para> - The following image features are available for all images: - <itemizedlist> - <listitem><para><emphasis>allow-empty-password:</emphasis> - Allows Dropbear and OpenSSH to accept root logins - and logins from accounts having an empty password string. - </para></listitem> - <listitem><para><emphasis>dbg-pkgs:</emphasis> - Installs debug symbol packages for all packages installed - in a given image. - </para></listitem> - <listitem><para><emphasis>debug-tweaks:</emphasis> - 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. - </para></listitem> - <listitem><para><emphasis>dev-pkgs:</emphasis> - Installs development packages (headers and extra library - links) for all packages installed in a given image. - </para></listitem> - <listitem><para><emphasis>doc-pkgs:</emphasis> Installs - documentation packages for all packages installed in a - given image. - </para></listitem> - <listitem><para><emphasis>empty-root-password:</emphasis> - Sets the root password to an empty string, which allows - logins with a blank password. - </para></listitem> - <listitem><para><emphasis>package-management:</emphasis> - Installs package management tools and preserves the package - manager database. - </para></listitem> - <listitem><para><emphasis>post-install-logging:</emphasis> - Enables logging postinstall script runs to - the <filename>/var/log/postinstall.log</filename> file - on first boot of the image on the target system. - <note> - To make the <filename>/var/log</filename> directory - on the target persistent, use the - <link linkend='var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></link> - variable by setting it to "no". - </note> - </para></listitem> - <listitem><para><emphasis>ptest-pkgs:</emphasis> - Installs ptest packages for all ptest-enabled recipes. - </para></listitem> - <listitem><para><emphasis>read-only-rootfs:</emphasis> - Creates an image whose root filesystem is read-only. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>" - section in the Yocto Project Development Tasks Manual for - more information. - </para></listitem> - <listitem><para><emphasis>splash:</emphasis> - Enables showing a splash screen during boot. - By default, this screen is provided by - <filename>psplash</filename>, which does allow - customization. - If you prefer to use an alternative splash screen package, - you can do so by setting the <filename>SPLASH</filename> - variable to a different package name (or names) within the - image recipe or at the distro configuration level. - </para></listitem> - <listitem><para><emphasis>staticdev-pkgs:</emphasis> - Installs static development packages, which are - static libraries (i.e. <filename>*.a</filename> files), for - all packages installed in a given image. - </para></listitem> - </itemizedlist> - </para> - - <para> - Some image features are available only when you inherit the - <link linkend='ref-classes-core-image'><filename>core-image</filename></link> - class. - The current list of these valid features is as follows: - <itemizedlist> - <listitem><para><emphasis>hwcodecs:</emphasis> Installs - hardware acceleration codecs. - </para></listitem> - <listitem><para><emphasis>nfs-server:</emphasis> - Installs an NFS server. - </para></listitem> - <listitem><para><emphasis>perf:</emphasis> - Installs profiling tools such as - <filename>perf</filename>, <filename>systemtap</filename>, - and <filename>LTTng</filename>. - For general information on user-space tools, see the - <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> - manual. - </para></listitem> - <listitem><para><emphasis>ssh-server-dropbear:</emphasis> - Installs the Dropbear minimal SSH server. - </para></listitem> - <listitem><para><emphasis>ssh-server-openssh:</emphasis> - 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 - <filename>IMAGE_FEATURES</filename>, then OpenSSH will take - precedence and Dropbear will not be installed. - </para></listitem> - <listitem><para><emphasis>tools-debug:</emphasis> - Installs debugging tools such as - <filename>strace</filename> and <filename>gdb</filename>. - For information on GDB, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" - section in the Yocto Project Development Tasks Manual. - For information on tracing and profiling, see the - <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>. - </para></listitem> - <listitem><para><emphasis>tools-sdk:</emphasis> - Installs a full SDK that runs on the device. - </para></listitem> - <listitem><para><emphasis>tools-testapps:</emphasis> - Installs device testing tools (e.g. touchscreen debugging). - </para></listitem> - <listitem><para><emphasis>x11:</emphasis> - Installs the X server. - </para></listitem> - <listitem><para><emphasis>x11-base:</emphasis> - Installs the X server with a minimal environment. - </para></listitem> - <listitem><para><emphasis>x11-sato:</emphasis> - Installs the OpenedHand Sato environment. - </para></listitem> - </itemizedlist> - </para> - - </section> - - <section id='ref-features-backfill'> - <title>Feature Backfilling</title> - - <para> - Sometimes it is necessary in the OpenEmbedded build system to extend - <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> - or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> - 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 configurations. - You can see the list of features for which this is done by - finding the - <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> - and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link> - variables in the <filename>meta/conf/bitbake.conf</filename> file. - </para> - - <para> - 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 - <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> - or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link> - variables for distro features and machine features respectively. - </para> - - <para> - Here are two examples to help illustrate feature backfilling: - <itemizedlist> - <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: - 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 - <filename>DISTRO_FEATURES_BACKFILL</filename> - variable in the <filename>meta/conf/bitbake.conf</filename> 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 - <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename> - in your distro's <filename>.conf</filename> file. - Adding the feature to this variable when it also - exists in the <filename>DISTRO_FEATURES_BACKFILL</filename> - variable prevents the build system from adding the feature to - your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling - the feature for that particular distro.</para></listitem> - <listitem><para><emphasis>The "rtc" machine feature option</emphasis>: - 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 <filename>MACHINE_FEATURES_BACKFILL</filename> - variable in the <filename>meta/conf/bitbake.conf</filename> 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 - <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename> - list in the machine's <filename>.conf</filename> file. - Adding the feature to this variable when it also - exists in the <filename>MACHINE_FEATURES_BACKFILL</filename> - variable prevents the build system from adding the feature to - your configuration's <filename>MACHINE_FEATURES</filename>, effectively - disabling RTC support for that particular machine.</para></listitem> - </itemizedlist> - </para> - </section> -</chapter> - -<!-- -vim: expandtab tw=80 ts=4 spell spelllang=en_gb ---> |