[PATCH 0/3] bitbake-setup updates

[PATCH 0/3] bitbake-setup updates

[Antonin Godard]

Add a commit to be able to use the release series in a numerical format,
and use that number in what's shown in the output of bitbake-setup init.

Switch the shell code-blocks to console code-blocks.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (3):
      poky.yaml.in: add DISTRO_RELEASE_SERIES
      brief-yoctoprojectqs/index.rst: update available bitbake-setup configurations
      brief-yoctoprojectqs/index.rst: switch shell block to to console lexer

 documentation/brief-yoctoprojectqs/index.rst | 41 +++++++++++++++-------------
 documentation/poky.yaml.in                   |  2 ++
 documentation/set_versions.py                |  1 +
 3 files changed, 25 insertions(+), 19 deletions(-)
---
base-commit: 79cd33b06e87c04e4f873a5afd9d53714bc5047f
change-id: 20251127-bitbake-setup-updates-b00664d244c4

[PATCH 1/3] poky.yaml.in: add DISTRO_RELEASE_SERIES

[Antonin Godard]

The DISTRO_RELEASE_SERIES represents the release series in numerical
format. So for whinlatter, it will always equal "5.3", no matter what
the latest tag or patch version is.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/poky.yaml.in    | 2 ++
 documentation/set_versions.py | 1 +
 2 files changed, 3 insertions(+)

diff --git a/documentation/poky.yaml.in b/documentation/poky.yaml.in
index 7a19545d1..810efd4d5 100644
--- a/documentation/poky.yaml.in
+++ b/documentation/poky.yaml.in
@@ -11,6 +11,8 @@ DISTRO : "5.2"
 # represent the latest HEAD revision on the branch). DISTRO_LATEST_TAG should
 # always point to an existing tag.
 DISTRO_LATEST_TAG : "5.2"
+# The DISTRO_RELEASE_SERIES omits the patch version (so always X.Y).
+DISTRO_RELEASE_SERIES : "5.2"
 DISTRO_NAME_NO_CAP : "walnascar"
 DISTRO_NAME : "Walnascar"
 DISTRO_NAME_NO_CAP_MINUS_ONE : "styhead"
diff --git a/documentation/set_versions.py b/documentation/set_versions.py
index be05ef323..d146f93bb 100755
--- a/documentation/set_versions.py
+++ b/documentation/set_versions.py
@@ -190,6 +190,7 @@ print("Release series calculated to be %s" % ourseries)
 replacements = {
     "DISTRO" : ourversion,
     "DISTRO_LATEST_TAG": latesttag,
+    "DISTRO_RELEASE_SERIES": release_series[ourseries],
     "DISTRO_NAME_NO_CAP" : ourseries,
     "DISTRO_NAME" : ourseries.capitalize(),
     "DISTRO_NAME_NO_CAP_MINUS_ONE" : previousseries[0],

-- 
2.51.0

[PATCH 2/3] brief-yoctoprojectqs/index.rst: update available bitbake-setup configurations

[Antonin Godard]

Configurations were updated with commit 720df1a53452 ("bitbake-setup:
add whinlatter configs for poky and oe-nodistro") in BitBake. To more
accurately represent what the output will be in the real world, add them
here by using the DISTRO_NAME_NO_CAP and DISTRO_RELEASE_SERIES meta
variable that are translated to "whinlatter" and "5.3" respectively.

Note that the real output mentions "(supported until 2026-05-31)" but we
don't want to maintain that value over time, so just omit it.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/brief-yoctoprojectqs/index.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 07bb4e1ca..1e0d867d6 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -129,7 +129,10 @@ differ from the examples below.
 
       Available configurations:
       1. poky-master  Poky - The Yocto Project testing distribution configurations and hardware test platforms
-      2. oe-nodistro  OpenEmbedded - 'nodistro' basic configuration
+      2. oe-nodistro-&DISTRO_NAME_NO_CAP;       OpenEmbedded - 'nodistro' basic configuration, release &DISTRO_RELEASE_SERIES; '&DISTRO_NAME_NO_CAP;'
+      3. poky-&DISTRO_NAME_NO_CAP;      Poky - The Yocto Project testing distribution configurations and hardware test platforms, release &DISTRO_RELEASE_SERIES; '&DISTRO_NAME_NO_CAP;'
+      4. oe-nodistro-master   OpenEmbedded - 'nodistro' basic configuration
+      ...
 
       Please select one of the above configurations by its number:
       1

-- 
2.51.0

[PATCH 3/3] brief-yoctoprojectqs/index.rst: switch shell block to to console lexer

[Antonin Godard]

Console outputs are more accurately represented with the 'console'
lexer. Visually, it separates the command from the output. Switch shell
block to console blocks.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/brief-yoctoprojectqs/index.rst | 36 ++++++++++++++--------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 1e0d867d6..b8bd65f4a 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -95,13 +95,13 @@ get a copy of the ``bitbake-setup`` tool to setup the :term:`Poky` reference
 distribution on your build host. Use the following commands to clone
 the bitbake repository.
 
-.. code-block:: shell
+.. code-block:: console
 
    $ git clone https://git.openembedded.org/bitbake
 
 Setup a build environment with the following command:
 
-.. code-block:: shell
+.. code-block:: console
 
    $ ./bitbake/bin/bitbake-setup init
 
@@ -110,7 +110,7 @@ By default, this will setup a top directory in the current directory.
 If you prefer to setup your builds in a different top directory, for example
 ``$HOME/bitbake-builds``, you can set it with the :ref:`bitbake:ref-bbsetup-command-settings` command:
 
-.. code-block:: shell
+.. code-block:: console
 
    $ ./bitbake/bin/bitbake-setup settings set --global default top-dir-prefix $HOME
 
@@ -125,7 +125,7 @@ differ from the examples below.
 
 #. Choose a configuration (for example, ``poky-master``):
 
-   .. code-block:: shell
+   .. code-block:: console
 
       Available configurations:
       1. poky-master  Poky - The Yocto Project testing distribution configurations and hardware test platforms
@@ -140,7 +140,7 @@ differ from the examples below.
    Depending on the choice above, new options can be prompted to further specify
    which configuration to use. For example:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       Available bitbake configurations:
       1. poky Poky - The Yocto Project testing distribution
@@ -151,7 +151,7 @@ differ from the examples below.
 
 #. Choose a target :term:`MACHINE` (for example, ``qemux86-64``):
 
-   .. code-block:: shell
+   .. code-block:: console
 
       Target machines:
       1. machine/qemux86-64
@@ -165,7 +165,7 @@ differ from the examples below.
 
 #. Choose a :term:`DISTRO` (for example, ``poky``):
 
-   .. code-block:: shell
+   .. code-block:: console
 
       Distribution configuration variants:
       1. distro/poky
@@ -177,7 +177,7 @@ differ from the examples below.
 
 #. Choose a :term:`bitbake:setup` directory name:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       Enter setup directory name: [poky-master-poky-distro_poky-machine_qemux86-64]
 
@@ -189,7 +189,7 @@ differ from the examples below.
    If you prefer to run non-interactively, you can run a command like the
    following:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ bitbake-setup init --non-interactive poky-master poky-with-sstate distro/poky machine/qemux86-64
 
@@ -248,7 +248,7 @@ an entire Linux distribution, including the toolchain, from source.
     environment setup script within the :term:`bitbake:BitBake build` directory
     to setup the :term:`BitBake` build environment on your host:
 
-    .. code-block:: shell
+    .. code-block:: console
 
        $ source poky-master-poky-distro_poky-machine_qemux86-64/build/init-build-env
        Poky reference distro build
@@ -261,7 +261,7 @@ an entire Linux distribution, including the toolchain, from source.
     With this tool, list the currently enabled :term:`configuration fragments
     <Configuration Fragment>`:
 
-    .. code-block:: shell
+    .. code-block:: console
 
        $ bitbake-config-build list-fragments
 
@@ -288,7 +288,7 @@ an entire Linux distribution, including the toolchain, from source.
     can be useful for development, you can enable the
     :ref:`ref-fragments-root-login-with-empty-password` fragment:
 
-    .. code-block:: shell
+    .. code-block:: console
 
        $ bitbake-config-build enable-fragment root-login-with-empty-password
 
@@ -318,7 +318,7 @@ an entire Linux distribution, including the toolchain, from source.
 #. **Start the Build:** Continue with the following command to build an OS
    image for the target, which is ``core-image-sato`` in this example:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ bitbake core-image-sato
 
@@ -332,7 +332,7 @@ an entire Linux distribution, including the toolchain, from source.
    built, you can start QEMU, which is a Quick EMUlator that ships with
    the Yocto Project:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ runqemu qemux86-64
 
@@ -378,7 +378,7 @@ layer>`:
 
     For this, the ``bitbake-layers add-layer`` can be used:
 
-    .. code-block:: shell
+    .. code-block:: console
 
        $ bitbake-layers add-layer ../layers/meta-raspberrypi
 
@@ -393,7 +393,7 @@ layer>`:
     machine, so let's make it the :term:`MACHINE` used for the build with
     ``bitbake-config-build``:
 
-    .. code-block:: shell
+    .. code-block:: console
 
        $ bitbake-config-build enable-fragment machine/raspberrypi5
 
@@ -414,7 +414,7 @@ layer>`:
 #. **Start The Build:** The configuration is now set to build for the Raspberry
    Pi 5. Start the build again:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ bitbake core-image-sato
 
@@ -441,7 +441,7 @@ configuration file, a ``recipes-example`` subdirectory that contains an
 The following commands run the tool to create a layer named
 ``meta-mylayer``:
 
-.. code-block:: shell
+.. code-block:: console
 
    $ bitbake-layers create-layer ../layers/meta-mylayer
    NOTE: Starting bitbake server...

-- 
2.51.0

Re: [docs] [PATCH 3/3] brief-yoctoprojectqs/index.rst: switch shell block to to console lexer

[Quentin Schulz]

Hi Antonin,

On 11/27/25 5:37 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Console outputs are more accurately represented with the 'console'
> lexer. Visually, it separates the command from the output. Switch shell
> block to console blocks.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/brief-yoctoprojectqs/index.rst | 36 ++++++++++++++--------------
>   1 file changed, 18 insertions(+), 18 deletions(-)
> 
> diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
> index 1e0d867d6..b8bd65f4a 100644
> --- a/documentation/brief-yoctoprojectqs/index.rst
> +++ b/documentation/brief-yoctoprojectqs/index.rst
> @@ -95,13 +95,13 @@ get a copy of the ``bitbake-setup`` tool to setup the :term:`Poky` reference
>   distribution on your build host. Use the following commands to clone
>   the bitbake repository.
>   
> -.. code-block:: shell
> +.. code-block:: console
>   
>      $ git clone https://git.openembedded.org/bitbake
>   
>   Setup a build environment with the following command:
>   
> -.. code-block:: shell
> +.. code-block:: console
>   
>      $ ./bitbake/bin/bitbake-setup init
>   
> @@ -110,7 +110,7 @@ By default, this will setup a top directory in the current directory.
>   If you prefer to setup your builds in a different top directory, for example
>   ``$HOME/bitbake-builds``, you can set it with the :ref:`bitbake:ref-bbsetup-command-settings` command:
>   
> -.. code-block:: shell
> +.. code-block:: console
>   
>      $ ./bitbake/bin/bitbake-setup settings set --global default top-dir-prefix $HOME
>   
> @@ -125,7 +125,7 @@ differ from the examples below.
>   
>   #. Choose a configuration (for example, ``poky-master``):
>   
> -   .. code-block:: shell
> +   .. code-block:: console
>   

Neither shell nor console. I would suggest to simply use a literal block 
(::), c.f. 
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks

>         Available configurations:
>         1. poky-master  Poky - The Yocto Project testing distribution configurations and hardware test platforms
> @@ -140,7 +140,7 @@ differ from the examples below.
>      Depending on the choice above, new options can be prompted to further specify
>      which configuration to use. For example:
>   
> -   .. code-block:: shell
> +   .. code-block:: console
>   

Ditto.

>         Available bitbake configurations:
>         1. poky Poky - The Yocto Project testing distribution
> @@ -151,7 +151,7 @@ differ from the examples below.
>   
>   #. Choose a target :term:`MACHINE` (for example, ``qemux86-64``):
>   
> -   .. code-block:: shell
> +   .. code-block:: console
>   

Ditto.

>         Target machines:
>         1. machine/qemux86-64
> @@ -165,7 +165,7 @@ differ from the examples below.
>   
>   #. Choose a :term:`DISTRO` (for example, ``poky``):
>   
> -   .. code-block:: shell
> +   .. code-block:: console
>   

Ditto.

>         Distribution configuration variants:
>         1. distro/poky
> @@ -177,7 +177,7 @@ differ from the examples below.
>   
>   #. Choose a :term:`bitbake:setup` directory name:
>   
> -   .. code-block:: shell
> +   .. code-block:: console
>   

Ditto.

Cheers,
Quentin

Re: [docs] [PATCH 3/3] brief-yoctoprojectqs/index.rst: switch shell block to to console lexer

[Antonin Godard]

Hi,

On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
[...]
>>   #. Choose a configuration (for example, ``poky-master``):
>>   
>> -   .. code-block:: shell
>> +   .. code-block:: console
>>   
>
> Neither shell nor console. I would suggest to simply use a literal block 
> (::), c.f. 
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks

Thanks, I'll change that.

I just noticed but I think the default lexer for literal blocks is Python unless
you explicitly set it to something else in the global configuration[1]. I think
it makes sense to change it to "text" as the rendering looks odd in most places
where it thinks it's Python code, whereas most of the time it's either text
snippets or bitbake assignments.

Antonin

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

Re: [docs] [PATCH 3/3] brief-yoctoprojectqs/index.rst: switch shell block to to console lexer

[Antonin Godard]

On Fri Nov 28, 2025 at 2:11 PM CET, Antonin Godard wrote:
> Hi,
>
> On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> [...]
>>>   #. Choose a configuration (for example, ``poky-master``):
>>>   
>>> -   .. code-block:: shell
>>> +   .. code-block:: console
>>>   
>>
>> Neither shell nor console. I would suggest to simply use a literal block 
>> (::), c.f. 
>> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks
>
> Thanks, I'll change that.
>
> I just noticed but I think the default lexer for literal blocks is Python unless
> you explicitly set it to something else in the global configuration[1]. I think
> it makes sense to change it to "text" as the rendering looks odd in most places
> where it thinks it's Python code, whereas most of the time it's either text
> snippets or bitbake assignments.

Forgot the link :)

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks

End of the paragraph:

Code highlighting can be enabled for these literal blocks on a document-wide
basis using the highlight directive and on a project-wide basis using the
highlight_language configuration option. The code-block directive can be used to
set highlighting on a block-by-block basis.

Antonin

Re: [docs] [PATCH 3/3] brief-yoctoprojectqs/index.rst: switch shell block to to console lexer

[Quentin Schulz]

Hi Antonin,

On 11/28/25 2:11 PM, Antonin Godard wrote:
> Hi,
> 
> On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> [...]
>>>    #. Choose a configuration (for example, ``poky-master``):
>>>    
>>> -   .. code-block:: shell
>>> +   .. code-block:: console
>>>    
>>
>> Neither shell nor console. I would suggest to simply use a literal block
>> (::), c.f.
>> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks
> 
> Thanks, I'll change that.
> 
> I just noticed but I think the default lexer for literal blocks is Python unless
> you explicitly set it to something else in the global configuration[1]. I think

Ah, and I had missed that. I changed it to shell for my company's user 
manuals but I didn't know it was Python by default (well some sort of 
Python).

> it makes sense to change it to "text" as the rendering looks odd in most places
> where it thinks it's Python code, whereas most of the time it's either text
> snippets or bitbake assignments.
> 
I would recommend picking a sensible default. Since there doesn't exist 
a BitBake lexer (and I don't see a MR for that in pygments) yet, I guess 
going for "text" or "none" will do. Good catch!

This though will get rid of highlights where it is (to me) somewhat 
useful, see most blocks in 
https://docs.yoctoproject.org/ref-manual/variables.html. Maybe it isn't 
*that* worth it. Up to you.

Cheers,
Quentin

Re: [docs] [PATCH 3/3] brief-yoctoprojectqs/index.rst: switch shell block to to console lexer

[Antonin Godard]

Hi,

On Fri Nov 28, 2025 at 2:30 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 11/28/25 2:11 PM, Antonin Godard wrote:
>> Hi,
>> 
>> On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
>> [...]
>>>>    #. Choose a configuration (for example, ``poky-master``):
>>>>    
>>>> -   .. code-block:: shell
>>>> +   .. code-block:: console
>>>>    
>>>
>>> Neither shell nor console. I would suggest to simply use a literal block
>>> (::), c.f.
>>> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks
>> 
>> Thanks, I'll change that.
>> 
>> I just noticed but I think the default lexer for literal blocks is Python unless
>> you explicitly set it to something else in the global configuration[1]. I think
>
> Ah, and I had missed that. I changed it to shell for my company's user 
> manuals but I didn't know it was Python by default (well some sort of 
> Python).
>
>> it makes sense to change it to "text" as the rendering looks odd in most places
>> where it thinks it's Python code, whereas most of the time it's either text
>> snippets or bitbake assignments.
>> 
> I would recommend picking a sensible default. Since there doesn't exist 
> a BitBake lexer (and I don't see a MR for that in pygments) yet, I guess 
> going for "text" or "none" will do. Good catch!
>
> This though will get rid of highlights where it is (to me) somewhat 
> useful, see most blocks in 
> https://docs.yoctoproject.org/ref-manual/variables.html. Maybe it isn't 
> *that* worth it. Up to you.

Yes, re-reading some of the docs I also noticed it would get rid of some useful
highlighting, so I think for text blocks we should use .. code-block:: text when
we think about it. I'll use that for the quick start guide.

Thanks!
Antonin

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

Re: [PATCH 0/3] bitbake-setup updates

[Antonin Godard]

On Thu, 27 Nov 2025 17:37:44 +0100, Antonin Godard wrote:
> Add a commit to be able to use the release series in a numerical format,
> and use that number in what's shown in the output of bitbake-setup init.
> 
> Switch the shell code-blocks to console code-blocks.
> 
> 

Applied, thanks!

[1/3] poky.yaml.in: add DISTRO_RELEASE_SERIES
      commit: 4d6bce0c3c61ca7f6f49b5aa0dc69e9da9d7584b
[2/3] brief-yoctoprojectqs/index.rst: update available bitbake-setup configurations
      commit: e5cded397725835e3d352de163edd9806750e345
[3/3] brief-yoctoprojectqs/index.rst: switch shell block to to console lexer
      (no commit info)

Best regards,
-- 
Antonin Godard