[v3] ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

This patch describes how to use overrides for grub-efi-cfg because that
is otherwise only clear after reading the .bbclass file. It also adds
a description for GRUB_TITLE.

Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
---
 documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
 documentation/ref-manual/variables.rst |  5 +++++
 2 files changed, 21 insertions(+)

Hi Simon,

On Tue Jan 28, 2025 at 11:23 AM CET, Simon A. Eugster wrote:
> This patch describes how to use overrides for grub-efi-cfg because that
> is otherwise only clear after reading the .bbclass file. It also adds
> a description for GRUB_TITLE.
>
> Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> ---
>  documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
>  documentation/ref-manual/variables.rst |  5 +++++
>  2 files changed, 21 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 761be7b545..1d64ac2f28 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -991,6 +991,7 @@ This class supports several variables:
>  
>  -  :term:`INITRD`: Indicates list of filesystem images to
>     concatenate and use as an initial RAM disk (initrd) (optional).
> +   Can be specified for each ``LABEL``.
>  
>  -  :term:`ROOTFS`: Indicates a filesystem image to include
>     as the root filesystem (optional).
> @@ -1004,6 +1005,9 @@ This class supports several variables:
>  -  :term:`APPEND`: An override list of append strings for
>     each ``LABEL``.
>  
> +-  :term:`GRUB_TITLE`: A custom title for each ```LABEL``.
> +   Defaults to ``LABEL`` if it is not defined.
> +
>  -  :term:`GRUB_OPTS`: Additional options to add to the
>     configuration (optional). Options are delimited using semi-colon
>     characters (``;``).
> @@ -1011,6 +1015,18 @@ This class supports several variables:
>  -  :term:`GRUB_TIMEOUT`: Timeout before executing
>     the default ``LABEL`` (optional).
>  
> +Each ``LABEL`` defined in the :term:``LABELS`` variable creates a GRUB boot

:term:``LABELS`` is incorrect, it should be enclosed with single backticks only.

Regards,
Antonin

> +entry, and some variables can be defined individually per ``LABEL``. The label
> +specific override names are defined as ``grub_LABEL``.
> +
> +For example, for a label ``factory``, the override name would be
> +``grub_factory``. A custom GRUB menu entry titled "Factory Install" with the
> +additional parameter ``factory=yes`` can be achieved as follows::
> +
> +   LABELS:append = " factory"
> +   APPEND:grub_factory = "factory=yes"
> +   GRUB_TITLE:grub_factory = "Factory Install"
> +
>  .. _ref-classes-gsettings:
>  
>  ``gsettings``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 0c5c7aab97..4eb11abede 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3320,6 +3320,11 @@ system and gives an overview of their function and contents.
>        :ref:`ref-classes-grub-efi` class for more information
>        on how this variable is used.
>  
> +   :term:`GRUB_TITLE`
> +      Specifies custom titles for GRUB labels defined in  :term:`LABELS`. See
> +      the :ref:`ref-classes-grub-efi` class for more information on how this
> +      variable is used.
> +
>     :term:`GTKIMMODULES_PACKAGES`
>        When inheriting the :ref:`ref-classes-gtk-immodules-cache` class,
>        this variable specifies the packages that contain the GTK+ input


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

Hi Simon,

On 1/28/25 11:23 AM, Simon A. Eugster via lists.yoctoproject.org wrote:
> This patch describes how to use overrides for grub-efi-cfg because that
> is otherwise only clear after reading the .bbclass file. It also adds
> a description for GRUB_TITLE.
> 
> Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> ---
>   documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
>   documentation/ref-manual/variables.rst |  5 +++++
>   2 files changed, 21 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 761be7b545..1d64ac2f28 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -991,6 +991,7 @@ This class supports several variables:
>   
>   -  :term:`INITRD`: Indicates list of filesystem images to
>      concatenate and use as an initial RAM disk (initrd) (optional).
> +   Can be specified for each ``LABEL``.
>   
>   -  :term:`ROOTFS`: Indicates a filesystem image to include
>      as the root filesystem (optional).
> @@ -1004,6 +1005,9 @@ This class supports several variables:
>   -  :term:`APPEND`: An override list of append strings for
>      each ``LABEL``.
>   
> +-  :term:`GRUB_TITLE`: A custom title for each ```LABEL``.
> +   Defaults to ``LABEL`` if it is not defined.
> +

I would rather say that it defaults to label's name (``LABEL``) or 
something like this. GRUB_TITLE does not defaults to LABEL, which is 
what this may imply.

>   -  :term:`GRUB_OPTS`: Additional options to add to the
>      configuration (optional). Options are delimited using semi-colon
>      characters (``;``).
> @@ -1011,6 +1015,18 @@ This class supports several variables:
>   -  :term:`GRUB_TIMEOUT`: Timeout before executing
>      the default ``LABEL`` (optional).
>   
> +Each ``LABEL`` defined in the :term:``LABELS`` variable creates a GRUB boot
> +entry, and some variables can be defined individually per ``LABEL``. The label
> +specific override names are defined as ``grub_LABEL``.
> +
> +For example, for a label ``factory``, the override name would be
> +``grub_factory``. A custom GRUB menu entry titled "Factory Install" with the
> +additional parameter ``factory=yes`` can be achieved as follows::
> +
> +   LABELS:append = " factory"
> +   APPEND:grub_factory = "factory=yes"
> +   GRUB_TITLE:grub_factory = "Factory Install"
> +

FYI, I believe this is currently not properly handled by sstate-cache. 
We use the same OVERRIDES trick on extlinux.conf generation for U-Boot 
and we needed (it seems like, wasn't there when it was implemented) 
explicitly list all variables with their OVERRIDES.

c.f. do_create_extlinux_config[vardeps] in 
meta/classes-recipe/uboot-extlinux-config.bbclass.

An easy way to check that would be to only modify APPEND:grub_factory 
and see if it regenerates the grub config file appropriately.

Cheers,
Quentin