Skip to contentSkip to conversation

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

PATCH In review Simon A. Eugster 2 participants 5 messages Jan 15, 2025 – Jan 23, 2025

lore
Share & tools
lore
#0 lore raw

PATCH 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 | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)
documentation/ref-manual/classes.rst +16 -1
index 761be7b545..460f94b232 100644
@@ -987,10 +987,14 @@ introspection. This functionality is only enabled if the
 The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for
 building bootable images.
 
-This class supports several variables:
+This class supports several variables.
+The label specific override names are ``grub_LABEL``.
+To specificy an override for the label ``mylabel``, the override name is ``grub_mylabel``,
+for example ``APPEND:grub_mylabel = my-appends``.
 
 -  :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 +1008,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 +1018,14 @@ This class supports several variables:
 -  :term:`GRUB_TIMEOUT`: Timeout before executing
    the default ``LABEL`` (optional).
 
+For the label ``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``
Signature · 1 line
2.43.0
#1 lore raw

Hi Simon,

Quoted 12 lines · Simon A. Eugster via lists.yoctoproject.org

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 | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)
documentation/ref-manual/classes.rst +0 -0
index 761be7b545..460f94b232 100644

documentation/ref-manual/classes.rst introspection. This functionality is only enabled if the · line 991

Quoted 6 lines
documentation/ref-manual/classes.rst +2 -1
@@ -987,10 +987,14 @@ introspection. This functionality is only enabled if the
 The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for
 building bootable images.
 
-This class supports several variables:
+This class supports several variables.
+The label specific override names are ``grub_LABEL``.

"...are defined as ``grub_LABEL``"?

documentation/ref-manual/classes.rst introspection. This functionality is only enabled if the · line 992

Quoted 1 line
documentation/ref-manual/classes.rst +1 -0
+To specificy an override for the label ``mylabel``, the override name is ``grub_mylabel``,

s/specificy/specify/

Also please wrap the lines to 80 chars, as recommended by our standards.md file.

documentation/ref-manual/classes.rst introspection. This functionality is only enabled if the · line 993

Quoted 1 line
documentation/ref-manual/classes.rst +1 -0
+for example ``APPEND:grub_mylabel = my-appends``.

You are missing quotes in this example, it should be ``APPEND:grub_mylabel = "my-appends"``.

I think it would also make sense to give this example after the bullet list. I would move the text starting from "The label specific override names..." to the APPEND example, after the bullet list. And you keep your real life example with the factory.

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

Quoted 12 lines
documentation/ref-manual/classes.rst +2 -0
 -  :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 +1008,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``.

In addition to adding the variable here, you also need to add its definition to documentation/ref-manual/variables.rst, otherwise you cannot make a cross-reference to it here. Mind that the variables.rst file had the variables alphabetically ordered.

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

Quoted 13 lines
documentation/ref-manual/classes.rst +6 -0
+   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 +1018,14 @@ This class supports several variables:
 -  :term:`GRUB_TIMEOUT`: Timeout before executing
    the default ``LABEL`` (optional).
 
+For the label ``factory``, a custom GRUB menu entry titled "Factory Install" with the additional parameter ``factory=yes``
+can be achieved as follows::
+
+  LABELS:append = "factory"

I think you need a space after the quote here:

LABELS:append = " factory"

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

Quoted 4 lines
documentation/ref-manual/classes.rst +4 -0
+  APPEND:grub_factory = "factory=yes"
+  GRUB_TITLE:grub_factory = "Factory Install"
+
+

Unneeded extra newline here

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

Quoted 3 lines
documentation/ref-manual/classes.rst +0 -0
 .. _ref-classes-gsettings:
 
 ``gsettings``

Thank you,
Antonin

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

PATCH 1/1 ref-manual: Describe grub-efi-cfg overrides and GRUB_TITLE

In reply to 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   | 18 +++++++++++++++++-
 documentation/ref-manual/variables.rst |  6 ++++++
 2 files changed, 23 insertions(+), 1 deletion(-)
documentation/ref-manual/classes.rst +17 -1
index 761be7b545..df6092f082 100644
@@ -987,10 +987,11 @@ introspection. This functionality is only enabled if the
 The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for
 building bootable images.
 
-This class supports several variables:
+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 +6 -0
index 0c5c7aab97..9061c206a7 100644
@@ -3320,6 +3320,12 @@ 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
#2 lore raw
In reply to Antonin Godard

Hi Antonin,

Thanks a lot for your suggestions! I have updated the patch according to them.

Simon

Quoted 107 lines · Antonin Godard

Hi Simon,

Review

Quoted 8 lines · Simon A. Eugster via lists.yoctoproject.org

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 | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)
(quoted diff) +0 -0

b/documentation/ref-manual/classes.rst

documentation/ref-manual/classes.rst introspection. This functionality is only enabled

Quoted 4 lines

index 761be7b545..460f94b232 100644

documentation/ref-manual/classes.rst +0 -0
@@ -987,10 +987,14 @@ introspection. This functionality is only enabled

if the

documentation/ref-manual/classes.rst introspection. This functionality is only enabled · line 987

Quoted 1 line
documentation/ref-manual/classes.rst +0 -0
 The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific

functions for

documentation/ref-manual/classes.rst introspection. This functionality is only enabled if the · line 991

Quoted 5 lines
documentation/ref-manual/classes.rst +2 -1
 building bootable images.
 
-This class supports several variables:
+This class supports several variables.
+The label specific override names are ``grub_LABEL``.

"...are defined as ``grub_LABEL``"?

documentation/ref-manual/classes.rst introspection. This functionality is only enabled · line 992

Quoted 1 line
documentation/ref-manual/classes.rst +1 -0
+To specificy an override for the label ``mylabel``, the override name

is ``grub_mylabel``,

s/specificy/specify/

Also please wrap the lines to 80 chars, as recommended by our standards.md file.

documentation/ref-manual/classes.rst introspection. This functionality is only enabled if the · line 993

Quoted 1 line
documentation/ref-manual/classes.rst +1 -0
+for example ``APPEND:grub_mylabel = my-appends``.

You are missing quotes in this example, it should be ``APPEND:grub_mylabel = "my-appends"``.

I think it would also make sense to give this example after the bullet list. I
would move the text starting from "The label specific override names..." to the
APPEND example, after the bullet list. And you keep your real life example with
the factory.

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

Quoted 12 lines
documentation/ref-manual/classes.rst +2 -0
 -  :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 +1008,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``.

In addition to adding the variable here, you also need to add its definition to
documentation/ref-manual/variables.rst, otherwise you cannot make a cross-reference to it here. Mind that the variables.rst file had the variables
alphabetically ordered.

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

Quoted 10 lines
documentation/ref-manual/classes.rst +3 -0
+   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 +1018,14 @@ This class supports several variables:
 -  :term:`GRUB_TIMEOUT`: Timeout before executing
    the default ``LABEL`` (optional).
 
+For the label ``factory``, a custom GRUB menu entry titled "Factory

Install" with the additional parameter ``factory=yes``

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

Quoted 3 lines
documentation/ref-manual/classes.rst +3 -0
+can be achieved as follows::
+
+  LABELS:append = "factory"

I think you need a space after the quote here:

LABELS:append = " factory"

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

Quoted 4 lines
documentation/ref-manual/classes.rst +4 -0
+  APPEND:grub_factory = "factory=yes"
+  GRUB_TITLE:grub_factory = "Factory Install"
+
+

Unneeded extra newline here

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

Quoted 3 lines
documentation/ref-manual/classes.rst +0 -0
 .. _ref-classes-gsettings:
 
 ``gsettings``

Thank you,
Antonin

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

#4 lore raw
In reply to Simon A. Eugster

Hi Simon,

Please send new versions of the patch in a separate email thread, and include the version in the Subject. See the contributor guide for more details on how to do that:
https://docs.yoctoproject.org/contributor-guide/submit-changes.html#taking-patch-review-into-account

Please, also make sure to include your Signed-off-by in your patches. The contributor guide goes over that too.

Quoted 13 lines · Simon A. Eugster via lists.yoctoproject.org

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   | 18 +++++++++++++++++-
 documentation/ref-manual/variables.rst |  6 ++++++
 2 files changed, 23 insertions(+), 1 deletion(-)
documentation/ref-manual/classes.rst +0 -0
index 761be7b545..df6092f082 100644

documentation/ref-manual/classes.rst introspection. This functionality is only enabled if the · line 990

Quoted 5 lines
documentation/ref-manual/classes.rst +1 -1
@@ -987,10 +987,11 @@ introspection. This functionality is only enabled if the
 The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for
 building bootable images.
 
-This class supports several variables:
+This class supports several variables.

You can leave the colon here.

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

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

Quoted 10 lines
documentation/ref-manual/classes.rst +10 -0
+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"

Our standards.md file recommends three spaces for code block indentation, can you fix this?

Quoted 9 lines
documentation/ref-manual/classes.rst +1 -0
+
 .. _ref-classes-gsettings:
 
 ``gsettings``
documentation/ref-manual/variables.rst +0 -0
index 0c5c7aab97..9061c206a7 100644

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

Quoted 9 lines
documentation/ref-manual/variables.rst +6 -0
@@ -3320,6 +3320,12 @@ 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.
+
+

Extra newline, can you remove it?

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

Quoted 3 lines
documentation/ref-manual/variables.rst +0 -0
    :term:`GTKIMMODULES_PACKAGES`
       When inheriting the :ref:`ref-classes-gtk-immodules-cache` class,
       this variable specifies the packages that contain the GTK+ input

Antonin

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