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

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

[Wadim Mueller]

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

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

[Antonin Godard]

Hi,

On Mon Oct 5, 2026 at 9:23 AM CEST, Wadim Müller via lists.yoctoproject.org wrote:
> 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,

This I understand,

> +      which an alias with the version in its name cannot express::

But this I'm not sure. Are you saying that you cannot write:

  RPROVIDES:${PN} = "widget-abi (>= 2)"

?

If that's what you wanted to say, maybe I would explain in a separate paragraph,
after the RDEPENDS snippet below, with an example. Also, what happens if you
write the example above? Does the build fail?

> +
> +         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

Thanks,
Antonin
text:
Mime-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset=UTF-8
Date: Mon, 12 Oct 2026 15:58:12 +0200
Message-Id: <DM2WVEXYKYCD.258COUKZK6O6C@bootlin.com>
Subject: Re: [docs] [PATCH] ref-manual/variables.rst: document versioned
 RPROVIDES
From: "Antonin Godard" <antonin.godard@bootlin.com>
To: <wafgo01@gmail.com>, <docs@lists.yoctoproject.org>
References: <20261005072345.1383304-1-wafgo01@gmail.com>
In-Reply-To: <20261005072345.1383304-1-wafgo01@gmail.com>
X-TUID: RiwbBQw8U+XC

Hi,

On Mon Oct 5, 2026 at 9:23 AM CEST, Wadim Müller via lists.yoctoproject.org wrote:
> 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,

This I understand,

> +      which an alias with the version in its name cannot express::

But this I'm not sure. Are you saying that you cannot write:

  RPROVIDES:${PN} = "widget-abi (>= 2)"

?

If that's what you wanted to say, maybe I would explain in a separate paragraph,
after the RDEPENDS snippet below, with an example. Also, what happens if you
write the example above? Does the build fail?

> +
> +         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

Thanks,
Antonin