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

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Quentin,

On Fri Dec 6, 2024 at 3:45 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 11/27/24 5:23 PM, Antonin Godard wrote:
> [...]
>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>> index ec4d7ab73fe3ac1bc64f5378c65d19ae0b749809..9bc07336a750beaf5c1cda8272f39803eb53901e 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"
>>   
>>         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
>> @@ -6702,9 +6701,7 @@ system and gives an overview of their function and contents.
>>   
>>         The :term:`PREFERRED_VERSION` variable supports limited wildcard use
>>         through the "``%``" character. You can use the character to match any
>> -      number of characters, which can be useful when specifying versions
>> -      that contain long revision numbers that potentially change. Here are
>
> I would keep some of this in. This is actually a good tip on how to 
> properly support bbappending in layers. E.g. gstreamer1.0 often gets its 
> minor version changed in the same release branch. If you want your layer 
> to be compatible with all previous, current and future minor versions of 
> the recipe, you can simply use e.g. 
> gstreamer1.0-plugins-base_1.24.%.bbappend!

You're right, I will add that back in a v4.

>> -      two examples::
>> +      number of characters. Here are two examples::
>>   
>>            PREFERRED_VERSION_python = "3.4.0"
>>            PREFERRED_VERSION_linux-yocto = "5.0%"
>> @@ -6715,22 +6712,13 @@ system and gives an overview of their function and contents.
>>            string. You cannot use the wildcard character in any other
>>            location of the string.
>>   
>> -      The specified version is matched against :term:`PV`, which
>> -      does not necessarily match the version part of the recipe's filename.
>> -      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}"
>> -
>> -      In this case, the correct way to select
>> -      ``foo_git.bb`` is by using an assignment such as the following::
>> -
>> -         PREFERRED_VERSION_foo = "1.1+git%"
>> +      The specified version is matched against :term:`PV`, which does not
>> +      necessarily match the version part of the recipe's filename.
>>   
>> -      Compare that previous example
>> -      against the following incorrect example, which does not work::
>> -
>> -         PREFERRED_VERSION_foo = "git"
>> +      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 ```PREFERRED_VERSION_foo``
>> +      to ``1.2.3%`` (i.e. simply using ``git`` will not work as the name of the
>
> s/simply using/simply setting ``PREFERRED_VERSION_foo`` to/
>
> The fact we remove git entirely from PREFERRED_VERSION_foo and say 
> "simply using git will not work" may be a bit confusing, so making 
> explicit what exactly won't work is better?

Yes, it's a bit more clear that way, I'll update

>> +      recipe isn't used, but rather its :term:`PV` definition).
>>   
>>         Sometimes the :term:`PREFERRED_VERSION` variable can be set by
>>         configuration files in a way that is hard to change. You can use
>> @@ -8316,21 +8304,23 @@ system and gives an overview of their function and contents.
>>         (SCM).
>>   
>>      :term:`SRCPV`
>> -      Returns the version string of the current package. This string is
>> -      used to help define the value of :term:`PV`.
>> +      The variable :term:`SRCPV` is deprecated. It was previously used to
>> +      include source control information in :term:`PV` for :term:`bitbake` to
>> +      work correctly but this is no longer a requirement. Source control
>> +      information will be automatically included by :term:`bitbake` in the
>> +      variable :term:`PKGV` during packaging if the ``+`` sign is present in
>> +      ``PV``.
>
> :term:`PV` ?

Will update

> Looking good otherwise!

Thanks for the review!
Antonin

--
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com