[gnome-continuous-yocto/gnomeostree-3.28-rocko: 1953/8267] ref-manual: Updated the PROVIDES variable description.

[Emmanuele Bassi <ebassi src gnome org>]

commit dfd845a126ca690e1a7971889fb323196affc30d
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Fri Jul 29 10:13:52 2016 -0700

    ref-manual: Updated the PROVIDES variable description.
    
    Added more information about virtual targets to the end of the
    description.
    
    Fixes [YOCTO #10011]
    
    (From yocto-docs rev: ce7ae0c6ad4ad3a0c2422b797556563dc48a9a5b)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/ref-manual/ref-variables.xml |   28 ++++++++++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)
---
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 1181d64..4316ea5 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9951,6 +9951,34 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     The <filename>PROVIDES</filename> statement results in
                     the "libav" recipe also being known as "libpostproc".
                 </para>
+
+                <para>
+                    In addition to providing recipes under alternate names,
+                    the <filename>PROVIDES</filename> mechanism is also used
+                    to implement virtual targets.
+                    A virtual target is a name that corresponds to some
+                    particular functionality (e.g. a Linux kernel).
+                    Recipes that provide the functionality in question list the
+                    virtual target in <filename>PROVIDES</filename>.
+                    Recipes that depend on the functionality in question can
+                    include the virtual target in
+                    <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+                    to leave the choice of provider open.
+                </para>
+
+                <para>
+                    Conventionally, virtual targets have names on the form
+                    "virtual/function" (e.g. "virtual/kernel").
+                    The slash is simply part of the name and has no
+                    syntactical significance.
+                </para>
+
+                <para>
+                    The
+                    <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
+                    variable is used to select which particular recipe
+                    provides a virtual target.
+                </para>
             </glossdef>
         </glossentry>