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>
---
 documentation/ref-manual/structure.rst | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)


---
base-commit: 67a239f372ed1667c923e2f407da976627be2039
change-id: 20241014-bug-14543-56fb4089086f

Best regards,

Hi Antonin,

On 10/14/24 3:44 PM, Antonin Godard via lists.yoctoproject.org 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>
> ---
>   documentation/ref-manual/structure.rst | 31 +++++++++++++++++++++++++++++--
>   1 file changed, 29 insertions(+), 2 deletions(-)
> 
> diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
> index e4d8b54bb9e39ffe344d2db1798e4fe76c742f4e..d13743cc285420b4d24f022ff6134a7ca33edcb2 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 host components that are allowed to be called within tasks. These are

some of the? I think we're missing a "the" here?

> +basic components usually pre-installed on the :ref:`supported Linux
> +distributions <system-requirements-supported-distros>`. These components are

I think this is a bit misleading as they are not necessarily 
preinstalled (I believe?) but rather part of the minimal setup required 
to get Yocto working, as documented in the link you provide there.

In any case, s/pre-installed/preinstalled/ if it were to stay.

> +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,11 @@ 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 store the kernel source code and kernel build
> +artifacts as a way to make it common to out-of-tree kernel modules or other

Can suggest:
s/as a way to make it common to/to make it available to/
or
so it's common between

But not necessarily a better wording :) Up to you!

Cheers,
Quentin

Hi Quentin,

Thanks for the reviews again.

On 15/10/2024 13:20:19+0000, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
> On 10/14/24 3:44 PM, Antonin Godard via lists.yoctoproject.org 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>
> > ---
> >   documentation/ref-manual/structure.rst | 31 +++++++++++++++++++++++++++++--
> >   1 file changed, 29 insertions(+), 2 deletions(-)
> >
> > diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
> > index e4d8b54bb9e39ffe344d2db1798e4fe76c742f4e..d13743cc285420b4d24f022ff6134a7ca33edcb2 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 host components that are allowed to be called within tasks. These are
>
> some of the? I think we're missing a "the" here?

Ha, you're right good catch.

> > +basic components usually pre-installed on the :ref:`supported Linux
> > +distributions <system-requirements-supported-distros>`. These components are
>
> I think this is a bit misleading as they are not necessarily preinstalled (I
> believe?) but rather part of the minimal setup required to get Yocto
> working, as documented in the link you provide there.

I agree, iirc git is not installed by default on every distro for example. I
will change to "basic components listed in the
:ref:`ref-manual/system-requirements:required packages for the build host`
section".

> In any case, s/pre-installed/preinstalled/ if it were to stay.

There are multiple instances of "post-installation". "pre-installation",
"pre-intall" in the docs, so I think we keep it that way (or we don't after the
rephrasing anyway :) ).

> > +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,11 @@ 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 store the kernel source code and kernel build
> > +artifacts as a way to make it common to out-of-tree kernel modules or other
>
> Can suggest:
> s/as a way to make it common to/to make it available to/
> or
> so it's common between
>
> But not necessarily a better wording :) Up to you!

Agreed on the better wording, thanks!

Cheers,
Antonin

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