Re: [docs] [PATCH 5/6] ref-manual/variables.rst: update STAGING_DIR* descriptions

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Wed Apr 8, 2026 at 3:05 PM CEST, Adam Blank via lists.yoctoproject.org wrote:
> Slightly reword to emphasize the sysroots' roles during the build.
> Drop double back-quote from the uses of '-native' to make it a bit
> easier on the eyes.
>
> Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
> ---
>  documentation/ref-manual/variables.rst | 45 +++++++++++++++++-----------------
>  1 file changed, 22 insertions(+), 23 deletions(-)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index aa142a701..67176917c 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -10178,31 +10178,31 @@ system and gives an overview of their function and contents.
>           those files into the sysroot.
>  
>     :term:`STAGING_DIR_HOST`
> -      Specifies the path to the sysroot directory for the system on which
> -      the component is built to run (the system that hosts the component).
> -      For most recipes, this sysroot is the one in which that recipe's
> -      :ref:`ref-tasks-populate_sysroot` task copies
> -      files. Exceptions include ``-native`` recipes, where the
> -      :ref:`ref-tasks-populate_sysroot` task instead uses
> -      :term:`STAGING_DIR_NATIVE`. Depending on
> -      the type of recipe and the build target, :term:`STAGING_DIR_HOST` can
> -      have the following values:
> +      Specifies the path to the recipe's input sysroot directory, populated with files
> +      for the system on which the component is built to run
> +      (the system that hosts the component).
> +      For most recipes, this sysroot is the one into which that recipe's files from
> +      :ref:`ref-tasks-populate_sysroot` task will be copied (when sharing files
> +      between recipes).

I'd suggest the following phrasing which is more straightforward:

"""
For most recipes, this sysroot is populated by their
:ref:`ref-tasks-populate_sysroot` task (when sharing files between recipes).
"""

> +      Exceptions include native recipes, for which the files from
> +      :ref:`ref-tasks-populate_sysroot` task are instead copied to
> +      :term:`STAGING_DIR_NATIVE`. Depending on the type of recipe and the build target,
> +      :term:`STAGING_DIR_HOST` can have the following values:
>  
>        -  For recipes building for the target machine, the value is
> -         "${:term:`STAGING_DIR`}/${:term:`MACHINE`}".
> +         ``"${RECIPE_SYSROOT}"``, check :term:`RECIPE_SYSROOT`.
>  
> -      -  For native recipes building for the build host, the value is empty
> +      -  For native recipes (building for the build host), the value is empty
>           given the assumption that when building for the build host, the
>           build host's own directories should be used.
>  
>           .. note::
>  
> -            ``-native`` recipes are not installed into host paths like such
> -            as ``/usr``. Rather, these recipes are installed into
> -            :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes,
> +            Native recipes' files are not installed into host paths such

s/Native recipes' files/Native recipe files/

> +            as ``/usr``. Rather, such recipes' files are installed into

s/such recipes' files/such files/

> +            :term:`STAGING_DIR_NATIVE`. When compiling native recipes,
>              standard build environment variables such as
>              :term:`CPPFLAGS` and
> -            :term:`CFLAGS` are set up so that both host paths
> +            :term:`CFLAGS` are set up so that both build host's paths
>              and :term:`STAGING_DIR_NATIVE` are searched for libraries and
>              headers using, for example, GCC's ``-isystem`` option.
>  
> @@ -10210,16 +10210,15 @@ system and gives an overview of their function and contents.
>              should be viewed as input variables by tasks such as
>              :ref:`ref-tasks-configure`,
>              :ref:`ref-tasks-compile`, and
> -            :ref:`ref-tasks-install`. Having the real system
> -            root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense
> -            for ``-native`` recipes, as they make use of host headers and
> -            libraries.
> -
> -      Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`.
> +            :ref:`ref-tasks-install`. Having the real system root
> +            (the build host's root) play the role of :term:`STAGING_DIR_HOST`
> +            makes conceptual sense for native recipes, as they make use
> +            of the build host's headers and libraries.
>  
>     :term:`STAGING_DIR_NATIVE`
> -      Specifies the path to the sysroot directory used when building
> -      components that run on the build host itself.
> +      Specifies the path to the recipe's input sysroot directory, populated with
> +      files provided by native recipes (recipes building components that
> +      run on the build host itself).

s/build host/:term:`build host`/

Can you make this replacement in the different places where it is used in your
patches?

The rest of the patches look good. Thanks for splitting the patches and for the
commit descriptions, it helped :)

Antonin