Skip to contentSkip to conversation

ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

PATCH Superseded Simon A. Eugster 2 participants 4 messages Jan 28, 2025

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 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.

---
 documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
 documentation/ref-manual/variables.rst |  5 +++++
 2 files changed, 21 insertions(+)
documentation/ref-manual/classes.rst +16 -0
index 761be7b545..1de362e864 100644
@@ -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 ``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"
+
 .. _ref-classes-gsettings:
 
 ``gsettings``
documentation/ref-manual/variables.rst +5 -0
index 0c5c7aab97..16ffbf0e85 100644
@@ -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  :ref:`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
Signature · 1 line
2.43.0
#1 lore raw

Hi Simon,

Quoted 56 lines · Simon A. Eugster

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.

---
 documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
 documentation/ref-manual/variables.rst |  5 +++++
 2 files changed, 21 insertions(+)
documentation/ref-manual/classes.rst +16 -0
index 761be7b545..1de362e864 100644
@@ -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 ``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"
+
 .. _ref-classes-gsettings:
 
 ``gsettings``
documentation/ref-manual/variables.rst +0 -0
index 0c5c7aab97..16ffbf0e85 100644

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 3324

Quoted 5 lines
documentation/ref-manual/variables.rst +2 -0
@@ -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  :ref:`LABELS`. See

Here you make a :ref: to LABELS, but like GRUB_TITLE, it needs to be added to variables.rst, otherwise it produces a compile error. You would also use :term:, not :ref:.

Can you add documentation for it?

Since "LABELS" by its own does not refer to Grub, just make sure to start the description with:

"""
When inheriting the :ref:ref-classes-grub-efi class, ... """

So someone reading the description knows in which context it's used.

If you do, please also use :term: in the class description above.

Thanks for the separate mail/Signed-off-by!

Antonin

Signature · 3 lines
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
#2 lore raw

Hi Antonin,

thanks again for your comments.

Quoted 72 lines · Antonin Godard

Hi Simon,

Review

Quoted 11 lines · Simon A. Eugster

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.

---
 documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
 documentation/ref-manual/variables.rst |  5 +++++
 2 files changed, 21 insertions(+)
(quoted diff) +0 -0

b/documentation/ref-manual/classes.rst

Quoted 22 lines

index 761be7b545..1de362e864 100644

documentation/ref-manual/classes.rst +4 -0
@@ -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 (``;``).

documentation/ref-manual/classes.rst This class supports several variables: · line 1018

Quoted 4 lines
documentation/ref-manual/classes.rst +1 -0
@@ -1011,6 +1015,18 @@ This class supports several variables:
 -  :term:`GRUB_TIMEOUT`: Timeout before executing
    the default ``LABEL`` (optional).
 
+Each ``LABEL`` defined in the ``LABELS`` variable creates a GRUB boot

entry,

documentation/ref-manual/classes.rst This class supports several variables: · line 1020

Quoted 2 lines
documentation/ref-manual/classes.rst +2 -0
+and some variables can be defined individually per ``LABEL``. The label
+specific override names are defined as ``grub_LABEL``.

+

documentation/ref-manual/classes.rst This class supports several variables: · line 1022

Quoted 2 lines
documentation/ref-manual/classes.rst +2 -0
+For example, for a label ``factory``, the override name would be
+``grub_factory``. A custom GRUB menu entry titled "Factory Install"

with the

Review

Quoted 10 lines
documentation/ref-manual/classes.rst +6 -0
+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``
(quoted diff) +0 -0

b/documentation/ref-manual/variables.rst

documentation/ref-manual/variables.rst system and gives an overview of their function

Quoted 4 lines

index 0c5c7aab97..16ffbf0e85 100644

documentation/ref-manual/variables.rst +0 -0
@@ -3320,6 +3320,11 @@ system and gives an overview of their function

and contents.

documentation/ref-manual/variables.rst system and gives an overview of their function and contents.

Quoted 5 lines
documentation/ref-manual/variables.rst +2 -0
       :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

:ref:LABELS. See

Quoted 8 lines

Here you make a :ref: to LABELS, but like GRUB_TITLE, it needs to be added to
variables.rst, otherwise it produces a compile error. You would also use :term:,
not :ref:.

Can you add documentation for it?

I will change it to :term:. The LABELS term already exists, right?

Also, is it okay if I fix a typo in standards.md in this same MR, or do you need a separate patch for that?

Since "LABELS" by its own does not refer to Grub, just make sure to start

Quoted 11 lines

the
description with:

"""
When inheriting the :ref:ref-classes-grub-efi class, ... """

So someone reading the description knows in which context it's used.

If you do, please also use :term: in the class description above.

Will do.

Quoted 2 lines

Thanks for the separate mail/Signed-off-by!

Thanks for the reminder, I hardly have to sign off commits :)

Simon

#3 lore raw

Hi Simon,

Quoted 85 lines · Simon Eugster

Hi Antonin,

thanks again for your comments.

Quoted 78 lines · Antonin Godard

Hi Simon,

Review

Quoted 11 lines · Simon A. Eugster

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.

---
 documentation/ref-manual/classes.rst   | 16 ++++++++++++++++
 documentation/ref-manual/variables.rst |  5 +++++
 2 files changed, 21 insertions(+)
(quoted diff) +0 -0

b/documentation/ref-manual/classes.rst

Quoted 22 lines

index 761be7b545..1de362e864 100644

documentation/ref-manual/classes.rst +4 -0
@@ -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 (``;``).

documentation/ref-manual/classes.rst This class supports several variables: · line 1018

Quoted 4 lines
documentation/ref-manual/classes.rst +1 -0
@@ -1011,6 +1015,18 @@ This class supports several variables:
 -  :term:`GRUB_TIMEOUT`: Timeout before executing
    the default ``LABEL`` (optional).
 
+Each ``LABEL`` defined in the ``LABELS`` variable creates a GRUB boot

entry,

documentation/ref-manual/classes.rst This class supports several variables: · line 1020

Quoted 2 lines
documentation/ref-manual/classes.rst +2 -0
+and some variables can be defined individually per ``LABEL``. The label
+specific override names are defined as ``grub_LABEL``.

+

documentation/ref-manual/classes.rst This class supports several variables: · line 1022

Quoted 2 lines
documentation/ref-manual/classes.rst +2 -0
+For example, for a label ``factory``, the override name would be
+``grub_factory``. A custom GRUB menu entry titled "Factory Install"

with the

Review

Quoted 10 lines
documentation/ref-manual/classes.rst +6 -0
+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``
(quoted diff) +0 -0

b/documentation/ref-manual/variables.rst

documentation/ref-manual/variables.rst system and gives an overview of their function

Quoted 4 lines

index 0c5c7aab97..16ffbf0e85 100644

documentation/ref-manual/variables.rst +0 -0
@@ -3320,6 +3320,11 @@ system and gives an overview of their function

and contents.

documentation/ref-manual/variables.rst system and gives an overview of their function and contents.

Quoted 5 lines
documentation/ref-manual/variables.rst +2 -0
       :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

:ref:LABELS. See

Here you make a :ref: to LABELS, but like GRUB_TITLE, it needs to be added to
variables.rst, otherwise it produces a compile error. You would also use :term:,
not :ref:.

Quoted 4 lines
Quoted 2 lines

Can you add documentation for it?

I will change it to :term:. The LABELS term already exists, right?

You're right, I should have double checked. Only change it to :term: then, thanks!

Quoted 2 lines

Also, is it okay if I fix a typo in standards.md in this same MR, or do you need a separate patch for that?

Please send a separated patch

Thanks,
Antonin

Signature · 3 lines
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com