Re: [docs] [yocto-docs PATCH] ref-manual: classes: bin_package: fix SRC_URI example

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

Hi Quentin,

On Tue Nov 19, 2024 at 10:38 AM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
> On 11/18/24 9:46 AM, Antonin Godard via lists.yoctoproject.org wrote:
>> `subdir` is the correct attribute to use for extracting the package in
>> the correct directory.
>> 
>>  From the bitbake doc:
>> 
>>    subdir: Places the file (or extracts its contents) into the specified
>>      subdirectory. This option is useful for unusual tarballs or other
>>      archives that do not have their files already in a subdirectory within
>>      the archive.
>>    subpath: Limits the checkout to a specific subpath of the tree when
>>      using the Git fetcher is used.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/ref-manual/classes.rst | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>> 
>> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
>> index b92f4e4f20ea8f702c90f4e3d29251b2461d07d0..2ac94630d80386cf613222b70f7bd6323b9948f2 100644
>> --- a/documentation/ref-manual/classes.rst
>> +++ b/documentation/ref-manual/classes.rst
>> @@ -176,7 +176,7 @@ example use for this class.
>>      are extracted into the subdirectory expected by the default value of
>>      :term:`S`::
>>   
>> -      SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}"
>> +      SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subdir=${BP}"
>>   
>
> This is not enough, subpath is mentioned in the note admonition just 
> above a few times, those need to be fixed as well.
>
> Additionally the wording is weird for the bin_package class.
>
> "class is a helper class for recipes that extract the contents of a 
> binary package (e.g. an RPM)"
> [...]
> "For RPMs and other packages that do not contain a subdirectory,"
>
> Maybe we should use another example of a binary package (e.g. a .deb 
> package) in the first sentence?
>
> Also I am not entirely sure what this example is supposed to show.
>
> SRC_URI = 
> "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}"
>
> This is very confusing to me, is this really a somepackage.rpm **git** 
> repo? or was this a mix between fetching via git and unpacking an RPM?
>
> I'm wondering what we were supposed to show with this example. Is it 
> about fetching an RPM from a git repo and only extracting a part of that 
> RPM? Is that even possible? If so, we probably want a combination of 
> subpath and subdir? subdir for the path internal to the repo to the RPM 
> and subpath for the path internal to the RPM to extract?

Actually I think I missed the point of the class description at first. It seems
to document how to fetch a subpath of a git repository containing rpm files…
Which makes me wonder: how often do you need to fetch binary from git
repositories? Probably not often.

I would have thought a more common case to be for extracting a local file, or
fetching a file over HTTP.

So I guess the description should be updated to give some more examples, yes. I
would even remove the git binary example, as it's bad practice to store binaries
in repos anyway… What do you think?

> Or, we should provide two examples, one for RPM downloaded from HTTP for 
> example, using subpath, and one for a directory from a git repo, using 
> subdir?

Actually: you'd use subpath for the git repo (to extract only a specific file
from the repo), and subdir for e.g. a tarball, to extract it in the right place.

The current description of the class is really confusing, I'll send a patch to
update it.


Antonin

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