[PATCH v2 2/5] classes.rst: document openssl-native.bbclass

[PATCH v2 2/5] classes.rst: document openssl-native.bbclass

[Mikko Rapeli]

It sets various environment variables correctly for openssl-native.

Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
---
 documentation/ref-manual/classes.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 11e0d472e8..5fc30f9233 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1672,6 +1672,17 @@ one such example. However, being aware of this class can reduce the
 proliferation of different versions of similar classes across multiple
 layers.
 
+.. _ref-classes-openssl-native:
+
+``openssl-native.bbclass``
+==================
+
+The ``openssl-native`` class supports using the native version of openssl
+built by the build system rather than support of the version provided
+by the build host. It helps setting environment variables for engines,
+modules, certificates etc correctly. For full certificate checking
+users should also add ``ca-certificates-native`` to :term:`DEPENDS`.
+
 .. _ref-classes-overlayfs:
 
 ``overlayfs.bbclass``
-- 
2.17.1

Re: [docs] [PATCH v2 2/5] classes.rst: document openssl-native.bbclass

[Quentin Schulz]

Hi Mikko,

On 10/4/22 17:27, Mikko Rapeli wrote:
> It sets various environment variables correctly for openssl-native.
> 
> Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> ---
>   documentation/ref-manual/classes.rst | 11 +++++++++++
>   1 file changed, 11 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 11e0d472e8..5fc30f9233 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1672,6 +1672,17 @@ one such example. However, being aware of this class can reduce the
>   proliferation of different versions of similar classes across multiple
>   layers.
>   
> +.. _ref-classes-openssl-native:
> +
> +``openssl-native.bbclass``
> +==================
> +
> +The ``openssl-native`` class supports using the native version of openssl

The :ref:`openssl-native <ref-classes-openssl-native>` class supports 
using the native version of ``openssl``
> +built by the build system rather than support of the version provided
> +by the build host. It helps setting environment variables for engines,
> +modules, certificates etc correctly. For full certificate checking
> +users should also add ``ca-certificates-native`` to :term:`DEPENDS`.
> +

I could suggest:
"""
built by the Yocto Project instead of the one provided by the build host 
distribution.
"""

I find "rather than support of the version..." confusing.

I think we could also replace the "It helps" sentence by stating that 
any recipe requiring openssl to be run on the host should inherit this 
class instead of just adding openssl-native to DEPENDS. Maybe that could 
even be a new QA check?

I would still keep the last sentence though.

What do you think?

(Thank you for sending a documentation patch in the same series as the 
code implementation, this is rare enough to be highlighted, much 
appreciated!)

Cheers,
Quentin

Re: [docs] [PATCH v2 2/5] classes.rst: document openssl-native.bbclass

[Mikko Rapeli]

Hi,

On Wed, Oct 05, 2022 at 10:31:25AM +0200, Quentin Schulz wrote:
> Hi Mikko,
> 
> On 10/4/22 17:27, Mikko Rapeli wrote:
> > It sets various environment variables correctly for openssl-native.
> > 
> > Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> > ---
> >   documentation/ref-manual/classes.rst | 11 +++++++++++
> >   1 file changed, 11 insertions(+)
> > 
> > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> > index 11e0d472e8..5fc30f9233 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -1672,6 +1672,17 @@ one such example. However, being aware of this class can reduce the
> >   proliferation of different versions of similar classes across multiple
> >   layers.
> > +.. _ref-classes-openssl-native:
> > +
> > +``openssl-native.bbclass``
> > +==================
> > +
> > +The ``openssl-native`` class supports using the native version of openssl
> 
> The :ref:`openssl-native <ref-classes-openssl-native>` class supports using
> the native version of ``openssl``

The text and syntax was shamesly copied from the other class descriptions.
Sould those all be updated?

> > +built by the build system rather than support of the version provided
> > +by the build host. It helps setting environment variables for engines,
> > +modules, certificates etc correctly. For full certificate checking
> > +users should also add ``ca-certificates-native`` to :term:`DEPENDS`.
> > +
> 
> I could suggest:
> """
> built by the Yocto Project instead of the one provided by the build host
> distribution.
> """
> 
> I find "rather than support of the version..." confusing.
> 
> I think we could also replace the "It helps" sentence by stating that any
> recipe requiring openssl to be run on the host should inherit this class
> instead of just adding openssl-native to DEPENDS. Maybe that could even be a
> new QA check?
> 
> I would still keep the last sentence though.
> 
> What do you think?

Yes, I can send a new version. I copied the text template form the other
class descriptions so maybe they need to be changed too.

> (Thank you for sending a documentation patch in the same series as the code
> implementation, this is rare enough to be highlighted, much appreciated!)

You're welcome. I RTFM all the time and thus would like to keep the docs
in sync whenever I can.

Cheers,

-Mikko

Re: [docs] [PATCH v2 2/5] classes.rst: document openssl-native.bbclass

[Quentin Schulz]

Hi Mikko,

On 10/5/22 10:43, Mikko Rapeli wrote:
> Hi,
> 
> On Wed, Oct 05, 2022 at 10:31:25AM +0200, Quentin Schulz wrote:
>> Hi Mikko,
>>
>> On 10/4/22 17:27, Mikko Rapeli wrote:
>>> It sets various environment variables correctly for openssl-native.
>>>
>>> Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
>>> ---
>>>    documentation/ref-manual/classes.rst | 11 +++++++++++
>>>    1 file changed, 11 insertions(+)
>>>
>>> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
>>> index 11e0d472e8..5fc30f9233 100644
>>> --- a/documentation/ref-manual/classes.rst
>>> +++ b/documentation/ref-manual/classes.rst
>>> @@ -1672,6 +1672,17 @@ one such example. However, being aware of this class can reduce the
>>>    proliferation of different versions of similar classes across multiple
>>>    layers.
>>> +.. _ref-classes-openssl-native:
>>> +
>>> +``openssl-native.bbclass``
>>> +==================
>>> +
>>> +The ``openssl-native`` class supports using the native version of openssl
>>
>> The :ref:`openssl-native <ref-classes-openssl-native>` class supports using
>> the native version of ``openssl``
> 
> The text and syntax was shamesly copied from the other class descriptions.
> Sould those all be updated?
> 

It's being worked on by Michael AFAIK (he sent a v1 of 30 patches last 
week). In short, we want to have all mentions of classes and terms 
(variables basically) using a link (:ref: for classes, :term: for 
variables), even within the section defining the class or variable itself.

>>> +built by the build system rather than support of the version provided
>>> +by the build host. It helps setting environment variables for engines,
>>> +modules, certificates etc correctly. For full certificate checking
>>> +users should also add ``ca-certificates-native`` to :term:`DEPENDS`.
>>> +
>>
>> I could suggest:
>> """
>> built by the Yocto Project instead of the one provided by the build host
>> distribution.
>> """
>>
>> I find "rather than support of the version..." confusing.
>>
>> I think we could also replace the "It helps" sentence by stating that any
>> recipe requiring openssl to be run on the host should inherit this class
>> instead of just adding openssl-native to DEPENDS. Maybe that could even be a
>> new QA check?
>>
>> I would still keep the last sentence though.
>>
>> What do you think?
> 
> Yes, I can send a new version. I copied the text template form the other
> class descriptions so maybe they need to be changed too.
> 

Mmmm, would you be able to point me to which class descriptions you're 
talking about? Not sure to understand what you're suggesting here :)

Cheers,
Quentin

Re: [docs] [PATCH v2 2/5] classes.rst: document openssl-native.bbclass

[Mikko Rapeli]

Hi, dropping oe-core since this is doc specific

On Wed, Oct 05, 2022 at 10:53:34AM +0200, Quentin Schulz wrote:
> Hi Mikko,
> 
> On 10/5/22 10:43, Mikko Rapeli wrote:
> > Hi,
> > 
> > On Wed, Oct 05, 2022 at 10:31:25AM +0200, Quentin Schulz wrote:
> > > Hi Mikko,
> > > 
> > > On 10/4/22 17:27, Mikko Rapeli wrote:
> > > > It sets various environment variables correctly for openssl-native.
> > > > 
> > > > Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> > > > ---
> > > >    documentation/ref-manual/classes.rst | 11 +++++++++++
> > > >    1 file changed, 11 insertions(+)
> > > > 
> > > > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> > > > index 11e0d472e8..5fc30f9233 100644
> > > > --- a/documentation/ref-manual/classes.rst
> > > > +++ b/documentation/ref-manual/classes.rst
> > > > @@ -1672,6 +1672,17 @@ one such example. However, being aware of this class can reduce the
> > > >    proliferation of different versions of similar classes across multiple
> > > >    layers.
> > > > +.. _ref-classes-openssl-native:
> > > > +
> > > > +``openssl-native.bbclass``
> > > > +==================
> > > > +
> > > > +The ``openssl-native`` class supports using the native version of openssl
> > > 
> > > The :ref:`openssl-native <ref-classes-openssl-native>` class supports using
> > > the native version of ``openssl``
> > 
> > The text and syntax was shamesly copied from the other class descriptions.
> > Sould those all be updated?
> > 
> 
> It's being worked on by Michael AFAIK (he sent a v1 of 30 patches last
> week). In short, we want to have all mentions of classes and terms
> (variables basically) using a link (:ref: for classes, :term: for
> variables), even within the section defining the class or variable itself.

Ok will send the update.

> > > > +built by the build system rather than support of the version provided
> > > > +by the build host. It helps setting environment variables for engines,
> > > > +modules, certificates etc correctly. For full certificate checking
> > > > +users should also add ``ca-certificates-native`` to :term:`DEPENDS`.
> > > > +
> > > 
> > > I could suggest:
> > > """
> > > built by the Yocto Project instead of the one provided by the build host
> > > distribution.
> > > """
> > > 
> > > I find "rather than support of the version..." confusing.
> > > 
> > > I think we could also replace the "It helps" sentence by stating that any
> > > recipe requiring openssl to be run on the host should inherit this class
> > > instead of just adding openssl-native to DEPENDS. Maybe that could even be a
> > > new QA check?
> > > 
> > > I would still keep the last sentence though.
> > > 
> > > What do you think?
> > 
> > Yes, I can send a new version. I copied the text template form the other
> > class descriptions so maybe they need to be changed too.
> > 
> 
> Mmmm, would you be able to point me to which class descriptions you're
> talking about? Not sure to understand what you're suggesting here :)

Yes, python3native:

.. _ref-classes-python3native:

``python3native.bbclass``
=========================

The ``python3native`` class supports using the native version of Python
3 built by the build system rather than support of the version provided
by the build host.

Cheers,

-Mikko