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

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

[Michael Opdenacker]

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.

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.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Peter Kjellerstedt]

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

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

[Michael Opdenacker]

Hi Peter,

On 1/28/22 20:25, Peter Kjellerstedt wrote:
>> -----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.


Thanks for the review. Indeed, I was wondering too. If anyone has
details about such issues, I'll be happy to mention them in the
documentation.

Thanks in advance
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com