variables.rst: expand explanation of RSUGGESTS

Add that the RSUGGESTS variable would be processed only by a
supporting package manager when installing packages from a
package feed.

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

---

Hi,

On Tue Feb 24, 2026 at 1:15 PM CET, Robert P. J. Day wrote:
>
> Add that the RSUGGESTS variable would be processed only by a
> supporting package manager when installing packages from a
> package feed.
>
> 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 208b5e43d..92476d509 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -8361,7 +8361,9 @@ system and gives an overview of their function and contents.
>     :term:`RSUGGESTS`
>        A list of additional packages that you can suggest for installation
>        by the package manager at the time a package is installed. Not all
> -      package managers support this functionality.
> +      package managers support this functionality. This feature takes effect
> +      only when the package manager is being used to install packages on
> +      the target system from a package feed.

Could you add a link to the section explaining how to enable this?

"""
See the :ref:`dev-manual/packages:Using Runtime Package Management` section of
the Yocto Project Development Tasks Manual for more information on the
package management feature.
"""

Thanks for the patch,
Antonin

On Tue, 24 Feb 2026, Antonin Godard via lists.yoctoproject.org wrote:

> Hi,
>
> On Tue Feb 24, 2026 at 1:15 PM CET, Robert P. J. Day wrote:
> >
> > Add that the RSUGGESTS variable would be processed only by a
> > supporting package manager when installing packages from a
> > package feed.
> >
> > 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 208b5e43d..92476d509 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -8361,7 +8361,9 @@ system and gives an overview of their function and contents.
> >     :term:`RSUGGESTS`
> >        A list of additional packages that you can suggest for installation
> >        by the package manager at the time a package is installed. Not all
> > -      package managers support this functionality.
> > +      package managers support this functionality. This feature takes effect
> > +      only when the package manager is being used to install packages on
> > +      the target system from a package feed.
>
> Could you add a link to the section explaining how to enable this?
>
> """
> See the :ref:`dev-manual/packages:Using Runtime Package Management` section of
> the Yocto Project Development Tasks Manual for more information on the
> package management feature.
> """

  oh, man, did this just open up a can of worms. if you check that
section:

https://docs.yoctoproject.org/dev-manual/packages.html#using-runtime-package-management

it has no reference to RSUGGESTS, so sending readers there might be
less than useful. so should some explanation of RSUGGESTS be added
there to provide context?

  and when i scroll to the top of that chapter:

https://docs.yoctoproject.org/dev-manual/packages.html#

the first section, "Excluding Package from an Image", mentions
PACKAGE_EXCLUDE, but does not mention using IMAGE_INSTALL:remove,
which is definitely used in places i've run across. should that also
be mentioned as a way to exclude packages?

  and if so, then that operation should also be mentioned in the
explanation for IMAGE_INSTALL:

https://docs.yoctoproject.org/ref-manual/variables.html#term-IMAGE_INSTALL

  thoughts?

rday

Hi Robert,

On 2/24/26 1:55 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> On Tue, 24 Feb 2026, Antonin Godard via lists.yoctoproject.org wrote:
> 
>> Hi,
>>
>> On Tue Feb 24, 2026 at 1:15 PM CET, Robert P. J. Day wrote:
>>>
>>> Add that the RSUGGESTS variable would be processed only by a
>>> supporting package manager when installing packages from a
>>> package feed.
>>>
>>> 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 208b5e43d..92476d509 100644
>>> --- a/documentation/ref-manual/variables.rst
>>> +++ b/documentation/ref-manual/variables.rst
>>> @@ -8361,7 +8361,9 @@ system and gives an overview of their function and contents.
>>>      :term:`RSUGGESTS`
>>>         A list of additional packages that you can suggest for installation
>>>         by the package manager at the time a package is installed. Not all
>>> -      package managers support this functionality.
>>> +      package managers support this functionality. This feature takes effect
>>> +      only when the package manager is being used to install packages on
>>> +      the target system from a package feed.
>>
>> Could you add a link to the section explaining how to enable this?
>>
>> """
>> See the :ref:`dev-manual/packages:Using Runtime Package Management` section of
>> the Yocto Project Development Tasks Manual for more information on the
>> package management feature.
>> """
> 
>    oh, man, did this just open up a can of worms. if you check that
> section:
> 
> https://docs.yoctoproject.org/dev-manual/packages.html#using-runtime-package-management
> 
> it has no reference to RSUGGESTS, so sending readers there might be
> less than useful. so should some explanation of RSUGGESTS be added
> there to provide context?
> 
>    and when i scroll to the top of that chapter:
> 
> https://docs.yoctoproject.org/dev-manual/packages.html#
> 
> the first section, "Excluding Package from an Image", mentions
> PACKAGE_EXCLUDE, but does not mention using IMAGE_INSTALL:remove,

IMAGE_INSTALL:remove is *almost* always wrong.

This only has an impact if the package is explicitly listed in 
IMAGE_INSTALL variable. If that is the case, then instead of using 
:remove, simply do not add it to IMAGE_INSTALL in the first place. If 
it's not in IMAGE_INSTALL, using :remove will be a no-op.

If the package is brought in as a dependency, you need to remove 
whatever package you explicitly list in IMAGE_INSTALL that is bringing 
this package as a dependency, which may not be possible without 
rebuilding the recipe with different PACKAGECONFIG for example.

If it's brought in as a light dependency (read RRECOMMENDS), then 
BAD_RECOMMENDATIONS or NO_RECOMMENDATIONS should do the trick.

PACKAGE_EXCLUDE will prevent building and then you can easily figure out 
which packages that are to be installed in your image depend on the 
package you want to exclude from your image. This is a good starting 
point to start debugging.

> which is definitely used in places i've run across. should that also
> be mentioned as a way to exclude packages?
> 

Hard no from me. See above why I think it is a bad idea to tell people 
to do that. Maybe we should actually explain why this is a bad idea as I 
see this being repeated here and there.

Cheers,
Quentin

Hi,

On Tue Feb 24, 2026 at 1:55 PM CET, Robert P. J. Day wrote:
> On Tue, 24 Feb 2026, Antonin Godard via lists.yoctoproject.org wrote:
>
>> Hi,
>>
>> On Tue Feb 24, 2026 at 1:15 PM CET, Robert P. J. Day wrote:
>> >
>> > Add that the RSUGGESTS variable would be processed only by a
>> > supporting package manager when installing packages from a
>> > package feed.
>> >
>> > 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 208b5e43d..92476d509 100644
>> > --- a/documentation/ref-manual/variables.rst
>> > +++ b/documentation/ref-manual/variables.rst
>> > @@ -8361,7 +8361,9 @@ system and gives an overview of their function and contents.
>> >     :term:`RSUGGESTS`
>> >        A list of additional packages that you can suggest for installation
>> >        by the package manager at the time a package is installed. Not all
>> > -      package managers support this functionality.
>> > +      package managers support this functionality. This feature takes effect
>> > +      only when the package manager is being used to install packages on
>> > +      the target system from a package feed.
>>
>> Could you add a link to the section explaining how to enable this?
>>
>> """
>> See the :ref:`dev-manual/packages:Using Runtime Package Management` section of
>> the Yocto Project Development Tasks Manual for more information on the
>> package management feature.
>> """
>
>   oh, man, did this just open up a can of worms. if you check that
> section:
>
> https://docs.yoctoproject.org/dev-manual/packages.html#using-runtime-package-management
>
> it has no reference to RSUGGESTS, so sending readers there might be
> less than useful. so should some explanation of RSUGGESTS be added
> there to provide context?

Let's create a link in the variable definition as a first step, then you can
follow-up with a patch that improves this section, including the mention of
RSUGGESTS.

>   and when i scroll to the top of that chapter:
>
> https://docs.yoctoproject.org/dev-manual/packages.html#
>
> the first section, "Excluding Package from an Image", mentions
> PACKAGE_EXCLUDE, but does not mention using IMAGE_INSTALL:remove,
> which is definitely used in places i've run across. should that also
> be mentioned as a way to exclude packages?

IIRC, IMAGE_INSTALL acts on the list of packages fed to the package manager, while
PACKAGE_EXCLUDE will act on package manager specific options to exclude a
certain package from the image, *even if this package is not explicitly listed
in IMAGE_INSTALL*. I believe this is the crucial point.

However, this section should probably start by saying something like:

"""
If the IMAGE_INSTALL variable does not contain a package that you want to
exclude from your image, you can use one of the variables below to exclude it
from the image: ...
"""

>   and if so, then that operation should also be mentioned in the
> explanation for IMAGE_INSTALL:
>
> https://docs.yoctoproject.org/ref-manual/variables.html#term-IMAGE_INSTALL

As explained, those act on slightly different places, so not sure I would mix
them up, but if you think it can fit, please propose a patch, I'd be happy to
review it.

Thanks,
Antonin

On Tue, 24 Feb 2026, Quentin Schulz wrote:

> Hi Robert,
>
> On 2/24/26 1:55 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> > On Tue, 24 Feb 2026, Antonin Godard via lists.yoctoproject.org wrote:
> >
> > > Hi,
> > >
> > > On Tue Feb 24, 2026 at 1:15 PM CET, Robert P. J. Day wrote:
> > > >
> > > > Add that the RSUGGESTS variable would be processed only by a
> > > > supporting package manager when installing packages from a
> > > > package feed.
> > > >
> > > > 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 208b5e43d..92476d509 100644
> > > > --- a/documentation/ref-manual/variables.rst
> > > > +++ b/documentation/ref-manual/variables.rst
> > > > @@ -8361,7 +8361,9 @@ system and gives an overview of their function and
> > > > contents.
> > > >      :term:`RSUGGESTS`
> > > >         A list of additional packages that you can suggest for
> > > > installation
> > > >         by the package manager at the time a package is installed. Not
> > > > all
> > > > -      package managers support this functionality.
> > > > +      package managers support this functionality. This feature takes
> > > > effect
> > > > +      only when the package manager is being used to install packages
> > > > on
> > > > +      the target system from a package feed.
> > >
> > > Could you add a link to the section explaining how to enable this?
> > >
> > > """
> > > See the :ref:`dev-manual/packages:Using Runtime Package Management`
> > > section of
> > > the Yocto Project Development Tasks Manual for more information on the
> > > package management feature.
> > > """
> >
> >    oh, man, did this just open up a can of worms. if you check that
> > section:
> >
> > https://docs.yoctoproject.org/dev-manual/packages.html#using-runtime-package-management
> >
> > it has no reference to RSUGGESTS, so sending readers there might be
> > less than useful. so should some explanation of RSUGGESTS be added
> > there to provide context?
> >
> >    and when i scroll to the top of that chapter:
> >
> > https://docs.yoctoproject.org/dev-manual/packages.html#
> >
> > the first section, "Excluding Package from an Image", mentions
> > PACKAGE_EXCLUDE, but does not mention using IMAGE_INSTALL:remove,
>
> IMAGE_INSTALL:remove is *almost* always wrong.
>
> This only has an impact if the package is explicitly listed in IMAGE_INSTALL
> variable. If that is the case, then instead of using :remove, simply do not
> add it to IMAGE_INSTALL in the first place. If it's not in IMAGE_INSTALL,
> using :remove will be a no-op.
>
> If the package is brought in as a dependency, you need to remove whatever
> package you explicitly list in IMAGE_INSTALL that is bringing this package as
> a dependency, which may not be possible without rebuilding the recipe with
> different PACKAGECONFIG for example.
>
> If it's brought in as a light dependency (read RRECOMMENDS), then
> BAD_RECOMMENDATIONS or NO_RECOMMENDATIONS should do the trick.
>
> PACKAGE_EXCLUDE will prevent building and then you can easily figure out which
> packages that are to be installed in your image depend on the package you want
> to exclude from your image. This is a good starting point to start debugging.
>
> > which is definitely used in places i've run across. should that also
> > be mentioned as a way to exclude packages?
> >
>
> Hard no from me. See above why I think it is a bad idea to tell people to do
> that. Maybe we should actually explain why this is a bad idea as I see this
> being repeated here and there.

  so would it be sufficient to simply add a note here:

https://docs.yoctoproject.org/dev-manual/packages.html#excluding-packages-from-an-image

stating that, while "IMAGE_INSTALL:remove" is occasionally seen as a
way to omit a package from installation, this is almost always a bad
idea and that "PACKAGE_EXCLUDE" is the proper way?

  that at least would warn developers off.

rdayt

Hi Robert,

On 2/24/26 4:26 PM, Robert P. J. Day wrote:
> On Tue, 24 Feb 2026, Quentin Schulz wrote:
> 
>> Hi Robert,
>>
>> On 2/24/26 1:55 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
>>> On Tue, 24 Feb 2026, Antonin Godard via lists.yoctoproject.org wrote:
>>>
>>>> Hi,
>>>>
>>>> On Tue Feb 24, 2026 at 1:15 PM CET, Robert P. J. Day wrote:
>>>>>
>>>>> Add that the RSUGGESTS variable would be processed only by a
>>>>> supporting package manager when installing packages from a
>>>>> package feed.
>>>>>
>>>>> 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 208b5e43d..92476d509 100644
>>>>> --- a/documentation/ref-manual/variables.rst
>>>>> +++ b/documentation/ref-manual/variables.rst
>>>>> @@ -8361,7 +8361,9 @@ system and gives an overview of their function and
>>>>> contents.
>>>>>       :term:`RSUGGESTS`
>>>>>          A list of additional packages that you can suggest for
>>>>> installation
>>>>>          by the package manager at the time a package is installed. Not
>>>>> all
>>>>> -      package managers support this functionality.
>>>>> +      package managers support this functionality. This feature takes
>>>>> effect
>>>>> +      only when the package manager is being used to install packages
>>>>> on
>>>>> +      the target system from a package feed.
>>>>
>>>> Could you add a link to the section explaining how to enable this?
>>>>
>>>> """
>>>> See the :ref:`dev-manual/packages:Using Runtime Package Management`
>>>> section of
>>>> the Yocto Project Development Tasks Manual for more information on the
>>>> package management feature.
>>>> """
>>>
>>>     oh, man, did this just open up a can of worms. if you check that
>>> section:
>>>
>>> https://docs.yoctoproject.org/dev-manual/packages.html#using-runtime-package-management
>>>
>>> it has no reference to RSUGGESTS, so sending readers there might be
>>> less than useful. so should some explanation of RSUGGESTS be added
>>> there to provide context?
>>>
>>>     and when i scroll to the top of that chapter:
>>>
>>> https://docs.yoctoproject.org/dev-manual/packages.html#
>>>
>>> the first section, "Excluding Package from an Image", mentions
>>> PACKAGE_EXCLUDE, but does not mention using IMAGE_INSTALL:remove,
>>
>> IMAGE_INSTALL:remove is *almost* always wrong.
>>
>> This only has an impact if the package is explicitly listed in IMAGE_INSTALL
>> variable. If that is the case, then instead of using :remove, simply do not
>> add it to IMAGE_INSTALL in the first place. If it's not in IMAGE_INSTALL,
>> using :remove will be a no-op.
>>
>> If the package is brought in as a dependency, you need to remove whatever
>> package you explicitly list in IMAGE_INSTALL that is bringing this package as
>> a dependency, which may not be possible without rebuilding the recipe with
>> different PACKAGECONFIG for example.
>>
>> If it's brought in as a light dependency (read RRECOMMENDS), then
>> BAD_RECOMMENDATIONS or NO_RECOMMENDATIONS should do the trick.
>>
>> PACKAGE_EXCLUDE will prevent building and then you can easily figure out which
>> packages that are to be installed in your image depend on the package you want
>> to exclude from your image. This is a good starting point to start debugging.
>>
>>> which is definitely used in places i've run across. should that also
>>> be mentioned as a way to exclude packages?
>>>
>>
>> Hard no from me. See above why I think it is a bad idea to tell people to do
>> that. Maybe we should actually explain why this is a bad idea as I see this
>> being repeated here and there.
> 
>    so would it be sufficient to simply add a note here:
> 
> https://docs.yoctoproject.org/dev-manual/packages.html#excluding-packages-from-an-image
> 
> stating that, while "IMAGE_INSTALL:remove" is occasionally seen as a
> way to omit a package from installation, this is almost always a bad
> idea and that "PACKAGE_EXCLUDE" is the proper way?
> 
>    that at least would warn developers off.
> 

A bit more info than that (see my initial mail), but I think it makes 
sense indeed.

Quentin