diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 761be7b545..8c3cc0140f 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. + +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:: + + SRC_URI = "file://somepackage.tar.xz;subdir=${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`` directory, and should be extracted to +``${S}/usr/lib/.so.`` to be installed in :term:`D` correctly. .. note:: - 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 = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}" - - 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 ` + depending on the file extension. .. _ref-classes-binconfig: