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

[Richard Purdie <richard.purdie@linuxfoundation.org>]

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