[yocto-docs,v2] ref-manual: classes: fix bin_package description

The previous bin_package description was confusing: it would instruct to
use the git fetcher to extract the content of an RPM package using the
`subpath` option - but that's not possible as the git fetcher can be
used to clone a repository but not to do the extraction.

Simplify the example with the HTTP fetcher that points to an RPM file,
and instruct the user to use `subdir` to extract its content to the
directory expected by S.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v2:
- Instead of updating the example, update the description of the class
  with a more common (and working) example usage of the class.
- Link to v1: https://lore.kernel.org/r/20241118-fix-bin-package-v1-1-906f0148fdaa@bootlin.com
---
 documentation/ref-manual/classes.rst | 38 ++++++++++++++++--------------------
 1 file changed, 17 insertions(+), 21 deletions(-)


---
base-commit: 7d5eb0cee5b2b7096969819d7d7ce569a3c92f27
change-id: 20241115-fix-bin-package-eed7633fbecd

Best regards,

Hi Antonin,

On 11/20/24 8:57 AM, Antonin Godard wrote:
> The previous bin_package description was confusing: it would instruct to
> use the git fetcher to extract the content of an RPM package using the
> `subpath` option - but that's not possible as the git fetcher can be
> used to clone a repository but not to do the extraction.
> 
> Simplify the example with the HTTP fetcher that points to an RPM file,
> and instruct the user to use `subdir` to extract its content to the
> directory expected by S.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

[...]
> +The :ref:`ref-classes-bin-package` class is a helper class for recipes that
> +extracts the contents of a binary package (e.g. an RPM package) and installs
> +those contents rather than building the binary from source. The binary package
> +is extracted and new packages in the configured output package format are

I think this is actually all misleading, this is not what bin_package 
class does.

What it does is disable the configure and compile tasks, take the 
entirety of ${S} (aside from patches/ and .pc/ directories) and install 
it in ${D}.

However, it is mostly useful when providing RPMs/tarballs/debs, etc... 
but the extraction is actually done by the fetcher I believe?

While looking in the fetcher, I discovered that there's a parameter we 
haven't documented yet for RPMs which is "extract", c.f. 
https://git.openembedded.org/bitbake/tree/lib/bb/fetch2/__init__.py#n1568 
I believe this is a way to extract only one (or more?) files from an RPM 
and then extract it again? c.f. commit 
906285ff00d6ffd3fd7713af52250e7c6503edb7 in poky. Unrelated though :)

So we should document this and states for what kind of recipes this is 
usually inherited but I think the current content is inadequate?

Cheers,
Quentin

Hi Quentin,

On Mon Nov 25, 2024 at 5:28 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 11/20/24 8:57 AM, Antonin Godard wrote:
>> The previous bin_package description was confusing: it would instruct to
>> use the git fetcher to extract the content of an RPM package using the
>> `subpath` option - but that's not possible as the git fetcher can be
>> used to clone a repository but not to do the extraction.
>> 
>> Simplify the example with the HTTP fetcher that points to an RPM file,
>> and instruct the user to use `subdir` to extract its content to the
>> directory expected by S.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>
> [...]
>> +The :ref:`ref-classes-bin-package` class is a helper class for recipes that
>> +extracts the contents of a binary package (e.g. an RPM package) and installs
>> +those contents rather than building the binary from source. The binary package
>> +is extracted and new packages in the configured output package format are
>
> I think this is actually all misleading, this is not what bin_package 
> class does.
>
> What it does is disable the configure and compile tasks, take the 
> entirety of ${S} (aside from patches/ and .pc/ directories) and install 
> it in ${D}.

True.

> However, it is mostly useful when providing RPMs/tarballs/debs, etc... 
> but the extraction is actually done by the fetcher I believe?

Yes.

> While looking in the fetcher, I discovered that there's a parameter we 
> haven't documented yet for RPMs which is "extract", c.f. 
> https://git.openembedded.org/bitbake/tree/lib/bb/fetch2/__init__.py#n1568 
> I believe this is a way to extract only one (or more?) files from an RPM 
> and then extract it again? c.f. commit 
> 906285ff00d6ffd3fd7713af52250e7c6503edb7 in poky. Unrelated though :)

Interesting (and old) find :) I couldn't find examples of this in poky, and
there's no test associated to it. I think we should probably add both doc and
test, probably.

> So we should document this and states for what kind of recipes this is
> usually inherited but I think the current content is inadequate?

Right I agree, I'll explain the S to D copying, which is what bin_package does.
And mention that the extraction is done by the fetcher in most cases.


Antonin