Squashed 'yocto-poky/' content from commit ea562de
git-subtree-dir: yocto-poky
git-subtree-split: ea562de57590c966cd5a75fda8defecd397e6436
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000..798e0a2
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,443 @@
+<!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; ] >
+
+<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 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+ 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>irda:</emphasis> Hardware has IrDA support
+ </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
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></ulink>
+ 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>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>irda:</emphasis> Include IrDA support.
+ </para></listitem>
+ <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
+ support (e.g. keymaps will be loaded during boot).
+ </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 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>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.
+ </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 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>eclipse-debug:</emphasis> Provides
+ Eclipse remote debugging support.
+ </para></listitem>
+ <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>qt4-pkgs:</emphasis>
+ Supports Qt4/X11 and demo applications.
+ </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 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-profile:</emphasis>
+ Installs profiling tools such as
+ <filename>oprofile</filename>, <filename>exmap</filename>,
+ and <filename>LTTng</filename>.
+ For general information on user-space tools, see the
+ "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>"
+ section in the Yocto Project Application Developer's
+ Guide.
+ </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
+-->