[yocto-docs][PATCH v4] ref-manual: classes: fix bin_package description

[yocto-docs][PATCH v4] ref-manual: classes: fix bin_package description

[Antonin Godard]

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.

Update the description by telling what it really does and what it
doesn't do, and by giving an HTTPS+RPM example.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v4:
- Typos / corrections spotted by Quentin.
- Add tarball example.
- Link to v3: https://lore.kernel.org/r/20241127-fix-bin-package-v3-1-ee09055000ac@bootlin.com

Changes in v3:
- Actually explain what bin_package does and what it doesn't do.
- Link to v2: https://lore.kernel.org/r/20241120-fix-bin-package-v2-1-917a5c2745d2@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 | 45 ++++++++++++++++++++++--------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index b92f4e4f20ea8f702c90f4e3d29251b2461d07d0..e7a8925806e1b6ea21e251c797c83d54b7049756 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -159,27 +159,38 @@ software that includes bash-completion data.
 ``bin_package``
 ===============
 
-The :ref:`ref-classes-bin-package` class is a helper class for recipes that extract the
-contents of a binary package (e.g. an RPM) and install those contents
-rather than building the binary from source. The binary package is
-extracted and new packages in the configured output package format are
-created. Extraction and installation of proprietary binaries is a good
-example use for this class.
+The :ref:`ref-classes-bin-package` class is a helper class for recipes, that
+disables the :ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` tasks and
+copies the content of the :term:`S` directory into the :term:`D` directory. This
+is useful for installing binary packages (e.g. RPM packages) by passing the
+package in the :term:`SRC_URI` variable and inheriting this class.
 
-.. note::
+For RPMs and other packages that do not contain a subdirectory, you should set
+the :term:`SRC_URI` option ``subdir`` to :term:`BP` so that the contents are
+extracted to the directory expected by the default value of :term:`S`. For
+example::
+
+   SRC_URI = "https://example.com/downloads/somepackage.rpm;subdir=${BP}"
+
+This class can also be used for tarballs. For example::
 
-   For RPMs and other packages that do not contain a subdirectory, you
-   should specify an appropriate fetcher parameter to point to the
-   subdirectory. For example, if BitBake is using the Git fetcher (``git://``),
-   the "subpath" parameter limits the checkout to a specific subpath
-   of the tree. Here is an example where ``${BP}`` is used so that the files
-   are extracted into the subdirectory expected by the default value of
-   :term:`S`::
+   SRC_URI = "file://somepackage.tar.xz;subdir=${BP}"
 
-      SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}"
+The :ref:`ref-classes-bin-package` class will copy the extracted content of the
+tarball from :term:`S` to :term:`D`.
+
+This class assumes that the content of the package as installed in :term:`S`
+mirrors the expected layout once installed on the target, which is generally the
+case for binary packages. For example, an RPM package for a library would
+usually contain the ``usr/lib`` directories, and should be extracted to
+``${S}/usr/lib/<library>.so.<version>`` to be installed in :term:`D` correctly.
+
+.. note::
 
-   See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for
-   more information on supported BitBake Fetchers.
+   The extraction of the package passed in :term:`SRC_URI` is not handled by the
+   :ref:`ref-classes-bin-package` class, but rather by the appropriate
+   :ref:`fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
+   depending on the file extension.
 
 .. _ref-classes-binconfig:
 

---
base-commit: 4175839e718db49bf6971e900c1cf176d03458d7
change-id: 20241115-fix-bin-package-eed7633fbecd

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

Re: [yocto-docs][PATCH v4] ref-manual: classes: fix bin_package description

[Quentin Schulz]

Hi Antonin,

On 11/27/24 5:01 PM, 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.
> 
> Update the description by telling what it really does and what it
> doesn't do, and by giving an HTTPS+RPM example.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
> Changes in v4:
> - Typos / corrections spotted by Quentin.
> - Add tarball example.
> - Link to v3: https://lore.kernel.org/r/20241127-fix-bin-package-v3-1-ee09055000ac@bootlin.com
> 
> Changes in v3:
> - Actually explain what bin_package does and what it doesn't do.
> - Link to v2: https://lore.kernel.org/r/20241120-fix-bin-package-v2-1-917a5c2745d2@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 | 45 ++++++++++++++++++++++--------------
>   1 file changed, 28 insertions(+), 17 deletions(-)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index b92f4e4f20ea8f702c90f4e3d29251b2461d07d0..e7a8925806e1b6ea21e251c797c83d54b7049756 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -159,27 +159,38 @@ software that includes bash-completion data.
>   ``bin_package``
>   ===============
>   
> -The :ref:`ref-classes-bin-package` class is a helper class for recipes that extract the
> -contents of a binary package (e.g. an RPM) and install those contents
> -rather than building the binary from source. The binary package is
> -extracted and new packages in the configured output package format are
> -created. Extraction and installation of proprietary binaries is a good
> -example use for this class.
> +The :ref:`ref-classes-bin-package` class is a helper class for recipes, that
> +disables the :ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` tasks and
> +copies the content of the :term:`S` directory into the :term:`D` directory. This
> +is useful for installing binary packages (e.g. RPM packages) by passing the
> +package in the :term:`SRC_URI` variable and inheriting this class.
>   
> -.. note::
> +For RPMs and other packages that do not contain a subdirectory, you should set
> +the :term:`SRC_URI` option ``subdir`` to :term:`BP` so that the contents are
> +extracted to the directory expected by the default value of :term:`S`. For
> +example::
> +
> +   SRC_URI = "https://example.com/downloads/somepackage.rpm;subdir=${BP}"
> +
> +This class can also be used for tarballs. For example::
>   
> -   For RPMs and other packages that do not contain a subdirectory, you
> -   should specify an appropriate fetcher parameter to point to the
> -   subdirectory. For example, if BitBake is using the Git fetcher (``git://``),
> -   the "subpath" parameter limits the checkout to a specific subpath
> -   of the tree. Here is an example where ``${BP}`` is used so that the files
> -   are extracted into the subdirectory expected by the default value of
> -   :term:`S`::
> +   SRC_URI = "file://somepackage.tar.xz;subdir=${BP}"
>   
> -      SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}"
> +The :ref:`ref-classes-bin-package` class will copy the extracted content of the
> +tarball from :term:`S` to :term:`D`.
> +
> +This class assumes that the content of the package as installed in :term:`S`
> +mirrors the expected layout once installed on the target, which is generally the
> +case for binary packages. For example, an RPM package for a library would
> +usually contain the ``usr/lib`` directories, and should be extracted to

s/directories/directory/ ?

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [yocto-docs][PATCH v4] ref-manual: classes: fix bin_package description

[Antonin Godard]

Hi Quentin,

On Thu Nov 28, 2024 at 11:07 AM CET, Quentin Schulz wrote:
[...]
>> +This class assumes that the content of the package as installed in :term:`S`
>> +mirrors the expected layout once installed on the target, which is generally the
>> +case for binary packages. For example, an RPM package for a library would
>> +usually contain the ``usr/lib`` directories, and should be extracted to
>
> s/directories/directory/ ?

+1!

> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>
> Thanks!
> Quentin

Thank you,
Antonin

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