Message ID | 20241127-fix-bin-package-v4-1-e7f7c2325dea@bootlin.com |
---|---|
State | New |
Headers | show |
Series | [yocto-docs,v4] ref-manual: classes: fix bin_package description | expand |
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
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
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:
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(-) --- base-commit: 4175839e718db49bf6971e900c1cf176d03458d7 change-id: 20241115-fix-bin-package-eed7633fbecd Best regards,