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

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

[Alper Ak]

Fix [YOCTO #15751]

Signed-off-by: Alper Ak <alperyasinak1@gmail.com>
---
 documentation/ref-manual/variables.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index c697bdbbb..2f0925b15 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5202,6 +5202,24 @@ system and gives an overview of their function and contents.
       Specifies additional ``make`` command-line arguments the OpenEmbedded
       build system passes on when compiling the kernel.
 
+   :term:`KERNEL_EXTRA_FEATURES`
+      Specifies optional kernel features to be added on top of the base
+      configuration in kernel recipes that inherit the :ref:`ref-classes-kernel-yocto` class.
+
+      This variable complements :term:`KERNEL_FEATURES` by allowing layers
+      to include or override additional features without requiring Python code or
+      recipe finalize hooks.
+
+      Features are defined in ``.scc`` files, which serve as kernel :term:`Metadata` and usually include patches
+      and configuration fragments to be used during the kernel build process to modify the Linux kernel.
+      For example::
+
+         KERNEL_EXTRA_FEATURES = "features/netfilter/netfilter.scc"
+         KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
+
+      By default, :term:`KERNEL_EXTRA_FEATURES` is empty. But, some distributions
+      such as Poky may set a default value using a soft assignment (``?=``).
+
    :term:`KERNEL_FEATURES`
       Includes additional kernel metadata. In the OpenEmbedded build
       system, the default Board Support Packages (BSPs)
-- 
2.43.0

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

[Quentin Schulz]

Hi Alper,

On 5/31/25 5:49 PM, Alper Ak via lists.yoctoproject.org wrote:
> Fix [YOCTO #15751]
> 
> Signed-off-by: Alper Ak <alperyasinak1@gmail.com>
> ---
>   documentation/ref-manual/variables.rst | 18 ++++++++++++++++++
>   1 file changed, 18 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index c697bdbbb..2f0925b15 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -5202,6 +5202,24 @@ system and gives an overview of their function and contents.
>         Specifies additional ``make`` command-line arguments the OpenEmbedded
>         build system passes on when compiling the kernel.
>   
> +   :term:`KERNEL_EXTRA_FEATURES`
> +      Specifies optional kernel features to be added on top of the base
> +      configuration in kernel recipes that inherit the :ref:`ref-classes-kernel-yocto` class.
> +

I'm not sure that is true?

git grep KERNEL_EXTRA_FEATURES meta/classes-recipe/kernel-yocto.bbclass

returns nothing.

Looking at the layer level, it seems KERNEL_EXTRA_FEATURES is never used 
as is, only as part of KERNEL_FEATURES, and always in final/leaf recipes 
and not .inc files or classes.

> +      This variable complements :term:`KERNEL_FEATURES` by allowing layers

It doesn't as far as I could tell? You need to make 
KERNEL_EXTRA_FEATURES part of the KERNEL_FEATURES variable for that to 
be true?

> +      to include or override additional features without requiring Python code or
> +      recipe finalize hooks.
> +
> +      Features are defined in ``.scc`` files, which serve as kernel :term:`Metadata` and usually include patches
> +      and configuration fragments to be used during the kernel build process to modify the Linux kernel.

Gut feeling is that those two lines are too long but haven't checked 
myself, compare to other long lines in this file to see when we wrap text.

> +      For example::
> +
> +         KERNEL_EXTRA_FEATURES = "features/netfilter/netfilter.scc"
> +         KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
> +
> +      By default, :term:`KERNEL_EXTRA_FEATURES` is empty. But, some distributions

It's not, it simply doesn't exist that is all I believe?

> +      such as Poky may set a default value using a soft assignment (``?=``).

Does it? I don't see it, only an :append is used.

I'll let Antonin decide but I am not entirely sure it makes sense to 
document this variable, which is very recipe specific. A point could be 
made that since poky.conf modifies it, maybe it makes sense to document 
it :)

Cheers,
Quentin

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

[Alper Ak]

Since the KERNEL_FEATURES variable is handled in kernel-yocto.bbclass
and KERNEL_EXTRA_FEATURES is usually appended to it, I wanted to
emphasize that this class should be used.
That's why I made a connection between them and assumed that they were
complementary. Apparently I misinterpreted it.  As you said, it always
in final/leaf recipes and not .inc files or classes.

> > +      such as Poky may set a default value using a soft assignment (``?=``).
> Does it? I don't see it, only an :append is used.

"bitbake-getvar KERNEL_EXTRA_FEATURES" shows that it is
appended(:append) in poky.conf but somehow I missed it and wrote soft
assign... my bad. I should be more careful :)

> I'll let Antonin decide but I am not entirely sure it makes sense to
> document this variable, which is very recipe specific. A point could be
> made that since poky.conf modifies it, maybe it makes sense to document
> it :)

I can prepare a new patch based on your feedback, suggestions.


Quentin Schulz <quentin.schulz@cherry.de>, 2 Haz 2025 Pzt, 14:36
tarihinde şunu yazdı:
>
> Hi Alper,
>
> On 5/31/25 5:49 PM, Alper Ak via lists.yoctoproject.org wrote:
> > Fix [YOCTO #15751]
> >
> > Signed-off-by: Alper Ak <alperyasinak1@gmail.com>
> > ---
> >   documentation/ref-manual/variables.rst | 18 ++++++++++++++++++
> >   1 file changed, 18 insertions(+)
> >
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index c697bdbbb..2f0925b15 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -5202,6 +5202,24 @@ system and gives an overview of their function and contents.
> >         Specifies additional ``make`` command-line arguments the OpenEmbedded
> >         build system passes on when compiling the kernel.
> >
> > +   :term:`KERNEL_EXTRA_FEATURES`
> > +      Specifies optional kernel features to be added on top of the base
> > +      configuration in kernel recipes that inherit the :ref:`ref-classes-kernel-yocto` class.
> > +
>
> I'm not sure that is true?
>
> git grep KERNEL_EXTRA_FEATURES meta/classes-recipe/kernel-yocto.bbclass
>
> returns nothing.
>
> Looking at the layer level, it seems KERNEL_EXTRA_FEATURES is never used
> as is, only as part of KERNEL_FEATURES, and always in final/leaf recipes
> and not .inc files or classes.
>
> > +      This variable complements :term:`KERNEL_FEATURES` by allowing layers
>
> It doesn't as far as I could tell? You need to make
> KERNEL_EXTRA_FEATURES part of the KERNEL_FEATURES variable for that to
> be true?
>
> > +      to include or override additional features without requiring Python code or
> > +      recipe finalize hooks.
> > +
> > +      Features are defined in ``.scc`` files, which serve as kernel :term:`Metadata` and usually include patches
> > +      and configuration fragments to be used during the kernel build process to modify the Linux kernel.
>
> Gut feeling is that those two lines are too long but haven't checked
> myself, compare to other long lines in this file to see when we wrap text.
>
> > +      For example::
> > +
> > +         KERNEL_EXTRA_FEATURES = "features/netfilter/netfilter.scc"
> > +         KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
> > +
> > +      By default, :term:`KERNEL_EXTRA_FEATURES` is empty. But, some distributions
>
> It's not, it simply doesn't exist that is all I believe?
>
> > +      such as Poky may set a default value using a soft assignment (``?=``).
>
> Does it? I don't see it, only an :append is used.
>
> I'll let Antonin decide but I am not entirely sure it makes sense to
> document this variable, which is very recipe specific. A point could be
> made that since poky.conf modifies it, maybe it makes sense to document
> it :)
>
> Cheers,
> Quentin

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

[Antonin Godard]

Hi,

On Mon Jun 2, 2025 at 5:41 PM CEST, Alper Ak via lists.yoctoproject.org wrote:
> Since the KERNEL_FEATURES variable is handled in kernel-yocto.bbclass
> and KERNEL_EXTRA_FEATURES is usually appended to it, I wanted to
> emphasize that this class should be used.
> That's why I made a connection between them and assumed that they were
> complementary. Apparently I misinterpreted it.  As you said, it always
> in final/leaf recipes and not .inc files or classes.
>
>> > +      such as Poky may set a default value using a soft assignment (``?=``).
>> Does it? I don't see it, only an :append is used.
>
> "bitbake-getvar KERNEL_EXTRA_FEATURES" shows that it is
> appended(:append) in poky.conf but somehow I missed it and wrote soft

I don't think we should document variable default values based on poky.conf, as
Poky is only a reference distro after all.

What bothers me is that KERNEL_EXTRA_FEATURES does not have any default value in
the kernel-yocto class. And I don't see the added value compared to
KERNEL_FEATURES, since what happens in the end is always:

  KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"

Meaning users are fine modifying the KERNEL_FEATURES variable directly, I
believe. What do you think?

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Alper Ak]

Looks like KERNEL_EXTRA_FEATURES only exists to add to KERNEL_FEATURES
from poky.

To be honest, after wrote the documentation I felt that this variable
was unnecessary. Of course it's necessary for poky but you know what I
mean.

Antonin Godard <antonin.godard@bootlin.com>, 4 Haz 2025 Çar, 10:47
tarihinde şunu yazdı:
>
> Hi,
>
> On Mon Jun 2, 2025 at 5:41 PM CEST, Alper Ak via lists.yoctoproject.org wrote:
> > Since the KERNEL_FEATURES variable is handled in kernel-yocto.bbclass
> > and KERNEL_EXTRA_FEATURES is usually appended to it, I wanted to
> > emphasize that this class should be used.
> > That's why I made a connection between them and assumed that they were
> > complementary. Apparently I misinterpreted it.  As you said, it always
> > in final/leaf recipes and not .inc files or classes.
> >
> >> > +      such as Poky may set a default value using a soft assignment (``?=``).
> >> Does it? I don't see it, only an :append is used.
> >
> > "bitbake-getvar KERNEL_EXTRA_FEATURES" shows that it is
> > appended(:append) in poky.conf but somehow I missed it and wrote soft
>
> I don't think we should document variable default values based on poky.conf, as
> Poky is only a reference distro after all.
>
> What bothers me is that KERNEL_EXTRA_FEATURES does not have any default value in
> the kernel-yocto class. And I don't see the added value compared to
> KERNEL_FEATURES, since what happens in the end is always:
>
>   KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
>
> Meaning users are fine modifying the KERNEL_FEATURES variable directly, I
> believe. What do you think?
>
> Antonin
>
> --
> Antonin Godard, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
>

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

[Antonin Godard]

On Wed Jun 4, 2025 at 11:52 AM CEST, Alper Ak wrote:
> Looks like KERNEL_EXTRA_FEATURES only exists to add to KERNEL_FEATURES
> from poky.
>
> To be honest, after wrote the documentation I felt that this variable
> was unnecessary. Of course it's necessary for poky but you know what I
> mean.

No problem, I will comment the bug on bugzilla and close it.

Otherwise, thanks for taking to contribute these patches, they are really
helping!

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com