documentation: Rename of poky-ref-manual folder to ref-manual.

Changing the folder that holds the YP Reference Manual to be
"ref-manual".  This will help with confustion over the manual's
intended purpose.

(From yocto-docs rev: 1106442964b5080cb0b6b3bd3af32e9407c0f7c1)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 294 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000000..77c31275ae
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,294 @@
+<!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>Reference: Features</title>
+
+    <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 in the <filename>poky.conf</filename> distribution configuration file.
+        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 metadata 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 $HOME/poky
+     $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
+        </literallayout>
+    </para>
+
+    <para>
+        This chapter provides a reference of shipped machine and distro features
+        you can include as part of the image, a reference on image types you can
+        build, and a reference on feature backfilling.
+    </para>
+
+
+    <section id='ref-features-distro'>
+        <title>Distro</title>
+
+        <para>
+            The items below are features you can use with
+            <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_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 <filename>do_configure</filename> for a particular
+            recipe.
+        </para>
+
+        <para>
+            This list only represents features as shipped with the Yocto Project metadata:
+            <itemizedlist>
+                <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility
+                    kernel modules will be installed if available).</para></listitem>
+                <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only)
+                    </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>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>pci:</emphasis> Include PCI bus support
+                    </para></listitem>
+                <listitem><para><emphasis>pcmcia:</emphasis> Include PCMCIA/CompactFlash support
+                    </para></listitem>
+                <listitem><para><emphasis>usbgadget:</emphasis> USB Gadget Device support (for USB
+                    networking/serial/storage)
+                    </para></listitem>
+                <listitem><para><emphasis>usbhost:</emphasis> USB Host support (allows to connect external
+                    keyboard, mouse, storage, network etc)
+                    </para></listitem>
+                <listitem><para><emphasis>wifi:</emphasis> WiFi support (integrated only)
+                    </para></listitem>
+                <listitem><para><emphasis>cramfs:</emphasis> CramFS support
+                    </para></listitem>
+                <listitem><para><emphasis>ipsec:</emphasis> IPSec support
+                    </para></listitem>
+                <listitem><para><emphasis>ipv6:</emphasis> IPv6 support
+                    </para></listitem>
+                <listitem><para><emphasis>nfs:</emphasis> NFS client support (for mounting NFS exports on
+                    device)</para></listitem>
+                <listitem><para><emphasis>ppp:</emphasis> PPP dialup support</para></listitem>
+                <listitem><para><emphasis>smbfs:</emphasis> SMB networks client support (for mounting
+                    Samba/Microsoft Windows shares on device)</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='ref-features-machine'>
+        <title>Machine</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 <filename>do_configure</filename> 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>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>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>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>wifi:</emphasis> Hardware has integrated WiFi
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='ref-features-image'>
+        <title>Images</title>
+
+        <para>
+            The contents of images generated by the OpenEmbedded build system can be controlled by the
+            <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
+            and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
+            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>
+            Current list of
+            <filename>IMAGE_FEATURES</filename> contains the following:
+            <itemizedlist>
+                <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>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>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>
+                <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
+                    </para></listitem>
+                <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
+                    <filename>strace</filename> and <filename>gdb</filename>.
+                    </para></listitem>
+                <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
+                    <filename>oprofile</filename>, <filename>exmap</filename>, and
+                    <filename>LTTng</filename>.</para></listitem>
+                <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
+                    touchscreen debugging).</para></listitem>
+                <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</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>staticdev-pkgs:</emphasis> Installs static development
+                    packages (i.e. static libraries containing <filename>*.a</filename> files) for all
+                    packages installed in a given image.</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>doc-pkgs:</emphasis> Installs documentation packages for all packages
+                    installed in a given image.</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
+-->