[v3] ref-manual: structure.rst: document missing tmp/ dirs

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,

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