Re: [yocto-docs][PATCH v2] Update the documentation for SRCPV

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

On 11/27/24 9:18 AM, Antonin Godard wrote:
> Hi Quentin,
> 
> On Mon Nov 25, 2024 at 4:57 PM CET, Quentin Schulz wrote:
>> Hi Antonin,
>>
>> On 11/25/24 9:17 AM, Antonin Godard wrote:
>>> The variable SRCPV is deprecated since 4.3. Instead of including SRCPV
>>> in PV, including the sign "+" is enough for bitbake to add the source
>>> control information to PKGV during the packaging phase.
>>>
>>> Update the documentation for SRCPV and the places where it was used.
>>> When instructions previously referred to SRCPV, replace by mentioning to
>>> include "+" in the assignment.
>>>
>>> In most examples, "+git" is added to PV as it is the most popular SCM.
>>> Simply adding "+" is also possible, although it is better practice to
>>> include the SCM name, so give that example.
>>>
>>> Update the gcompat example with l3afpad as it didn't include "+git" in
>>> its PV definition anymore.
>>>
>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>> ---
>> [...]
>>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>>> index ec4d7ab73fe3ac1bc64f5378c65d19ae0b749809..f611edae9f37097734234805faa34b1850e5cfd1 100644
>>> --- a/documentation/ref-manual/variables.rst
>>> +++ b/documentation/ref-manual/variables.rst
>>> @@ -209,12 +209,11 @@ system and gives an overview of their function and contents.
>>>             SRCREV = "${AUTOREV}"
>>>    
>>>          If you use the previous statement to retrieve the latest version of
>>> -      software, you need to be sure :term:`PV` contains
>>> -      ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you have a kernel
>>> -      recipe that inherits the :ref:`ref-classes-kernel` class and you
>>> -      use the previous statement. In this example, ``${SRCPV}`` does not
>>> -      automatically get into :term:`PV`. Consequently, you need to change
>>> -      :term:`PV` in your recipe so that it does contain ``${SRCPV}``.
>>> +      software, you need to make sure :term:`PV` contains the ``+`` sign so
>>> +      :term:`bitbake` includes source control information to :term:`PKGV` when
>>> +      packaging the recipe. For example::
>>> +
>>> +        PV = "6.10.y+git"
>>>    
>>
>> I believe this is not properly indented? Missing a space here to follow
>> our standards?
> 
> 
> Good catch, thank you. Some others below are also not properly indented. It
> would be nice if sphinx-lint could report this, but I don't think it is able to.
> 

It's open-source, so maybe something we can contribute :)

>>>          For more information see the
>>>          ":ref:`dev-manual/packages:automatically incrementing a package version number`"
>>> @@ -5152,7 +5151,7 @@ system and gives an overview of their function and contents.
>>>          The :term:`LINUX_VERSION` variable is used to define :term:`PV`
>>>          for the recipe::
>>>    
>>> -         PV = "${LINUX_VERSION}+git${SRCPV}"
>>> +         PV = "${LINUX_VERSION}+git"
>>>    
>>>       :term:`LINUX_VERSION_EXTENSION`
>>>          A string extension compiled into the version string of the Linux
>>> @@ -6720,9 +6719,10 @@ system and gives an overview of their function and contents.
>>>          For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
>>>          where ``foo_git.bb`` contains the following assignment::
>>>    
>>> -         PV = "1.1+git${SRCPV}"
>>> +         PV = "1.1+git${@bb.fetch2.get_srcrev(d)}"
>>>    
>>
>> Getting back at my original comment in v1 (forgot to answer again there,
>> so doing it here). I'm not sure this makes sense as an example as it is
>> not necessary anymore since + character is enough to include that
>> information in PKGV (as far as I understood from the patch). I would
> 
> Exactly, "+" is enough now.
> 
>> like to avoid suggesting using something that isn't relevant here (or
>> discouraged).
>>
>> I think we could simplify the example. The point is not necessarily to
>> use % with a git-named recipe but rather that a git-named recipe is not
>> going to match "git" but the "PV" defined in the recipe. What do you think?
> 
> Ok, something like:
> 
>    If your PV is equal to "a.b.c+git", you can match it with "a.b.c%" in
>    PREFERRED_VERSION?
> 
> This makes more sense with the current state of things, and simplifies the
> example a bit.
> 

"""
If you want to select a recipe named foo_git.bb which has :term:`PV` set 
to `1.2.3+git`, you can do so by setting :term:`PREFERRED_VERSION_foo` 
to `1.2.3%` (i.e. using simply `git` will not work as the name of the 
recipe isn't used, but rather its :term:`PV`).
"""

or something like that?

Is PV really extended with the git hash when there's a + in there or is 
it only PKGV that gets it? Basically, do you even need % character when 
we have a + in PV now?

Not sure it's clear, lemme know if I need to rephrase my question.

Cheers,
Quentin