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