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

[PATCH] 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 | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 643a3e7ae..7d8e257b9 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -9049,6 +9049,12 @@ 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`
+      SSTATE_SKIP_CREATION variable will be used to skip creation of
+      sstate 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.
+
    :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] ref-manual/variables.rst: document SSTATE_SKIP_CREATION

[Antonin Godard]

Hi,

Some suggestions and formatting related suggestions below.

On Tue May 20, 2025 at 2:39 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 | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 643a3e7ae..7d8e257b9 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9049,6 +9049,12 @@ 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`
> +      SSTATE_SKIP_CREATION variable will be used to skip creation of

s/SSTATE_SKIP_CREATION/The :term:`SSTATE_SKIP_CREATION` variable/
s/will be/can be/
s/to skip creation/to skip the creation/

> +      sstate tarball files. It makes sense e.g. for image creation tasks as

s/sstate/:ref:`shared state <overview-manual/concepts:shared state cache>`/

> +      tarring images and keeping them in sstate would consume a lot of
> +      disk space.

An example would be nice, such as:

   SSTATE_SKIP_CREATION:task-image-complete = "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

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

[Richard Purdie]

On Thu, 2025-05-22 at 11:39 +0200, Antonin Godard via lists.yoctoproject.org wrote:
> Hi,
> 
> Some suggestions and formatting related suggestions below.
> 
> On Tue May 20, 2025 at 2:39 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 | 6 ++++++
> >  1 file changed, 6 insertions(+)
> > 
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index 643a3e7ae..7d8e257b9 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -9049,6 +9049,12 @@ 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`
> > +      SSTATE_SKIP_CREATION variable will be used to skip creation of
> 
> s/SSTATE_SKIP_CREATION/The :term:`SSTATE_SKIP_CREATION` variable/
> s/will be/can be/
> s/to skip creation/to skip the creation/
> 
> > +      sstate tarball files. It makes sense e.g. for image creation tasks as
> 
> s/sstate/:ref:`shared state <overview-manual/concepts:shared state cache>`/
> 
> > +      tarring images and keeping them in sstate would consume a lot of
> > +      disk space.
> 
> An example would be nice, such as:
> 
>    SSTATE_SKIP_CREATION:task-image-complete = "1"
> 
> >     :term:`STAGING_BASE_LIBDIR_NATIVE`
> >        Specifies the path to the ``/lib`` subdirectory of the sysroot
> >        directory for the build host.

I've really not wanted this one documented in the past as I've not
wanted people using it. The reason is the implications of it. I see the
use has grown in OE-Core to multiple classes now :(.

If we do add a doc, I'd suggest adding something along the lines of:

"""
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.
"""

Cheers,

Richard

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

[Etienne Cordonnier]

[-- Attachment #1: Type: text/plain, Size: 2960 bytes --]

Hi Richard,
I'm using it to avoid some recipes from a buggy bsp layer (which can't
build from a pre-populated sstate-cache) populating my sstate-cache and
breaking builds down the line. I understand the proper fix is to fix the
recipes to work with sstate-cache, but for various reasons (e.g. no control
over a third-party bsp layer) it is not always possible.

Étienne


On Thu, May 22, 2025 at 12:36 PM Richard Purdie <
richard.purdie@linuxfoundation.org> wrote:

> On Thu, 2025-05-22 at 11:39 +0200, Antonin Godard via
> lists.yoctoproject.org wrote:
> > Hi,
> >
> > Some suggestions and formatting related suggestions below.
> >
> > On Tue May 20, 2025 at 2:39 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 | 6 ++++++
> > >  1 file changed, 6 insertions(+)
> > >
> > > diff --git a/documentation/ref-manual/variables.rst
> b/documentation/ref-manual/variables.rst
> > > index 643a3e7ae..7d8e257b9 100644
> > > --- a/documentation/ref-manual/variables.rst
> > > +++ b/documentation/ref-manual/variables.rst
> > > @@ -9049,6 +9049,12 @@ 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`
> > > +      SSTATE_SKIP_CREATION variable will be used to skip creation of
> >
> > s/SSTATE_SKIP_CREATION/The :term:`SSTATE_SKIP_CREATION` variable/
> > s/will be/can be/
> > s/to skip creation/to skip the creation/
> >
> > > +      sstate tarball files. It makes sense e.g. for image creation
> tasks as
> >
> > s/sstate/:ref:`shared state <overview-manual/concepts:shared state
> cache>`/
> >
> > > +      tarring images and keeping them in sstate would consume a lot of
> > > +      disk space.
> >
> > An example would be nice, such as:
> >
> >    SSTATE_SKIP_CREATION:task-image-complete = "1"
> >
> > >     :term:`STAGING_BASE_LIBDIR_NATIVE`
> > >        Specifies the path to the ``/lib`` subdirectory of the sysroot
> > >        directory for the build host.
>
> I've really not wanted this one documented in the past as I've not
> wanted people using it. The reason is the implications of it. I see the
> use has grown in OE-Core to multiple classes now :(.
>
> If we do add a doc, I'd suggest adding something along the lines of:
>
> """
> 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.
> """
>
> Cheers,
>
> Richard
>

[-- Attachment #2: Type: text/html, Size: 3983 bytes --]