Message ID | 20241016-bug-14543-v3-1-35ff2724e662@bootlin.com |
---|---|
State | New |
Headers | show |
Series | [v3] ref-manual: structure.rst: document missing tmp/ dirs | expand |
Hi Antonin, On 10/16/24 5:24 PM, Antonin Godard wrote: > Document `hosttools/`, `pkgdata/` and add some more information on > `work-shared/`. > > Adresses [YOCTO #14543]. > > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> > Reported-by: Robert P. J. Day <rpjday@crashcourse.ca> > --- > Changes in v3: > - Rephrase triple "to" to "to make the kernel source code and kernel > build artifacts available to..." > - Add a note on the rarity of using this directory, and an example of > when it's used. > - Link to v2: https://lore.kernel.org/r/20241016-bug-14543-v2-1-df3038344377@bootlin.com > > Changes in v2: > - hosttools: add missing "the" > - hosttools: Remove "pre-installed" packages and point to host > requirements section instead. > - work-shared: s/as a way to make it common to/to make it available to/ > - Link to v1: https://lore.kernel.org/r/20241014-bug-14543-v1-1-7c8519be9c9c@bootlin.com > --- > documentation/ref-manual/structure.rst | 35 ++++++++++++++++++++++++++++++++-- > 1 file changed, 33 insertions(+), 2 deletions(-) > > diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst > index e4d8b54bb9e39ffe344d2db1798e4fe76c742f4e..bbeda78c791d430faa55356a3209f5eeb1402837 100644 > --- a/documentation/ref-manual/structure.rst > +++ b/documentation/ref-manual/structure.rst > @@ -484,6 +484,30 @@ the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" > section in the Yocto Project Application Development and the Extensible > Software Development Kit (eSDK) manual. > > +.. _structure-build-tmp-hosttools: > + > +``build/tmp/hosttools/`` > +~~~~~~~~~~~~~~~~~~~~~~~~ > + > +The OpenEmbedded build system uses this directory to create symbolic links to > +some of the host components that are allowed to be called within tasks. These > +are basic components listed in the :ref:`ref-manual/system-requirements:required > +packages for the build host` section. These components are also listed in the > +:term:`HOSTTOOLS` variable and are limited to this list to prevent host > +contamination. > + > +.. _structure-build-tmp-pkgdata: > + > +``build/tmp/pkgdata/`` > +~~~~~~~~~~~~~~~~~~~~~~ > + > +The OpenEmbedded build system uses this directory to store package metadata > +generated during the :ref:`ref-tasks-packagedata` task. The files stored in this > +directory contain information about each output package produced by the > +OpenEmbedded build system, and are used in different ways by the build system > +such as ":ref:`dev-manual/debugging:viewing package information with > +\`\`oe-pkgdata-util\`\``". > + > .. _structure-build-tmp-sstate-control: > > ``build/tmp/sstate-control/`` > @@ -657,8 +681,15 @@ Here are key subdirectories within each recipe work directory: > > For efficiency, the OpenEmbedded build system creates and uses this > directory to hold recipes that share a work directory with other > -recipes. In practice, this is only used for ``gcc`` and its variants > -(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth). > +recipes. This is for example used for ``gcc`` and its variants (e.g. > +``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth), or by the > +:ref:`ref-classes-kernel` class to make the kernel source code and kernel build > +artifacts available to out-of-tree kernel modules or other kernel-dependent > +recipes. > + > +In practice, only a few recipes make use of the ``work-shared`` directory. This > +directory is especially useful for recipes that would induce a lot of storage > +space if they were to be shared with the standard :term:`Sysroot` mechanism. > Provided that's a legit justification for using work-shared (I really do not know :) ), Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> Thanks! Quentin
Hi Quentin, On Wed Oct 16, 2024 at 5:34 PM CEST, Quentin Schulz wrote: > > For efficiency, the OpenEmbedded build system creates and uses this > > directory to hold recipes that share a work directory with other > > -recipes. In practice, this is only used for ``gcc`` and its variants > > -(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth). > > +recipes. This is for example used for ``gcc`` and its variants (e.g. > > +``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth), or by the > > +:ref:`ref-classes-kernel` class to make the kernel source code and kernel build > > +artifacts available to out-of-tree kernel modules or other kernel-dependent > > +recipes. > > + > > +In practice, only a few recipes make use of the ``work-shared`` directory. This > > +directory is especially useful for recipes that would induce a lot of storage > > +space if they were to be shared with the standard :term:`Sysroot` mechanism. > > > > Provided that's a legit justification for using work-shared (I really do > not know :) ), I chose the above wording to express that it is _one_ of the things it is used for, it doesn't really imply that it's the _only_ thing it's used for… so it's not set in stone. :) > Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> > > Thanks! > Quentin Thank you, Antonin -- Antonin Godard, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst index e4d8b54bb9e39ffe344d2db1798e4fe76c742f4e..bbeda78c791d430faa55356a3209f5eeb1402837 100644 --- a/documentation/ref-manual/structure.rst +++ b/documentation/ref-manual/structure.rst @@ -484,6 +484,30 @@ the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual. +.. _structure-build-tmp-hosttools: + +``build/tmp/hosttools/`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +The OpenEmbedded build system uses this directory to create symbolic links to +some of the host components that are allowed to be called within tasks. These +are basic components listed in the :ref:`ref-manual/system-requirements:required +packages for the build host` section. These components are also listed in the +:term:`HOSTTOOLS` variable and are limited to this list to prevent host +contamination. + +.. _structure-build-tmp-pkgdata: + +``build/tmp/pkgdata/`` +~~~~~~~~~~~~~~~~~~~~~~ + +The OpenEmbedded build system uses this directory to store package metadata +generated during the :ref:`ref-tasks-packagedata` task. The files stored in this +directory contain information about each output package produced by the +OpenEmbedded build system, and are used in different ways by the build system +such as ":ref:`dev-manual/debugging:viewing package information with +\`\`oe-pkgdata-util\`\``". + .. _structure-build-tmp-sstate-control: ``build/tmp/sstate-control/`` @@ -657,8 +681,15 @@ Here are key subdirectories within each recipe work directory: For efficiency, the OpenEmbedded build system creates and uses this directory to hold recipes that share a work directory with other -recipes. In practice, this is only used for ``gcc`` and its variants -(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth). +recipes. This is for example used for ``gcc`` and its variants (e.g. +``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth), or by the +:ref:`ref-classes-kernel` class to make the kernel source code and kernel build +artifacts available to out-of-tree kernel modules or other kernel-dependent +recipes. + +In practice, only a few recipes make use of the ``work-shared`` directory. This +directory is especially useful for recipes that would induce a lot of storage +space if they were to be shared with the standard :term:`Sysroot` mechanism. .. _structure-meta:
Document `hosttools/`, `pkgdata/` and add some more information on `work-shared/`. Adresses [YOCTO #14543]. Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> Reported-by: Robert P. J. Day <rpjday@crashcourse.ca> --- Changes in v3: - Rephrase triple "to" to "to make the kernel source code and kernel build artifacts available to..." - Add a note on the rarity of using this directory, and an example of when it's used. - Link to v2: https://lore.kernel.org/r/20241016-bug-14543-v2-1-df3038344377@bootlin.com Changes in v2: - hosttools: add missing "the" - hosttools: Remove "pre-installed" packages and point to host requirements section instead. - work-shared: s/as a way to make it common to/to make it available to/ - Link to v1: https://lore.kernel.org/r/20241014-bug-14543-v1-1-7c8519be9c9c@bootlin.com --- documentation/ref-manual/structure.rst | 35 ++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) --- base-commit: 1304b899cd4480f80eaeb6e58d57e87d3d2f6911 change-id: 20241014-bug-14543-56fb4089086f Best regards,