RE: [docs] [PATCH] ref-manual: add usage details about ccache.bbclass

[Peter Kjellerstedt <peter.kjellerstedt@axis.com>]

> -----Original Message-----
> From: docs@lists.yoctoproject.org <docs@lists.yoctoproject.org> On Behalf Of Michael Opdenacker via lists.yoctoproject.org
> Sent: den 28 januari 2022 16:56
> To: docs@lists.yoctoproject.org
> Subject: Re: [docs] [PATCH] ref-manual: add usage details about ccache.bbclass
> 
> On 1/28/22 16:53, Michael Opdenacker via lists.yoctoproject.org wrote:
> > Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> > ---
> >  documentation/ref-manual/classes.rst | 13 +++++++++----
> >  1 file changed, 9 insertions(+), 4 deletions(-)
> >
> > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> > index d9065b3619..949217bf42 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -274,10 +274,15 @@ sstate re-use. In order to function, this class requires the
> >
> >  The ``ccache`` class enables the C/C++ Compiler Cache for the build.
> >  This class is used to give a minor performance boost during the build.
> > -However, using the class can lead to unexpected side-effects. Thus, it
> > -is recommended that you do not use this class. See
> > -https://ccache.samba.org/ for information on the C/C++ Compiler
> > -Cache.
> > +
> > +See https://ccache.samba.org/ for information on the C/C++ Compiler
> > +Cache, and the :oe_git:`ccache.bbclass </openembedded-core/tree/meta/classes/ccache.bbclass>`
> > +file for details about how to enable this mechanism in your configuration
> > +file, how to disable it for specific recipes, and how to share ``ccache``
> > +files between builds.
> > +
> > +However, using the class can lead to unexpected side-effects. Thus, using
> > +this class is not recommended.

It would probably be a good idea then to explain what those 
unexpected side-effects are, or you leave the reader hanging. 
That way it easier to make an educated choice whether using 
the class is a good idea or not.

> I guess it could be controversial to add usage details for a class that
> the manual recommends not to use. On the other hand, if we keep this
> class in oe-core, that must be because there are some people who still
> want to use it. Then, it makes sense to have usage details IMHO.
> 
> Any thoughts about this?
> 
> Cheers
> Michael.

//Peter