[docs][PATCH v2] ref-manual/variables.rst: document SSTATE_SKIP_CREATION

[docs][PATCH v2] ref-manual/variables.rst: document SSTATE_SKIP_CREATION

[ecordonnier]

From: Etienne Cordonnier <ecordonnier@snap.com>

Signed-off-by: Etienne Cordonnier <ecordonnier@snap.com>
---
 documentation/ref-manual/variables.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 643a3e7ae8f..dc6dd2f1ba4 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -9049,6 +9049,26 @@ system and gives an overview of their function and contents.
 
       For details on the process, see the :ref:`ref-classes-staging` class.
 
+   :term:`SSTATE_SKIP_CREATION`
+      The :term:`SSTATE_SKIP_CREATION` variable can be used to skip the creation of
+      :ref:`shared state <overview-manual/concepts:shared state cache>` tarball files. It makes sense e.g. for image creation tasks as
+      tarring images and keeping them in sstate would consume a lot of
+      disk space.
+
+      In general it is not recommended to use this variable as missing sstate
+      artefacts adversely impact the build, particularly for entries in the
+      middle of dependency chains. The case it can make sense is where the
+      size and time costs of the artefact are similar to just running the
+      tasks. This generally only applies to end artefact output like images.
+
+      The syntax to disable it for one task is:
+
+          SSTATE_SKIP_CREATION:task-image-complete = "1"
+
+      The syntax to disable it for the whole recipe is:
+
+          SSTATE_SKIP_CREATION = "1"
+
    :term:`STAGING_BASE_LIBDIR_NATIVE`
       Specifies the path to the ``/lib`` subdirectory of the sysroot
       directory for the build host.
-- 
2.43.0

Re: [docs][PATCH v2] ref-manual/variables.rst: document SSTATE_SKIP_CREATION

[Antonin Godard]

On Fri May 23, 2025 at 1:24 PM CEST, Etienne Cordonnier via lists.yoctoproject.org wrote:
> From: Etienne Cordonnier <ecordonnier@snap.com>
>
> Signed-off-by: Etienne Cordonnier <ecordonnier@snap.com>
> ---
>  documentation/ref-manual/variables.rst | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 643a3e7ae8f..dc6dd2f1ba4 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9049,6 +9049,26 @@ system and gives an overview of their function and contents.
>  
>        For details on the process, see the :ref:`ref-classes-staging` class.
>  
> +   :term:`SSTATE_SKIP_CREATION`
> +      The :term:`SSTATE_SKIP_CREATION` variable can be used to skip the creation of
> +      :ref:`shared state <overview-manual/concepts:shared state cache>` tarball files. It makes sense e.g. for image creation tasks as

Please wrap the lines to 80 chars when possible.

> +      tarring images and keeping them in sstate would consume a lot of
> +      disk space.
> +
> +      In general it is not recommended to use this variable as missing sstate
> +      artefacts adversely impact the build, particularly for entries in the
> +      middle of dependency chains. The case it can make sense is where the
> +      size and time costs of the artefact are similar to just running the
> +      tasks. This generally only applies to end artefact output like images.
> +
> +      The syntax to disable it for one task is:

This does not render properly, you need to use two ":"

"""
The syntax to disable it for one task is::
"""

> +
> +          SSTATE_SKIP_CREATION:task-image-complete = "1"

We indent the code blocks with 3 spaces, not 4.

> +
> +      The syntax to disable it for the whole recipe is:
> +
> +          SSTATE_SKIP_CREATION = "1"
> +
>     :term:`STAGING_BASE_LIBDIR_NATIVE`
>        Specifies the path to the ``/lib`` subdirectory of the sysroot
>        directory for the build host.

Thanks,
Antonin

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