[PATCH] variables.rst: document uki.bbclass variables

[PATCH] variables.rst: document uki.bbclass variables

[Mikko Rapeli]

Documentation for the new class.

[YOCTO #15650]
https://bugzilla.yoctoproject.org/show_bug.cgi?id=15650

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

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index ec4d7ab73f..9dac0b2d25 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -9846,6 +9846,38 @@ system and gives an overview of their function and contents.
       passes and uses "all" for the target during the U-Boot building
       process.
 
+   :term:`UKIFY_CMD`
+      When inheriting the :ref:`ref-classes-uki` class,
+      `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build
+      `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+      Defaults to ``ukify build``.
+
+   :term:`UKI_CONFIG_FILE`
+      When inheriting the :ref:`ref-classes-uki` class,
+      an optional config file for `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command.
+
+   :term:`UKI_FILENAME`
+      When inheriting the :ref:`ref-classes-uki` class,
+      the output file name for generated `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+      Defaults to ``uki.efi``.
+
+   :term:`UKI_KERNEL_FILENAME`
+      When inheriting the :ref:`ref-classes-uki` class,
+      the kernel image file name to use as input. Defaults to :term:`KERNEL_IMAGETYPE`.
+
+   :term:`UKI_CMDLINE`
+      When inheriting the :ref:`ref-classes-uki` class,
+      the kernel command line to use when booting the `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+      Defaults to ``rootwait root=LABEL=root console=${KERNEL_CONSOLE}``.
+
+   :term:`UKI_SB_KEY`
+      When inheriting the :ref:`ref-classes-uki` class,
+      optional UEFI secureboot private key to sign `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+
+   :term:`UKI_SB_CERT`
+      When inheriting the :ref:`ref-classes-uki` class,
+      optional UEFI secureboot certificate mathing the private key in :term:`UKI_SB_KEY`.
+
    :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`
       Specifies a list of options that, if reported by the configure script
       as being invalid, should not generate a warning during the
-- 
2.43.0

Re: [docs] [PATCH] variables.rst: document uki.bbclass variables

[Quentin Schulz]

Hi Mikko,

On 11/26/24 9:29 AM, Mikko Rapeli via lists.yoctoproject.org wrote:
> Documentation for the new class.
> 
> [YOCTO #15650]
> https://bugzilla.yoctoproject.org/show_bug.cgi?id=15650
> 
> Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> ---
>   documentation/ref-manual/variables.rst | 32 ++++++++++++++++++++++++++
>   1 file changed, 32 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index ec4d7ab73f..9dac0b2d25 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9846,6 +9846,38 @@ system and gives an overview of their function and contents.
>         passes and uses "all" for the target during the U-Boot building
>         process.
>   
> +   :term:`UKIFY_CMD`
> +      When inheriting the :ref:`ref-classes-uki` class,

I don't see this reference defined anywhere, which we should have in 
documentation/ref-manual/classes.rst so that needs to be added as well.

EDIT: this is contributed in another patch, 
https://lore.kernel.org/yocto-docs/20241125153415.282847-1-mikko.rapeli@linaro.org/T/#u

Having both in the same patch series would have been appreciated, or at 
least mention in this patch that it depends on another patch so we don't 
forget in which order to merge them.

> +      `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build
> +      `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> +      Defaults to ``ukify build``.
> +
> +   :term:`UKI_CONFIG_FILE`
> +      When inheriting the :ref:`ref-classes-uki` class,
> +      an optional config file for `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command.
> +
> +   :term:`UKI_FILENAME`
> +      When inheriting the :ref:`ref-classes-uki` class,
> +      the output file name for generated `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> +      Defaults to ``uki.efi``.
> +
> +   :term:`UKI_KERNEL_FILENAME`
> +      When inheriting the :ref:`ref-classes-uki` class,
> +      the kernel image file name to use as input. Defaults to :term:`KERNEL_IMAGETYPE`.
> +
> +   :term:`UKI_CMDLINE`
> +      When inheriting the :ref:`ref-classes-uki` class,
> +      the kernel command line to use when booting the `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> +      Defaults to ``rootwait root=LABEL=root console=${KERNEL_CONSOLE}``.
> +

Can we have this term ordered alphabetically too (just below UKIFY_CMD)?

> +   :term:`UKI_SB_KEY`
> +      When inheriting the :ref:`ref-classes-uki` class,
> +      optional UEFI secureboot private key to sign `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> +

Same here, please move this one below UKI_SB_CERT.

> +   :term:`UKI_SB_CERT`
> +      When inheriting the :ref:`ref-classes-uki` class,
> +      optional UEFI secureboot certificate mathing the private key in :term:`UKI_SB_KEY`.

s/mathing/matching/

Cheers,
Quentin

Re: [docs] [PATCH] variables.rst: document uki.bbclass variables

[Mikko Rapeli]

Hi,

On Tue, Nov 26, 2024 at 11:01:17AM +0100, Quentin Schulz wrote:
> Hi Mikko,
> 
> On 11/26/24 9:29 AM, Mikko Rapeli via lists.yoctoproject.org wrote:
> > Documentation for the new class.
> > 
> > [YOCTO #15650]
> > https://bugzilla.yoctoproject.org/show_bug.cgi?id=15650
> > 
> > Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> > ---
> >   documentation/ref-manual/variables.rst | 32 ++++++++++++++++++++++++++
> >   1 file changed, 32 insertions(+)
> > 
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index ec4d7ab73f..9dac0b2d25 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -9846,6 +9846,38 @@ system and gives an overview of their function and contents.
> >         passes and uses "all" for the target during the U-Boot building
> >         process.
> > +   :term:`UKIFY_CMD`
> > +      When inheriting the :ref:`ref-classes-uki` class,
> 
> I don't see this reference defined anywhere, which we should have in
> documentation/ref-manual/classes.rst so that needs to be added as well.
> 
> EDIT: this is contributed in another patch, https://lore.kernel.org/yocto-docs/20241125153415.282847-1-mikko.rapeli@linaro.org/T/#u
> 
> Having both in the same patch series would have been appreciated, or at
> least mention in this patch that it depends on another patch so we don't
> forget in which order to merge them.

Sorry, done in v2.
 
> > +      `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build
> > +      `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> > +      Defaults to ``ukify build``.
> > +
> > +   :term:`UKI_CONFIG_FILE`
> > +      When inheriting the :ref:`ref-classes-uki` class,
> > +      an optional config file for `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command.
> > +
> > +   :term:`UKI_FILENAME`
> > +      When inheriting the :ref:`ref-classes-uki` class,
> > +      the output file name for generated `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> > +      Defaults to ``uki.efi``.
> > +
> > +   :term:`UKI_KERNEL_FILENAME`
> > +      When inheriting the :ref:`ref-classes-uki` class,
> > +      the kernel image file name to use as input. Defaults to :term:`KERNEL_IMAGETYPE`.
> > +
> > +   :term:`UKI_CMDLINE`
> > +      When inheriting the :ref:`ref-classes-uki` class,
> > +      the kernel command line to use when booting the `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> > +      Defaults to ``rootwait root=LABEL=root console=${KERNEL_CONSOLE}``.
> > +
> 
> Can we have this term ordered alphabetically too (just below UKIFY_CMD)?

Done in v2.
 
> > +   :term:`UKI_SB_KEY`
> > +      When inheriting the :ref:`ref-classes-uki` class,
> > +      optional UEFI secureboot private key to sign `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
> > +
> 
> Same here, please move this one below UKI_SB_CERT.

Done in v2.

> > +   :term:`UKI_SB_CERT`
> > +      When inheriting the :ref:`ref-classes-uki` class,
> > +      optional UEFI secureboot certificate mathing the private key in :term:`UKI_SB_KEY`.
> 
> s/mathing/matching/

Thanks, done in v2.

Cheers,

-Mikko