ref-manual/variables: document the PREFERRED_RPROVIDER variable

This variable is similar to the PREFERRED_PROVIDER variable but it
denotes a runtime provider specifically.

(From yocto-docs rev: 0b0b58070fceff6851a6e137f7f774e706205b32)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 22 insertions, 0 deletions

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 1d4e2e2be6..ca1701e7c6 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6726,6 +6726,28 @@ system and gives an overview of their function and contents.
    :term:`PREFERRED_PROVIDERS`
       See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual.
 
+   :term:`PREFERRED_RPROVIDER`
+      The :term:`PREFERRED_RPROVIDER` variable works like the
+      :term:`PREFERRED_PROVIDER` variable, but it denotes packages that provide a
+      *runtime* component. Runtime providers are declared in recipes that set
+      the :term:`RPROVIDES` variable for a specific package.
+
+      For example::
+
+         PREFERRED_RPROVIDER_virtual-x-terminal-emulator = "rxvt-unicode"
+
+      This statement sets the runtime provider for the X terminal emulator to
+      ``rxvt-unicode``. The ``rxvt-unicode`` package is a runtime provider of
+      this component because the ``rxvt-unicode`` recipe set the following
+      :term:`RPROVIDES` definition for the ``rxvt-unicode`` (``${PN}``)
+      package::
+
+         RPROVIDES:${PN} = "virtual-x-terminal-emulator"
+
+      For more information on virtual providers, see the
+      ":ref:`dev-manual/new-recipe:using virtual providers`" section in the
+      Yocto Project Development Tasks Manual.
+
    :term:`PREFERRED_VERSION`
       If there are multiple versions of a recipe available, this variable
       determines which version should be given preference. You must always