[PATCH 0/6] (no cover subject)

[PATCH 0/6] (no cover subject)

[Adam Blank]

Updates of staging and packaging variables' descriptions following
design and implementation changes of the last few years.

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
Adam Blank (6):
      ref-manual/variables.rst: update STAGING_DIR's description
      ref-manual/variables.rst: update COMPONENTS_DIR's description
      ref-manual/variables.rst: update PKGDATA_DIR's description
      ref-manual/variables.rst: update RECIPE_SYSROOT* descriptions
      ref-manual/variables.rst: update STAGING_DIR* descriptions
      ref-manual/variables.rst: correct a reference to STAGING_DIR*

 documentation/ref-manual/variables.rst | 74 ++++++++++++++++------------------
 1 file changed, 35 insertions(+), 39 deletions(-)
---
base-commit: dc1574b9f71532c469f355af2ff5ff5664083e48
change-id: 20260408-staging_and_packaging_vars-eb7f6d92a6cc

Best regards,
-- 
Adam Blank <adam.blank.g@gmail.com>

[PATCH 1/6] ref-manual/variables.rst: update STAGING_DIR's description

[Adam Blank]

STAGING_DIR is not in direct relation to recipe-sysroot*
directries. Also it does not participate in packaging, but rather
in staging and sharing files among recipes.

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
 documentation/ref-manual/variables.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 60e608c0c..7f19723ed 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -10160,8 +10160,7 @@ system and gives an overview of their function and contents.
       directory for the build host.
 
    :term:`STAGING_DIR`
-      Helps construct the ``recipe-sysroot*`` directories, which are used
-      during packaging.
+      Used for constructing directory trees used during staging.
 
       For information on how staging for recipe-specific sysroots occurs,
       see the :ref:`ref-tasks-populate_sysroot`

-- 
2.43.0

[PATCH 2/6] ref-manual/variables.rst: update COMPONENTS_DIR's description

[Adam Blank]

Make it more evident, that it is first populated by files from
some recipes, and later used as source of those files for the
others (staging and sharing files).

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
 documentation/ref-manual/variables.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 7f19723ed..e11294c6b 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1712,7 +1712,7 @@ system and gives an overview of their function and contents.
          (set via :term:`RRECOMMENDS`) are always ignored.
 
    :term:`COMPONENTS_DIR`
-      Stores sysroot components for each recipe. The OpenEmbedded build
+      Stores sysroot components provided by each recipe. The OpenEmbedded build
       system uses :term:`COMPONENTS_DIR` when constructing recipe-specific
       sysroots for other recipes.
 

-- 
2.43.0

[PATCH 3/6] ref-manual/variables.rst: update PKGDATA_DIR's description

[Adam Blank]

Don't refer to it as temporary. Update the default value.

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
 documentation/ref-manual/variables.rst | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index e11294c6b..7d3aa8ccf 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7493,19 +7493,17 @@ system and gives an overview of their function and contents.
       Points to a shared, global-state directory that holds data generated
       during the packaging process. During the packaging process, the
       :ref:`ref-tasks-packagedata` task packages data
-      for each recipe and installs it into this temporary, shared area.
+      for each recipe and installs it into this shared area.
       This directory defaults to the following, which you should not
       change::
 
-         ${STAGING_DIR_HOST}/pkgdata
+         ${TMPDIR}/pkgdata/${MACHINE}
 
       For examples of how this data is used, see the
       ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
       section in the Yocto Project Overview and Concepts Manual and the
       ":ref:`dev-manual/debugging:viewing package information with ``oe-pkgdata-util```"
-      section in the Yocto Project Development Tasks Manual. For more
-      information on the shared, global-state directory, see
-      :term:`STAGING_DIR_HOST`.
+      section in the Yocto Project Development Tasks Manual.
 
    :term:`PKGDEST`
       Points to the parent directory for files to be packaged after they

-- 
2.43.0

[PATCH 4/6] ref-manual/variables.rst: update RECIPE_SYSROOT* descriptions

[Adam Blank]

Slightly reword to emphasise the order of steps during staging.
Further clarify those variables' relation to STAGING_DIR* variables.

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
 documentation/ref-manual/variables.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 7d3aa8ccf..aa142a701 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8345,13 +8345,13 @@ system and gives an overview of their function and contents.
       section.
 
    :term:`RECIPE_SYSROOT`
-      This variable points to the directory that holds all files populated from
+      This variable points to the directory populated with all files provided by
       recipes specified in :term:`DEPENDS`. As the name indicates,
-      think of this variable as a custom root (``/``) for the recipe that will be
+      think of this variable as a custom root (``/``) for the recipe, that will be
       used by the compiler in order to find headers and other files needed to complete
       its job.
 
-      This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET`
+      This variable is used to define :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET`
       according to the type of the recipe and the build target.
 
       To better understand this variable, consider the following examples:
@@ -8365,11 +8365,11 @@ system and gives an overview of their function and contents.
       Do not modify it.
 
    :term:`RECIPE_SYSROOT_NATIVE`
-      This is similar to :term:`RECIPE_SYSROOT` but the populated files are from
-      ``-native`` recipes. This allows a recipe built for the target machine to
-      use ``native`` tools.
+      This is similar to :term:`RECIPE_SYSROOT` but files in it are provided by
+      native recipes. This allows a recipe built for the target machine to
+      use native tools.
 
-      This variable is related to :term:`STAGING_DIR_NATIVE`.
+      This variable is used to define :term:`STAGING_DIR_NATIVE`.
 
       The default value is ``"${WORKDIR}/recipe-sysroot-native"``.
       Do not modify it.

-- 
2.43.0

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

[Adam Blank]

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). 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
+            as ``/usr``. Rather, such recipes' files are installed into
+            :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).
 
       The default value is ``"${RECIPE_SYSROOT_NATIVE}"``,
       check :term:`RECIPE_SYSROOT_NATIVE`.

-- 
2.43.0

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

[Antonin Godard]

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

[PATCH 6/6] ref-manual/variables.rst: correct a reference to STAGING_DIR*

[Adam Blank]

The reference to STAGING_DIR* variables in the description of
DEPENDS was misleading, as it pointed at STAGING_DIR which is
unrelated in this context.

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
 documentation/ref-manual/variables.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 67176917c..fbc2b78d9 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -2225,7 +2225,7 @@ system and gives an overview of their function and contents.
 
       The practical effect of the previous assignment is that all files
       installed by bar will be available in the appropriate staging sysroot,
-      given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time
+      given by the :term:`STAGING_DIR* <STAGING_DIR_HOST>` variables, by the time
       the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is
       implemented by having :ref:`ref-tasks-configure` depend on the
       :ref:`ref-tasks-populate_sysroot` task of each recipe listed in

-- 
2.43.0