diff mbox series

[ref-manual] clarify definition of PROVIDES variable

Message ID 6686fc57-f92d-8c76-704d-ebc5046561a9@crashcourse.ca
State Under Review
Headers show
Series [ref-manual] clarify definition of PROVIDES variable | expand

Commit Message

Robert P. J. Day June 11, 2025, 8:49 a.m. UTC
Correct the example used in the definition, and add a bit more detail,
including the use of both assignment operators.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

Comments

Quentin Schulz June 11, 2025, 10:23 a.m. UTC | #1
Hi Robert,

No need for [ref-manual] in the subject, or use:

ref-manual: clarify definition of PROVIDES

if you want.

On 6/11/25 10:49 AM, Robert P. J. Day via lists.yoctoproject.org wrote:
> 
> Correct the example used in the definition, and add a bit more detail,
> including the use of both assignment operators.
> 
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> 
> ---
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 5c18b852d..2d3af4966 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -7411,21 +7411,25 @@ system and gives an overview of their function and contents.
>         provides itself. If a recipe uses :term:`PROVIDES`, the additional
>         aliases are synonyms for the recipe and can be useful for satisfying
>         dependencies of other recipes during the build as specified by
> -      :term:`DEPENDS`.
> +      :term:`DEPENDS` without needing to be specific as to which package

recipe != package. PROVIDES is for the recipe, not the package.

> +      provides that dependency.
> 

I still feel this isn't making it that much clearer because we don't 
make it explicit that two recipes can have the same alias (which is 
actually the whole point of aliases). We do explain it in a few 
paragraphs though.

> -      Consider the following example :term:`PROVIDES` statement from the recipe
> -      file ``eudev_3.2.9.bb``::
> +      As an example, the term "udev" refers to the Linux subsystem for
> +      managing device events. Depending on how you configure your build,

I don't think udev is a Linux subsystem?

I would reword it to something like:

"""
As an example, "udev" `Linux dynamic device 
management<https://www.kernel.org/pub/linux/utils/kernel/hotplug/udev/udev.html>`__ 
functionality is handled by ``eudev`` and ``systemd`` recipes, which is 
why they both have the following::

    PROVIDES = "udev"
"""

what do you think?

> +      that functionality can be supplied by either the ``eudev`` package

package != recipe

> +      or by ``systemd``, which is why both of those BitBake recipes advertise
> +      that with the line:
> 

You need to end the paragraph with :: instead of : otherwise what 
follows isn't a code block.

> -         PROVIDES += "udev"
> +         PROVIDES = "udev"
> 
> -      The :term:`PROVIDES` statement
> -      results in the "eudev" recipe also being available as simply "udev".
> +      Those :term:`PROVIDES` assignments result in both the ``eudev`` and
> +      ``systemd`` packages being available as simply "udev".
> 

s/packages/recipes/

s/being available as simply "udev"/being also available under the "udev" 
alias/

I'm not entirely sure but I also believe that you cannot install 
packages from two recipes providing the same alias? Also, your build 
dependency tree probably shouldn't have a dependency on multiple recipes 
providing the same alias?

As a test, I copied kmscube into kmscube2 in poky, made them both have 
PROVIDES = "kmscube-test", then have my bootloader DEPENDS on kmscube 
and my kernel DEPENDS on kmscube2 and I get the following error:

ERROR: Multiple .bb files are due to be built which each provide 
kmscube-test:             | ETA:  0:00:00
   /build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb
   /build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb
A list of tasks depending on these providers is shown and may help 
explain where the dependency comes from.
/build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb has 
unique dependees:
  
/build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_package_write_rpm
  
/build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_package
  
/build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_collect_spdx_deps
  
/build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_prepare_recipe_sysroot
/build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb has 
unique dependees:
  
/build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_package
  
/build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_package_write_rpm
  
/build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_prepare_recipe_sysroot
  
/build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_collect_spdx_deps
It could be that one recipe provides something the other doesn't and 
should. The following provider and runtime provider differences may be 
helpful.
/build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb has 
unique provides:
   kmscube2
/build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb has 
unique rprovides:
   kmscube2
   kmscube2-doc
   kmscube2-locale
   ^kmscube2-locale-.*
   kmscube2-staticdev
   kmscube2-src
   kmscube2-dev
   kmscube2-dbg
/build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb has 
unique provides:
   kmscube
/build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb has 
unique rprovides:
   ^kmscube-locale-.*
   kmscube-doc
   kmscube-src
   kmscube-dev
   kmscube-dbg
   kmscube-staticdev
   kmscube-locale
   kmscube

I think this is an important note as well, one should be really thinking 
twice before (ab)using the PROVIDES mechanism :) Doesn't need to be in 
this patch though.

Cheers,
Quentin
Robert P. J. Day June 11, 2025, 10:28 a.m. UTC | #2
OK, I'll redo this after the coffee kicks in.

rday

On Wed, 11 Jun 2025, Quentin Schulz via lists.yoctoproject.org wrote:

> Hi Robert,
>
> No need for [ref-manual] in the subject, or use:
>
> ref-manual: clarify definition of PROVIDES
>
> if you want.
>
> On 6/11/25 10:49 AM, Robert P. J. Day via lists.yoctoproject.org wrote:
> >
> > Correct the example used in the definition, and add a bit more detail,
> > including the use of both assignment operators.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> > diff --git a/documentation/ref-manual/variables.rst
> > b/documentation/ref-manual/variables.rst
> > index 5c18b852d..2d3af4966 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -7411,21 +7411,25 @@ system and gives an overview of their function and
> > contents.
> >         provides itself. If a recipe uses :term:`PROVIDES`, the additional
> >         aliases are synonyms for the recipe and can be useful for satisfying
> >         dependencies of other recipes during the build as specified by
> > -      :term:`DEPENDS`.
> > +      :term:`DEPENDS` without needing to be specific as to which package
>
> recipe != package. PROVIDES is for the recipe, not the package.
>
> > +      provides that dependency.
> >
>
> I still feel this isn't making it that much clearer because we don't make it
> explicit that two recipes can have the same alias (which is actually the whole
> point of aliases). We do explain it in a few paragraphs though.
>
> > -      Consider the following example :term:`PROVIDES` statement from the
> > recipe
> > -      file ``eudev_3.2.9.bb``::
> > +      As an example, the term "udev" refers to the Linux subsystem for
> > +      managing device events. Depending on how you configure your build,
>
> I don't think udev is a Linux subsystem?
>
> I would reword it to something like:
>
> """
> As an example, "udev" `Linux dynamic device
> management<https://www.kernel.org/pub/linux/utils/kernel/hotplug/udev/udev.html>`__
> functionality is handled by ``eudev`` and ``systemd`` recipes, which is why
> they both have the following::
>
>    PROVIDES = "udev"
> """
>
> what do you think?
>
> > +      that functionality can be supplied by either the ``eudev`` package
>
> package != recipe
>
> > +      or by ``systemd``, which is why both of those BitBake recipes
> > advertise
> > +      that with the line:
> >
>
> You need to end the paragraph with :: instead of : otherwise what follows
> isn't a code block.
>
> > -         PROVIDES += "udev"
> > +         PROVIDES = "udev"
> >
> > -      The :term:`PROVIDES` statement
> > -      results in the "eudev" recipe also being available as simply "udev".
> > +      Those :term:`PROVIDES` assignments result in both the ``eudev`` and
> > +      ``systemd`` packages being available as simply "udev".
> >
>
> s/packages/recipes/
>
> s/being available as simply "udev"/being also available under the "udev"
> alias/
>
> I'm not entirely sure but I also believe that you cannot install packages from
> two recipes providing the same alias? Also, your build dependency tree
> probably shouldn't have a dependency on multiple recipes providing the same
> alias?
>
> As a test, I copied kmscube into kmscube2 in poky, made them both have
> PROVIDES = "kmscube-test", then have my bootloader DEPENDS on kmscube and my
> kernel DEPENDS on kmscube2 and I get the following error:
>
> ERROR: Multiple .bb files are due to be built which each provide kmscube-test:
> | ETA:  0:00:00
>   /build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb
>   /build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb
> A list of tasks depending on these providers is shown and may help explain
> where the dependency comes from.
> /build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb has unique
> dependees:
>  /build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_package_write_rpm
>  /build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_package
>  /build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_collect_spdx_deps
>  /build/../repo/meta-bsp/recipes-kernel/linux/linux-cherry-es-dev_git.bb:do_prepare_recipe_sysroot
> /build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb has unique
> dependees:
>  /build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_package
>  /build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_package_write_rpm
>  /build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_prepare_recipe_sysroot
>  /build/../repo/meta-bsp/recipes-bsp/u-boot/u-boot-cherry-es_2024.07.bb:do_collect_spdx_deps
> It could be that one recipe provides something the other doesn't and should.
> The following provider and runtime provider differences may be helpful.
> /build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb has unique
> provides:
>   kmscube2
> /build/../work/poky/meta/recipes-graphics/kmscube/kmscube2_git.bb has unique
> rprovides:
>   kmscube2
>   kmscube2-doc
>   kmscube2-locale
>   ^kmscube2-locale-.*
>   kmscube2-staticdev
>   kmscube2-src
>   kmscube2-dev
>   kmscube2-dbg
> /build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb has unique
> provides:
>   kmscube
> /build/../work/poky/meta/recipes-graphics/kmscube/kmscube_git.bb has unique
> rprovides:
>   ^kmscube-locale-.*
>   kmscube-doc
>   kmscube-src
>   kmscube-dev
>   kmscube-dbg
>   kmscube-staticdev
>   kmscube-locale
>   kmscube
>
> I think this is an important note as well, one should be really thinking twice
> before (ab)using the PROVIDES mechanism :) Doesn't need to be in this patch
> though.
>
> Cheers,
> Quentin
>
diff mbox series

Patch

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 5c18b852d..2d3af4966 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7411,21 +7411,25 @@  system and gives an overview of their function and contents.
       provides itself. If a recipe uses :term:`PROVIDES`, the additional
       aliases are synonyms for the recipe and can be useful for satisfying
       dependencies of other recipes during the build as specified by
-      :term:`DEPENDS`.
+      :term:`DEPENDS` without needing to be specific as to which package
+      provides that dependency.

-      Consider the following example :term:`PROVIDES` statement from the recipe
-      file ``eudev_3.2.9.bb``::
+      As an example, the term "udev" refers to the Linux subsystem for
+      managing device events. Depending on how you configure your build,
+      that functionality can be supplied by either the ``eudev`` package
+      or by ``systemd``, which is why both of those BitBake recipes advertise
+      that with the line:

-         PROVIDES += "udev"
+         PROVIDES = "udev"

-      The :term:`PROVIDES` statement
-      results in the "eudev" recipe also being available as simply "udev".
+      Those :term:`PROVIDES` assignments result in both the ``eudev`` and
+      ``systemd`` packages being available as simply "udev".

       .. note::

-         A recipe's own recipe name (:term:`PN`) is always implicitly prepended
-         to :term:`PROVIDES`, so while using "+=" in the above example may not be
-         strictly necessary it is recommended to avoid confusion.
+         Throughout Yocto Project recipes, you will see :term:`PROVIDES`
+         assignments using both the "=" and "+=" operators;
+         both forms are valid and have the same effect.

       In addition to providing recipes under alternate names, the
       :term:`PROVIDES` mechanism is also used to implement virtual targets. A