[PATCH] ref-manual/variables.rst: document versioned RPROVIDES

[Wadim Mueller <wafgo01@gmail.com>]

RPROVIDES accepts the same "name (operator version)" syntax as
RDEPENDS: package_rpm parses it with bb.utils.explode_dep_versions2()
and writes "Provides: name = version" into the spec file. This lets a
package provide an interface level that other packages depend on with
">=", which an alias carrying the version in its name, such as the
existing "widget-abi-2" example, cannot express.

package_ipk and package_deb build their Provides field from
dict.fromkeys(explode_dep_versions2(RPROVIDES), []) and so drop the
version, which the documentation should say next to the syntax.

Signed-off-by: Wadim Mueller <wafgo01@gmail.com>
---
 documentation/ref-manual/variables.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 1c0864d87..b16a6272c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8735,6 +8735,24 @@ system and gives an overview of their function and contents.
 
          RPROVIDES:${PN} = "widget-abi-2"
 
+      An alias can also carry a version, using the same syntax as
+      :term:`RDEPENDS` with the ``=`` operator::
+
+         RPROVIDES:${PN} = "widget-abi (= 2)"
+
+      Other packages can then depend on a range of versions of the alias,
+      which an alias with the version in its name cannot express::
+
+         RDEPENDS:${PN} = "widget-abi (>= 2)"
+
+      .. note::
+
+         Only the :ref:`ref-classes-package_rpm` class writes the version
+         into the package metadata. The :ref:`ref-classes-package_ipk` and
+         :ref:`ref-classes-package_deb` classes drop it and provide the bare
+         alias, so a versioned dependency on the alias cannot be relied upon
+         with those package formats.
+
    :term:`RRECOMMENDS`
       A list of packages that extends the usability of a package being
       built. The package being built does not depend on this list of
-- 
2.43.0