[docs][PATCH 1/5] doc: change some terminology around bitbake-setup

All of lore.kernel.org
 help / color / mirror / Atom feed

* [docs][PATCH 1/5] doc: change some terminology around bitbake-setup
@ 2026-01-26 22:27 Daiane Angolini
  2026-01-26 22:27 ` [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs Daiane Angolini
                   ` (6 more replies)
  0 siblings, 7 replies; 22+ messages in thread
From: Daiane Angolini @ 2026-01-26 22:27 UTC (permalink / raw)
  To: bitbake-devel; +Cc: docs, Daiane Angolini

Change some terms to use more specific wording:

  Generic Configuration  -> BitBake Setup Template
  Specific Configuration -> BitBake Setup Instance
  nested configurations  -> Variant

Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
---
 .../bitbake-user-manual-environment-setup.rst | 88 +++++++++----------
 1 file changed, 44 insertions(+), 44 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
index 3b6a73fd8..824b01ffb 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -41,8 +41,8 @@ Quick Start
       $ ./bitbake/bin/bitbake-setup init
 
    This command will ask you to choose which configurations to use available as
-   part of the default BitBake :term:`generic configurations <generic
-   Configuration>`.
+   part of the default BitBake :term:`BitBake Setup Templates <BitBake Setup
+   Template>`.
 
    .. note::
 
@@ -73,8 +73,8 @@ Quick Start
 
       The name of the directory will vary depending on the choices.
 
-   -  ``config/``: holds the :term:`Specific Configuration`, which embeds the
-      :term:`Generic Configuration` (first choice of the :ref:`ref-bbsetup-command-init` command)
+   -  ``config/``: holds the :term:`BitBake Setup Instance`, which embeds the
+      :term:`BitBake Setup Template` (first choice of the :ref:`ref-bbsetup-command-init` command)
       and the choices made during the initialization.
 
    -  ``build/``: the :term:`BitBake Build` directory, where BitBake stores
@@ -145,12 +145,12 @@ The "Top Directory" and "Setup" directories are defined as follows:
    :term:`Setup`
       A Setup is the result of the :ref:`ref-bbsetup-command-init`
       command, which creates a :term:`Setup` directory. It is constructed from a
-      :term:`Generic Configuration` and choices made during the ``init`` command.
+      :term:`BitBake Setup Template` and choices made during the ``init`` command.
 
       It contains at least:
 
       -  A :term:`BitBake Build` (``build/`` directory).
-      -  A :term:`Specific Configuration` (``config/`` directory).
+      -  A :term:`BitBake Setup Instance` (``config/`` directory).
       -  Sources such as :ref:`layers
          <bitbake-user-manual/bitbake-user-manual-intro:Layers>` or other
          repositories managed by ``bitbake-setup`` (``layers/`` directory).
@@ -173,8 +173,8 @@ The following components are involved to create the content of these directories
       Build` constitute the :ref:`BitBake configuration
       <bitbake-user-manual/bitbake-user-manual-intro:Configuration Files>`.
 
-   :term:`Generic Configuration`
-      A Generic Configuration is a file in JSON format containing a template to
+   :term:`BitBake Setup Template`
+      A BitBake Setup Template is a file in JSON format containing a template to
       create a :term:`Setup`. These files are used during the :ref:`ref-bbsetup-command-init`
       command as a starting point to configure the :term:`Setup`. When the
       command runs, the user may be prompted with choices to further specify the
@@ -183,42 +183,42 @@ The following components are involved to create the content of these directories
       It is also possible to specify the choices on the command line for a
       completely non-interactive initialization.
 
-      :term:`Generic Configuration` files are stored in :term:`registries
+      :term:`BitBake Setup Template` files are stored in :term:`registries
       <Registry>`, and can be listed with the :ref:`ref-bbsetup-command-list`
       command.
 
-      :term:`Generic Configuration` files must end with the ``.conf.json``
+      :term:`BitBake Setup Template` files must end with the ``.conf.json``
       suffix for ``bitbake-setup`` to locate them.
 
       .. note::
 
-         The default :term:`Generic Configurations <Generic Configuration>` are
+         The default :term:`BitBake Setup Templates <BitBake Setup Template>` are
          located in the BitBake repository in a local registry. the
          ``default-registry/`` directory. This can be modified with the
          :ref:`ref-bbsetup-setting-registry` setting.
 
       :ref:`ref-bbsetup-command-status` will tell if a :term:`Setup`
-      is in sync with the :term:`Generic Configuration` it was constructed from
+      is in sync with the :term:`BitBake Setup Template` it was constructed from
       (typically: layer updates).
 
       :ref:`ref-bbsetup-command-update` will bring a :term:`Setup`
-      in sync with its :term:`Generic Configuration`.
+      in sync with its :term:`BitBake Setup Template`.
 
-   :term:`Specific Configuration`
-      The :term:`Specific Configuration` is stored in the ``config/`` directory
-      in a :term:`Setup`. It embeds the :term:`Generic Configuration` and the
+   :term:`BitBake Setup Instance`
+      The :term:`BitBake Setup Instance` is stored in the ``config/`` directory
+      in a :term:`Setup`. It embeds the :term:`BitBake Setup Template` and the
       choices made during the initialization.
 
-      It is also a Git repository, that contains a history of the specific
-      configuration and updates made to it via :ref:`ref-bbsetup-command-update`.
+      It is also a Git repository, that contains a history of the setup instance
+      and updates made to it via :ref:`ref-bbsetup-command-update`.
 
    :term:`Registry`
-      A configuration registry is a place where one or more :term:`Generic
-      Configurations <Generic Configuration>` are stored.
+      A configuration registry is a place where one or more :term:`BitBake
+      Setup Templates <BitBake Setup Template>` are stored.
 
       The directory structure of the registry can be any: ``bitbake-setup``
       recursively find files ending with ``.conf.json`` and consider it a
-      :term:`Generic Configuration`.
+      :term:`BitBake Setup Template`.
 
       The registry location is configured through the
       :ref:`ref-bbsetup-setting-registry` setting. This location can be the URL to
@@ -279,7 +279,7 @@ The ``bitbake-setup init`` sub-command helps initializing a :term:`Setup`.
 
 This command can be run without any arguments to prompt the user with
 configuration options to choose from. These configuration options are taken from
-the input :term:`Generic Configuration` files in the :term:`registry`.
+the input :term:`BitBake Setup Template` files in the :term:`registry`.
 
 .. note::
 
@@ -288,9 +288,9 @@ the input :term:`Generic Configuration` files in the :term:`registry`.
 
 Otherwise, the first argument to :ref:`ref-bbsetup-command-init` can be:
 
--  A generic configuration ID in the registry.
--  A path to a generic configuration file on a local disk.
--  An HTTP URI to the generic configuration file.
+-  A BitBake Setup Template ID in the registry.
+-  A path to a BitBake Setup Template file on a local disk.
+-  An HTTP URI to the BitBake Setup Template file.
 
 The choices made during the bare ``bitbake-setup init`` command can also be
 passed directly on the command-line, for example::
@@ -331,7 +331,7 @@ In addition, the command can take the following arguments:
 ``bitbake-setup init`` Examples
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  This example prompts the user to choose a :term:`Generic Configuration` from
+-  This example prompts the user to choose a :term:`BitBake Setup Template` from
    a custom registry:
 
    .. code-block:: shell
@@ -340,7 +340,7 @@ In addition, the command can take the following arguments:
           --setting default registry 'git://example.com/bitbake-setup-configurations.git;protocol=https;branch=main;rev=main' \
           init
 
--  This example takes a :term:`Generic Configuration` from a remote location
+-  This example takes a :term:`BitBake Setup Template` from a remote location
    (here, one of the default configuration in BitBake):
 
    .. code-block:: shell
@@ -351,7 +351,7 @@ In addition, the command can take the following arguments:
 
    -  A custom :ref:`ref-bbsetup-setting-top-dir-prefix` and :ref:`ref-bbsetup-setting-top-dir-name`
    -  A :term:`source override`, and additionally overriding openembedded-core with a locally managed directory.
-   -  A standalone :term:`generic configuration` file.
+   -  A standalone :term:`BitBake Setup Template` file.
    -  Choices passed on the command-line, applied non-interactively.
 
    .. code-block:: shell
@@ -371,8 +371,8 @@ In addition, the command can take the following arguments:
 ``bitbake-setup list``
 ----------------------
 
-The ``bitbake-setup list`` sub-command lists the available :term:`generic
-configurations <generic configuration>` in the current :term:`registry`.
+The ``bitbake-setup list`` sub-command lists the available :term:`BitBake Setup
+Templates <BitBake Setup Template>` in the current :term:`registry`.
 
 In addition, the command can take the following arguments:
 
@@ -388,8 +388,8 @@ In addition, the command can take the following arguments:
 ------------------------
 
 The ``bitbake-setup status`` sub-command shows the status of a
-:term:`Setup`. Any differences between the local copy of the :term:`generic
-configuration` and the upstream one are printed on the console.
+:term:`Setup`. Any differences between the local copy of the :term:`BitBake Setup
+Template` and the upstream one are printed on the console.
 
 If the BitBake environment is sourced and ready to build, the ``bitbake-setup
 status`` command (without any arguments) will show the status of the current
@@ -407,7 +407,7 @@ In addition, the command can take the following arguments:
 ------------------------
 
 The ``bitbake-setup update`` sub-command updates a :term:`Setup` to sync with
-the latest changes from a :term:`generic configuration` it was constructed from.
+the latest changes from the :term:`BitBake Setup Template` it was constructed from.
 The :ref:`ref-bbsetup-command-status` command can be used to show the current
 status of the :term:`Setup` before updating it.
 
@@ -617,16 +617,16 @@ manner.
 
 The :ref:`ref-bbsetup-setting-use-full-setup-dir-name` setting, if set to ``yes``
 will override the suggestions for the :term:`Setup` directory name made by
-``setup-dir-name`` entries in :term:`Generic Configuration` files. This
+``setup-dir-name`` entries in :term:`BitBake Setup Template` files. This
 will make the directory names longer, but fully specific: they will contain
 all selections made during initialization.
 
 .. _ref-bbsetup-section-config-reference:
 
-Generic Configuration Files Reference
-=====================================
+BitBake Setup Template Files Reference
+======================================
 
-:term:`Generic Configurations <Generic Configuration>` are the input files given
+:term:`BitBake Setup Templates <BitBake Setup Template>` are the input files given
 to ``bitbake-setup`` to configure :term:`Setups <Setup>`.
 
 These files are written in the JSON file format and are stored in a
@@ -792,8 +792,8 @@ They contain the following sections:
       snippet. This is what is prompted during the
       :ref:`ref-bbsetup-command-init` command execution.
 
-   -  ``configurations``: Configurations can recursively contain as many nested
-      configurations as needed. This will create more choices when running the
+   -  ``configurations``: Configurations can recursively contain as many
+      variants as needed. This will create more choices when running the
       :ref:`ref-bbsetup-command-init` command.
 
       The purpose of such nesting is to be able to scale the configurations, for
@@ -891,8 +891,8 @@ They contain the following sections:
 
       would expand to ``somebuild-machine_gadget``.
 
-Generic Configuration Examples
-------------------------------
+BitBake Setup Template Examples
+-------------------------------
 
 OpenEmbedded "nodistro" configuration for master branches:
 
@@ -945,10 +945,10 @@ Here is an example file that overrides the branch of the BitBake repository to
    }
 
 -  The ``version`` parameter contains the version of the used configuration, and
-   should match the one of the :term:`Generic Configuration` file in use.
+   should match the one of the :term:`BitBake Setup Template` file in use.
 
 -  The ``sources`` section contains the same options as the ``sources`` option
-   of a :term:`Generic Configuration` file. See the
+   of a :term:`BitBake Setup Template` file. See the
    :ref:`ref-bbsetup-section-config-reference` section for more information.
 
 .. _ref-bbsetup-fixed-revisions:
@@ -956,7 +956,7 @@ Here is an example file that overrides the branch of the BitBake repository to
 Fixed source revisions
 ======================
 
-:term:`Generic Configuration` can set source revisions in ``rev`` to a tag or a branch.
+:term:`BitBake Setup Template` can set source revisions in ``rev`` to a tag or a branch.
 Bitbake-setup will make sure the actual revision will match the tag or branch when performing
 initializations or updates, and will capture the revisions in a :ref:`ref-bbsetup-source-overrides`
 file.
-- 
2.34.1



^ permalink raw reply related	[flat|nested] 22+ messages in thread

* [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs
  2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
@ 2026-01-26 22:27 ` Daiane Angolini
  2026-01-27 10:29   ` Antonin Godard
  2026-01-26 22:27 ` [docs][PATCH 3/5] docs: Fix leading text for bitbake-setup init Daiane Angolini
                   ` (5 subsequent siblings)
  6 siblings, 1 reply; 22+ messages in thread
From: Daiane Angolini @ 2026-01-26 22:27 UTC (permalink / raw)
  To: bitbake-devel; +Cc: docs, Daiane Angolini

The original output in the script does not use the original terminology
from the document. This patch changes the script output to match the
terminoly, this way user can search the documentation for help.

Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
---
 bin/bitbake-setup                                         | 8 ++++----
 default-registry/configurations/poky-master.conf.json     | 2 +-
 default-registry/configurations/poky-whinlatter.conf.json | 2 +-
 .../bitbake-user-manual-environment-setup.rst             | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/bin/bitbake-setup b/bin/bitbake-setup
index abe7614c8..65f0c5eb3 100755
--- a/bin/bitbake-setup
+++ b/bin/bitbake-setup
@@ -457,11 +457,11 @@ def choose_bitbake_config(configs, parameters, non_interactive):
     if non_interactive:
         raise Exception("Unable to choose from bitbake configurations in non-interactive mode: {}".format(configs_dict))
 
-    logger.plain("\nAvailable bitbake configurations:")
+    logger.plain("\nAvailable Variants:")
     for n, config_data in enumerated_configs:
         logger.plain("{}. {}\t{}".format(n, config_data["name"], config_data["description"]))
     config_n = int_input([i[0] for i in enumerated_configs],
-                         "\nPlease select one of the above bitbake configurations by its number: ") - 1
+                         "\nPlease select one of the above Variants by its number: ") - 1
     return flattened_configs[config_n]
 
 def choose_config(configs, non_interactive):
@@ -475,7 +475,7 @@ def choose_config(configs, non_interactive):
     if non_interactive:
         raise Exception("Unable to choose from configurations in non-interactive mode: {}".format(not_expired_configs))
 
-    logger.plain("\nAvailable configurations:")
+    logger.plain("\nAvailable BitBake Setup Template:")
     for n, config_name in config_list:
         config_data = configs[config_name]
         expiry_date = config_data.get("expires", None)
@@ -485,7 +485,7 @@ def choose_config(configs, non_interactive):
         else:
            logger.plain("{}. {}\t{}".format(n, config_name, config_desc))
     config_n = int_input([i[0] for i in config_list],
-                         "\nPlease select one of the above configurations by its number: ") - 1
+                         "\nPlease select one of the above BitBake Setup Templates by its number: ") - 1
     return config_list[config_n][1]
 
 def choose_fragments(possibilities, parameters, non_interactive, skip_selection):
diff --git a/default-registry/configurations/poky-master.conf.json b/default-registry/configurations/poky-master.conf.json
index 1de038bab..f248a4811 100644
--- a/default-registry/configurations/poky-master.conf.json
+++ b/default-registry/configurations/poky-master.conf.json
@@ -57,7 +57,7 @@
                     "options" : ["machine/qemux86-64", "machine/qemuarm64", "machine/qemuriscv64", "machine/genericarm64", "machine/genericx86-64"]
                 },
                 "distro": {
-                    "description": "Distribution configuration variants",
+                    "description": "Target Distributions",
                     "options" : ["distro/poky", "distro/poky-altcfg", "distro/poky-tiny"]
                 }
             },
diff --git a/default-registry/configurations/poky-whinlatter.conf.json b/default-registry/configurations/poky-whinlatter.conf.json
index bfa67426d..4827ebe11 100644
--- a/default-registry/configurations/poky-whinlatter.conf.json
+++ b/default-registry/configurations/poky-whinlatter.conf.json
@@ -58,7 +58,7 @@
                     "options" : ["machine/qemux86-64", "machine/qemuarm64", "machine/qemuriscv64", "machine/genericarm64", "machine/genericx86-64"]
                 },
                 "distro": {
-                    "description": "Distribution configuration variants",
+                    "description": "Target Distributions",
                     "options" : ["distro/poky", "distro/poky-altcfg", "distro/poky-tiny"]
                 }
             },
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
index 824b01ffb..7bbe7cc75 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -347,7 +347,7 @@ In addition, the command can take the following arguments:
 
       $ ./bitbake/bin/bitbake-setup init https://git.openembedded.org/bitbake/plain/default-registry/configurations/oe-nodistro-master.conf.json
 
--  This example initializes a :term:`Setup` with: 
+-  This example initializes a :term:`Setup` with:
 
    -  A custom :ref:`ref-bbsetup-setting-top-dir-prefix` and :ref:`ref-bbsetup-setting-top-dir-name`
    -  A :term:`source override`, and additionally overriding openembedded-core with a locally managed directory.
@@ -762,7 +762,7 @@ They contain the following sections:
                         "options" : ["machine/qemux86-64", "machine/qemuarm64", "machine/qemuriscv64", "machine/genericarm64", "machine/genericx86-64"]
                     },
                     "distro": {
-                        "description": "Distribution configuration variants",
+                        "description": "Target Distributions",
                         "options" : ["distro/poky", "distro/poky-altcfg", "distro/poky-tiny"]
                     }
                 },
-- 
2.34.1



^ permalink raw reply related	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs
  2026-01-26 22:27 ` [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs Daiane Angolini
@ 2026-01-27 10:29   ` Antonin Godard
  2026-01-27 10:38     ` Alexander Kanavin
  0 siblings, 1 reply; 22+ messages in thread
From: Antonin Godard @ 2026-01-27 10:29 UTC (permalink / raw)
  To: daiane.angolini, bitbake-devel; +Cc: docs

Hi,

On Mon Jan 26, 2026 at 11:27 PM CET, Daiane Angolini via lists.yoctoproject.org wrote:
> The original output in the script does not use the original terminology
> from the document. This patch changes the script output to match the
> terminoly, this way user can search the documentation for help.
>
> Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
> ---
>  bin/bitbake-setup                                         | 8 ++++----
>  default-registry/configurations/poky-master.conf.json     | 2 +-
>  default-registry/configurations/poky-whinlatter.conf.json | 2 +-
>  .../bitbake-user-manual-environment-setup.rst             | 4 ++--
>  4 files changed, 8 insertions(+), 8 deletions(-)
>
> diff --git a/bin/bitbake-setup b/bin/bitbake-setup
> index abe7614c8..65f0c5eb3 100755
> --- a/bin/bitbake-setup
> +++ b/bin/bitbake-setup
> @@ -457,11 +457,11 @@ def choose_bitbake_config(configs, parameters, non_interactive):
>      if non_interactive:
>          raise Exception("Unable to choose from bitbake configurations in non-interactive mode: {}".format(configs_dict))
>  
> -    logger.plain("\nAvailable bitbake configurations:")
> +    logger.plain("\nAvailable Variants:")
>      for n, config_data in enumerated_configs:
>          logger.plain("{}. {}\t{}".format(n, config_data["name"], config_data["description"]))
>      config_n = int_input([i[0] for i in enumerated_configs],
> -                         "\nPlease select one of the above bitbake configurations by its number: ") - 1
> +                         "\nPlease select one of the above Variants by its number: ") - 1
>      return flattened_configs[config_n]
>  
>  def choose_config(configs, non_interactive):
> @@ -475,7 +475,7 @@ def choose_config(configs, non_interactive):
>      if non_interactive:
>          raise Exception("Unable to choose from configurations in non-interactive mode: {}".format(not_expired_configs))
>  
> -    logger.plain("\nAvailable configurations:")
> +    logger.plain("\nAvailable BitBake Setup Template:")

s/Template/Templates/

Antonin

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



^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs
  2026-01-27 10:29   ` Antonin Godard
@ 2026-01-27 10:38     ` Alexander Kanavin
  2026-01-27 13:21       ` Daiane Angolini
  0 siblings, 1 reply; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 10:38 UTC (permalink / raw)
  To: antonin.godard; +Cc: daiane.angolini, bitbake-devel, docs

On Tue, 27 Jan 2026 at 11:29, Antonin Godard via
lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> > -    logger.plain("\nAvailable bitbake configurations:")
> > +    logger.plain("\nAvailable Variants:")

To be honest, I am no longer sure introducing 'variants' as a term is
an improvement. Someone well familiar with the terms will get it,
someone running the tool for the first time will be baffled. 'bitbake
confugurations' is more familiar and straightforward.

Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs
  2026-01-27 10:38     ` Alexander Kanavin
@ 2026-01-27 13:21       ` Daiane Angolini
  2026-01-27 17:45         ` Alexander Kanavin
  0 siblings, 1 reply; 22+ messages in thread
From: Daiane Angolini @ 2026-01-27 13:21 UTC (permalink / raw)
  To: Alexander Kanavin; +Cc: antonin.godard, bitbake-devel, docs

On Tue, Jan 27, 2026 at 7:38 AM Alexander Kanavin
<alex.kanavin@gmail.com> wrote:
>
> On Tue, 27 Jan 2026 at 11:29, Antonin Godard via
> lists.yoctoproject.org
> <antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> > > -    logger.plain("\nAvailable bitbake configurations:")
> > > +    logger.plain("\nAvailable Variants:")
>
> To be honest, I am no longer sure introducing 'variants' as a term is
> an improvement. Someone well familiar with the terms will get it,
> someone running the tool for the first time will be baffled. 'bitbake
> confugurations' is more familiar and straightforward.

If everything is configuration, all stuff is the same for the
newcomer. Bitbake configuration is the most generic way to refer to
anything. If I have a site.conf with DL_DIR set there, it's a bitbake
configuration, if I have a KERNEL_DEVICE inside a machine.conf it's a
bitbake configuration.

How do you like Fragment Set?


>
> Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs
  2026-01-27 13:21       ` Daiane Angolini
@ 2026-01-27 17:45         ` Alexander Kanavin
  2026-01-27 18:17           ` Daiane Angolini
  0 siblings, 1 reply; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 17:45 UTC (permalink / raw)
  To: Daiane Angolini; +Cc: antonin.godard, bitbake-devel, docs

On Tue, 27 Jan 2026 at 14:21, Daiane Angolini
<daiane.angolini@foundries.io> wrote:
> If everything is configuration, all stuff is the same for the
> newcomer. Bitbake configuration is the most generic way to refer to
> anything. If I have a site.conf with DL_DIR set there, it's a bitbake
> configuration, if I have a KERNEL_DEVICE inside a machine.conf it's a
> bitbake configuration.
>
> How do you like Fragment Set?

It's not just the fragment set. It's also what layers are enabled in
bblayers.conf, and what is in site.conf. All these things together are
collected in build/conf/, they define what bitbake starts with (the
metadata in layers is pulled in based on what layers are included in
bblayers.conf) , and they are commonly understood as adding parameters
to bitbake configuration for a particular build directory, on top of
layer metadata - if you change those things, then it affects only that
build directory.

So maybe 'bitbake configuration' isn't unambigious, but tweaking
build/conf to adjust the bitbake configuration without changing layers
is a well understood concept. Can you suggest a better name for that?

Alex

^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs
  2026-01-27 17:45         ` Alexander Kanavin
@ 2026-01-27 18:17           ` Daiane Angolini
  0 siblings, 0 replies; 22+ messages in thread
From: Daiane Angolini @ 2026-01-27 18:17 UTC (permalink / raw)
  To: Alexander Kanavin; +Cc: antonin.godard, bitbake-devel, docs

On Tue, Jan 27, 2026 at 2:45 PM Alexander Kanavin
<alex.kanavin@gmail.com> wrote:
>
> On Tue, 27 Jan 2026 at 14:21, Daiane Angolini
> <daiane.angolini@foundries.io> wrote:
> > If everything is configuration, all stuff is the same for the
> > newcomer. Bitbake configuration is the most generic way to refer to
> > anything. If I have a site.conf with DL_DIR set there, it's a bitbake
> > configuration, if I have a KERNEL_DEVICE inside a machine.conf it's a
> > bitbake configuration.
> >
> > How do you like Fragment Set?
>
> It's not just the fragment set. It's also what layers are enabled in
> bblayers.conf, and what is in site.conf. All these things together are
> collected in build/conf/, they define what bitbake starts with (the
> metadata in layers is pulled in based on what layers are included in
> bblayers.conf) , and they are commonly understood as adding parameters
> to bitbake configuration for a particular build directory, on top of
> layer metadata - if you change those things, then it affects only that
> build directory.
>
> So maybe 'bitbake configuration' isn't unambigious, but tweaking
> build/conf to adjust the bitbake configuration without changing layers
> is a well understood concept. Can you suggest a better name for that?

Not today. Today I can only think about "former local.conf".

I will prepare v2 without touching on variants.

Daiane
>
> Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* [docs][PATCH 3/5] docs: Fix leading text for bitbake-setup init
  2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
  2026-01-26 22:27 ` [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs Daiane Angolini
@ 2026-01-26 22:27 ` Daiane Angolini
  2026-01-27 10:29   ` Antonin Godard
  2026-01-26 22:27 ` [docs][PATCH 4/5] doc: Add the term Variant Daiane Angolini
                   ` (4 subsequent siblings)
  6 siblings, 1 reply; 22+ messages in thread
From: Daiane Angolini @ 2026-01-26 22:27 UTC (permalink / raw)
  To: bitbake-devel; +Cc: docs, Daiane Angolini

If we use the default of bitbake-setut init we may not create anything
(as the first default for an empty directory is N).

If user does not chose a number, the script asks again for a number.

Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
---
 .../bitbake-user-manual-environment-setup.rst                   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
index 7bbe7cc75..e316ead56 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -50,7 +50,7 @@ Quick Start
       See the :ref:`ref-bbsetup-section-config-reference` section to learn more
       about ``bitbake-setup`` input configuration files.
 
-#. With the default choices, the ``bitbake-setup init`` command creates the
+#. One example of ``bitbake-setup init`` possible command creates the
    following files and directories::
 
       ./bitbake-builds/
-- 
2.34.1



^ permalink raw reply related	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 3/5] docs: Fix leading text for bitbake-setup init
  2026-01-26 22:27 ` [docs][PATCH 3/5] docs: Fix leading text for bitbake-setup init Daiane Angolini
@ 2026-01-27 10:29   ` Antonin Godard
  2026-01-27 10:43     ` Alexander Kanavin
  0 siblings, 1 reply; 22+ messages in thread
From: Antonin Godard @ 2026-01-27 10:29 UTC (permalink / raw)
  To: daiane.angolini, bitbake-devel; +Cc: docs

On Mon Jan 26, 2026 at 11:27 PM CET, Daiane Angolini via lists.yoctoproject.org wrote:
> If we use the default of bitbake-setut init we may not create anything
> (as the first default for an empty directory is N).
>
> If user does not chose a number, the script asks again for a number.
>
> Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
> ---
>  .../bitbake-user-manual-environment-setup.rst                   | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> index 7bbe7cc75..e316ead56 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -50,7 +50,7 @@ Quick Start
>        See the :ref:`ref-bbsetup-section-config-reference` section to learn more
>        about ``bitbake-setup`` input configuration files.
>  
> -#. With the default choices, the ``bitbake-setup init`` command creates the
> +#. One example of ``bitbake-setup init`` possible command creates the
>     following files and directories::
>  
>        ./bitbake-builds/

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks!
Antonin

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



^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 3/5] docs: Fix leading text for bitbake-setup init
  2026-01-27 10:29   ` Antonin Godard
@ 2026-01-27 10:43     ` Alexander Kanavin
  0 siblings, 0 replies; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 10:43 UTC (permalink / raw)
  To: antonin.godard; +Cc: daiane.angolini, bitbake-devel, docs

On Tue, 27 Jan 2026 at 11:29, Antonin Godard via
lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> > -#. With the default choices, the ``bitbake-setup init`` command creates the
> > +#. One example of ``bitbake-setup init`` possible command creates the
> >     following files and directories::

"One example of 'bitbake-setup init' possible command creates ...' is
very clumsy.

Better:
Here is a example of a directory/file tree structure created by
'bitbake-setup init'

Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* [docs][PATCH 4/5] doc: Add the term Variant
  2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
  2026-01-26 22:27 ` [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs Daiane Angolini
  2026-01-26 22:27 ` [docs][PATCH 3/5] docs: Fix leading text for bitbake-setup init Daiane Angolini
@ 2026-01-26 22:27 ` Daiane Angolini
  2026-01-27 10:28   ` Antonin Godard
  2026-01-26 22:27 ` [docs][PATCH 5/5] docs: Fix sources as required Daiane Angolini
                   ` (3 subsequent siblings)
  6 siblings, 1 reply; 22+ messages in thread
From: Daiane Angolini @ 2026-01-26 22:27 UTC (permalink / raw)
  To: bitbake-devel; +Cc: docs, Daiane Angolini

It also add a description for the term based on the concept that a
variant is a fragment or a set of fragments.

Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
---
 .../bitbake-user-manual-environment-setup.rst          | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
index e316ead56..700e02216 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -212,6 +212,16 @@ The following components are involved to create the content of these directories
       It is also a Git repository, that contains a history of the setup instance
       and updates made to it via :ref:`ref-bbsetup-command-update`.
 
+   :term:`Variant`
+      A Variant is a fragment or a set of fragments grouped under a name that
+      makes sense for a project. It is a nested configuration within a
+      :term:`BitBake Setup Template`.
+
+      A :term:`BitBake Setup Template` can contain multiple variants. Users
+      select among them during the :ref:`ref-bbsetup-command-init` command to
+      customize the :term:`Setup`. Variants enable scaling configurations by
+      sharing common parameters in a parent while differing in specific settings.
+
    :term:`Registry`
       A configuration registry is a place where one or more :term:`BitBake
       Setup Templates <BitBake Setup Template>` are stored.
-- 
2.34.1



^ permalink raw reply related	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 4/5] doc: Add the term Variant
  2026-01-26 22:27 ` [docs][PATCH 4/5] doc: Add the term Variant Daiane Angolini
@ 2026-01-27 10:28   ` Antonin Godard
  2026-01-27 10:46     ` Alexander Kanavin
  0 siblings, 1 reply; 22+ messages in thread
From: Antonin Godard @ 2026-01-27 10:28 UTC (permalink / raw)
  To: daiane.angolini, bitbake-devel; +Cc: docs

Hi,

On Mon Jan 26, 2026 at 11:27 PM CET, Daiane Angolini via lists.yoctoproject.org wrote:
> It also add a description for the term based on the concept that a
> variant is a fragment or a set of fragments.
>
> Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
> ---
>  .../bitbake-user-manual-environment-setup.rst          | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> index e316ead56..700e02216 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -212,6 +212,16 @@ The following components are involved to create the content of these directories
>        It is also a Git repository, that contains a history of the setup instance
>        and updates made to it via :ref:`ref-bbsetup-command-update`.
>  
> +   :term:`Variant`
> +      A Variant is a fragment or a set of fragments grouped under a name that

I think multiple variants could contains different set of layers too
(bb-layers). So it's not limited to fragments?
Also bb-env-passthrough-additions, etc.

> +      makes sense for a project. It is a nested configuration within a
> +      :term:`BitBake Setup Template`.
> +
> +      A :term:`BitBake Setup Template` can contain multiple variants. Users
> +      select among them during the :ref:`ref-bbsetup-command-init` command to
> +      customize the :term:`Setup`. Variants enable scaling configurations by
> +      sharing common parameters in a parent while differing in specific settings.
> +
>     :term:`Registry`
>        A configuration registry is a place where one or more :term:`BitBake
>        Setup Templates <BitBake Setup Template>` are stored.


Antonin

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



^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 4/5] doc: Add the term Variant
  2026-01-27 10:28   ` Antonin Godard
@ 2026-01-27 10:46     ` Alexander Kanavin
  0 siblings, 0 replies; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 10:46 UTC (permalink / raw)
  To: antonin.godard; +Cc: daiane.angolini, bitbake-devel, docs

On Tue, 27 Jan 2026 at 11:29, Antonin Godard via
lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> I think multiple variants could contains different set of layers too
> (bb-layers). So it's not limited to fragments?
> Also bb-env-passthrough-additions, etc.

TBH, I think we should drop 'variants' altogether, and just refer to
'bitbake configurations'. We can explain that a list of bitbake
configurations is formed by flattening the configurations template,
and when a user selects from that list, and further selects from
fragment choices, that selection (together with the layer spec)
becomes a *configuration instance*.

Alex

^ permalink raw reply	[flat|nested] 22+ messages in thread

* [docs][PATCH 5/5] docs: Fix sources as required
  2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
                   ` (2 preceding siblings ...)
  2026-01-26 22:27 ` [docs][PATCH 4/5] doc: Add the term Variant Daiane Angolini
@ 2026-01-26 22:27 ` Daiane Angolini
  2026-01-27 10:28   ` [bitbake-devel] " Antonin Godard
  2026-01-27 10:18 ` [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Alexander Kanavin
                   ` (2 subsequent siblings)
  6 siblings, 1 reply; 22+ messages in thread
From: Daiane Angolini @ 2026-01-26 22:27 UTC (permalink / raw)
  To: bitbake-devel; +Cc: docs, Daiane Angolini

If sources is empty, nothing happens. So let's just not say it's
optional, and let's say the minimum is bitbake source code.

Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
---
 .../bitbake-user-manual-environment-setup.rst               | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
index 700e02216..5d6bcbea1 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -671,8 +671,10 @@ They contain the following sections:
           "description": "OpenEmbedded - 'nodistro' basic configuration"
       }
 
--  ``sources`` (*optional*): sources, such as git repositories that should be provided
-   under ``layers/`` directory of a :term:`Setup`.
+-  ``sources``: sources, such as git repositories that should be provided
+   under ``layers/`` directory of a :term:`Setup`. Although the list of sources
+   can be very flexible, at least BitBake should be cloned to generate a
+   :term:`Setup`.
 
    Example:
 
-- 
2.34.1



^ permalink raw reply related	[flat|nested] 22+ messages in thread

* Re: [bitbake-devel] [docs][PATCH 5/5] docs: Fix sources as required
  2026-01-26 22:27 ` [docs][PATCH 5/5] docs: Fix sources as required Daiane Angolini
@ 2026-01-27 10:28   ` Antonin Godard
  2026-01-27 10:50     ` Alexander Kanavin
  0 siblings, 1 reply; 22+ messages in thread
From: Antonin Godard @ 2026-01-27 10:28 UTC (permalink / raw)
  To: daiane.angolini, bitbake-devel; +Cc: docs

Hi,

On Mon Jan 26, 2026 at 11:27 PM CET, Daiane Angolini via lists.openembedded.org wrote:
> If sources is empty, nothing happens. So let's just not say it's
> optional, and let's say the minimum is bitbake source code.
>
> Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
> ---
>  .../bitbake-user-manual-environment-setup.rst               | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> index 700e02216..5d6bcbea1 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -671,8 +671,10 @@ They contain the following sections:
>            "description": "OpenEmbedded - 'nodistro' basic configuration"
>        }
>  
> --  ``sources`` (*optional*): sources, such as git repositories that should be provided
> -   under ``layers/`` directory of a :term:`Setup`.
> +-  ``sources``: sources, such as git repositories that should be provided

To align with the rest, this should contain "(**required**)" then

> +   under ``layers/`` directory of a :term:`Setup`. Although the list of sources
> +   can be very flexible, at least BitBake should be cloned to generate a
> +   :term:`Setup`.
>  
>     Example:
>  


Antonin

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



^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [bitbake-devel] [docs][PATCH 5/5] docs: Fix sources as required
  2026-01-27 10:28   ` [bitbake-devel] " Antonin Godard
@ 2026-01-27 10:50     ` Alexander Kanavin
  2026-01-27 13:27       ` Daiane Angolini
  0 siblings, 1 reply; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 10:50 UTC (permalink / raw)
  To: antonin.godard; +Cc: daiane.angolini, bitbake-devel, docs

On Tue, 27 Jan 2026 at 11:28, Antonin Godard via
lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> > +   under ``layers/`` directory of a :term:`Setup`. Although the list of sources
> > +   can be very flexible, at least BitBake should be cloned to generate a
> > +   :term:`Setup`.

Not necessarily. It's an esoteric example, but one could write a list
of sources without bitbake in it, and leave 'configurations' empty. In
this case bitbake-setup will clone/unpack the sources and stop there.

Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [bitbake-devel] [docs][PATCH 5/5] docs: Fix sources as required
  2026-01-27 10:50     ` Alexander Kanavin
@ 2026-01-27 13:27       ` Daiane Angolini
  2026-01-27 17:46         ` Alexander Kanavin
  0 siblings, 1 reply; 22+ messages in thread
From: Daiane Angolini @ 2026-01-27 13:27 UTC (permalink / raw)
  To: Alexander Kanavin; +Cc: antonin.godard, bitbake-devel, docs

On Tue, Jan 27, 2026 at 7:50 AM Alexander Kanavin
<alex.kanavin@gmail.com> wrote:
>
> On Tue, 27 Jan 2026 at 11:28, Antonin Godard via
> lists.yoctoproject.org
> <antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> > > +   under ``layers/`` directory of a :term:`Setup`. Although the list of sources
> > > +   can be very flexible, at least BitBake should be cloned to generate a
> > > +   :term:`Setup`.
>
> Not necessarily. It's an esoteric example, but one could write a list
> of sources without bitbake in it, and leave 'configurations' empty. In
> this case bitbake-setup will clone/unpack the sources and stop there.

For this one, I'm really guessing. Because, when I made a "wrong" json
file, I got an error that bitbake source is needed (so I added
bitbake).

But when I drop "sources" completely, nothing is created (and I was
expecting at least the top directory and the .conf files)

So, saying it's "optional" is not accurate, but saying it's "required"
is not accurate either.  But I don't quite understand the constraints
here.

Daiane
>
> Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [bitbake-devel] [docs][PATCH 5/5] docs: Fix sources as required
  2026-01-27 13:27       ` Daiane Angolini
@ 2026-01-27 17:46         ` Alexander Kanavin
  2026-01-27 18:06           ` Daiane Angolini
  0 siblings, 1 reply; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 17:46 UTC (permalink / raw)
  To: Daiane Angolini; +Cc: antonin.godard, bitbake-devel, docs

On Tue, 27 Jan 2026 at 14:27, Daiane Angolini
<daiane.angolini@foundries.io> wrote:
> For this one, I'm really guessing. Because, when I made a "wrong" json
> file, I got an error that bitbake source is needed (so I added
> bitbake).
>
> But when I drop "sources" completely, nothing is created (and I was
> expecting at least the top directory and the .conf files)
>
> So, saying it's "optional" is not accurate, but saying it's "required"
> is not accurate either.  But I don't quite understand the constraints
> here.

It's just that these are all not very common corner cases, and they
aren't tested. We test the common case, but if behaviour in such
special situations doesn't make sense, that can be fixed in the tool
itself if there's a need for it.

'configurations' without 'sources' doesn't make sense though, as
configurations contain lists of layers and fragments, which are both
references into sources .

Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [bitbake-devel] [docs][PATCH 5/5] docs: Fix sources as required
  2026-01-27 17:46         ` Alexander Kanavin
@ 2026-01-27 18:06           ` Daiane Angolini
  0 siblings, 0 replies; 22+ messages in thread
From: Daiane Angolini @ 2026-01-27 18:06 UTC (permalink / raw)
  To: Alexander Kanavin; +Cc: antonin.godard, bitbake-devel, docs

On Tue, Jan 27, 2026 at 2:47 PM Alexander Kanavin
<alex.kanavin@gmail.com> wrote:
>
> On Tue, 27 Jan 2026 at 14:27, Daiane Angolini
> <daiane.angolini@foundries.io> wrote:
> > For this one, I'm really guessing. Because, when I made a "wrong" json
> > file, I got an error that bitbake source is needed (so I added
> > bitbake).
> >
> > But when I drop "sources" completely, nothing is created (and I was
> > expecting at least the top directory and the .conf files)
> >
> > So, saying it's "optional" is not accurate, but saying it's "required"
> > is not accurate either.  But I don't quite understand the constraints
> > here.
>
> It's just that these are all not very common corner cases, and they
> aren't tested. We test the common case, but if behaviour in such
> special situations doesn't make sense, that can be fixed in the tool
> itself if there's a need for it.
>
> 'configurations' without 'sources' doesn't make sense though, as
> configurations contain lists of layers and fragments, which are both
> references into sources .

so, it's required.

Daiane
>
> Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 1/5] doc: change some terminology around bitbake-setup
  2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
                   ` (3 preceding siblings ...)
  2026-01-26 22:27 ` [docs][PATCH 5/5] docs: Fix sources as required Daiane Angolini
@ 2026-01-27 10:18 ` Alexander Kanavin
  2026-01-27 10:28 ` Antonin Godard
  2026-01-27 10:35 ` Alexander Kanavin
  6 siblings, 0 replies; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 10:18 UTC (permalink / raw)
  To: daiane.angolini; +Cc: bitbake-devel, docs

On Mon, 26 Jan 2026 at 23:28, Daiane Angolini via
lists.yoctoproject.org
<daiane.angolini=foundries.io@lists.yoctoproject.org> wrote:
> Change some terms to use more specific wording:
>
>   Generic Configuration  -> BitBake Setup Template
>   Specific Configuration -> BitBake Setup Instance

I believe the consensus was to retain the word 'configuration'. E.g

'generic configuration' -> 'configuration template'
'specific configuration' -> 'configuration instance'

From the context (bitbake-setup docs, bitbake-setup output) it should
be obvious that it's bitbake-setup configurations, so I guess it
doesn't need to be prefixed.

Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 1/5] doc: change some terminology around bitbake-setup
  2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
                   ` (4 preceding siblings ...)
  2026-01-27 10:18 ` [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Alexander Kanavin
@ 2026-01-27 10:28 ` Antonin Godard
  2026-01-27 10:35 ` Alexander Kanavin
  6 siblings, 0 replies; 22+ messages in thread
From: Antonin Godard @ 2026-01-27 10:28 UTC (permalink / raw)
  To: daiane.angolini, bitbake-devel; +Cc: docs

Hi,

On Mon Jan 26, 2026 at 11:27 PM CET, Daiane Angolini via lists.yoctoproject.org wrote:
> Change some terms to use more specific wording:
>
>   Generic Configuration  -> BitBake Setup Template
>   Specific Configuration -> BitBake Setup Instance


I think we agreed on naming those:

BitBake Setup Configuration Template
BitBake Setup Configuration Instance

?

Once again, I think it's important that those two terms refer to the JSON files.
I think adding "configuration" makes it clearer, especially for the "instance".

Also not sure about prefixing it with "Bitbake Setup". In your book you can
always prefix "Configuration Template/Instance" with "Bitbake Setup", but I
think in this document it clear that's it's related to bitbake-setup.

>   nested configurations  -> Variant
>
> Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
> ---
>  .../bitbake-user-manual-environment-setup.rst | 88 +++++++++----------
>  1 file changed, 44 insertions(+), 44 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> index 3b6a73fd8..824b01ffb 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -41,8 +41,8 @@ Quick Start
>        $ ./bitbake/bin/bitbake-setup init
>  
>     This command will ask you to choose which configurations to use available as
> -   part of the default BitBake :term:`generic configurations <generic
> -   Configuration>`.
> +   part of the default BitBake :term:`BitBake Setup Templates <BitBake Setup
> +   Template>`.
>  
>     .. note::
>  
> @@ -73,8 +73,8 @@ Quick Start
>  
>        The name of the directory will vary depending on the choices.
>  
> -   -  ``config/``: holds the :term:`Specific Configuration`, which embeds the
> -      :term:`Generic Configuration` (first choice of the :ref:`ref-bbsetup-command-init` command)
> +   -  ``config/``: holds the :term:`BitBake Setup Instance`, which embeds the
> +      :term:`BitBake Setup Template` (first choice of the :ref:`ref-bbsetup-command-init` command)
>        and the choices made during the initialization.
>  
>     -  ``build/``: the :term:`BitBake Build` directory, where BitBake stores
> @@ -145,12 +145,12 @@ The "Top Directory" and "Setup" directories are defined as follows:
>     :term:`Setup`
>        A Setup is the result of the :ref:`ref-bbsetup-command-init`
>        command, which creates a :term:`Setup` directory. It is constructed from a
> -      :term:`Generic Configuration` and choices made during the ``init`` command.
> +      :term:`BitBake Setup Template` and choices made during the ``init`` command.
>  
>        It contains at least:
>  
>        -  A :term:`BitBake Build` (``build/`` directory).
> -      -  A :term:`Specific Configuration` (``config/`` directory).
> +      -  A :term:`BitBake Setup Instance` (``config/`` directory).
>        -  Sources such as :ref:`layers
>           <bitbake-user-manual/bitbake-user-manual-intro:Layers>` or other
>           repositories managed by ``bitbake-setup`` (``layers/`` directory).
> @@ -173,8 +173,8 @@ The following components are involved to create the content of these directories
>        Build` constitute the :ref:`BitBake configuration
>        <bitbake-user-manual/bitbake-user-manual-intro:Configuration Files>`.
>  
> -   :term:`Generic Configuration`
> -      A Generic Configuration is a file in JSON format containing a template to
> +   :term:`BitBake Setup Template`
> +      A BitBake Setup Template is a file in JSON format containing a template to
>        create a :term:`Setup`. These files are used during the :ref:`ref-bbsetup-command-init`
>        command as a starting point to configure the :term:`Setup`. When the
>        command runs, the user may be prompted with choices to further specify the
> @@ -183,42 +183,42 @@ The following components are involved to create the content of these directories
>        It is also possible to specify the choices on the command line for a
>        completely non-interactive initialization.
>  
> -      :term:`Generic Configuration` files are stored in :term:`registries
> +      :term:`BitBake Setup Template` files are stored in :term:`registries
>        <Registry>`, and can be listed with the :ref:`ref-bbsetup-command-list`
>        command.
>  
> -      :term:`Generic Configuration` files must end with the ``.conf.json``
> +      :term:`BitBake Setup Template` files must end with the ``.conf.json``
>        suffix for ``bitbake-setup`` to locate them.
>  
>        .. note::
>  
> -         The default :term:`Generic Configurations <Generic Configuration>` are
> +         The default :term:`BitBake Setup Templates <BitBake Setup Template>` are
>           located in the BitBake repository in a local registry. the
>           ``default-registry/`` directory. This can be modified with the
>           :ref:`ref-bbsetup-setting-registry` setting.
>  
>        :ref:`ref-bbsetup-command-status` will tell if a :term:`Setup`
> -      is in sync with the :term:`Generic Configuration` it was constructed from
> +      is in sync with the :term:`BitBake Setup Template` it was constructed from
>        (typically: layer updates).
>  
>        :ref:`ref-bbsetup-command-update` will bring a :term:`Setup`
> -      in sync with its :term:`Generic Configuration`.
> +      in sync with its :term:`BitBake Setup Template`.
>  
> -   :term:`Specific Configuration`
> -      The :term:`Specific Configuration` is stored in the ``config/`` directory
> -      in a :term:`Setup`. It embeds the :term:`Generic Configuration` and the
> +   :term:`BitBake Setup Instance`
> +      The :term:`BitBake Setup Instance` is stored in the ``config/`` directory
> +      in a :term:`Setup`. It embeds the :term:`BitBake Setup Template` and the
>        choices made during the initialization.
>  
> -      It is also a Git repository, that contains a history of the specific
> -      configuration and updates made to it via :ref:`ref-bbsetup-command-update`.
> +      It is also a Git repository, that contains a history of the setup instance
> +      and updates made to it via :ref:`ref-bbsetup-command-update`.
>  
>     :term:`Registry`
> -      A configuration registry is a place where one or more :term:`Generic
> -      Configurations <Generic Configuration>` are stored.
> +      A configuration registry is a place where one or more :term:`BitBake
> +      Setup Templates <BitBake Setup Template>` are stored.
>  
>        The directory structure of the registry can be any: ``bitbake-setup``
>        recursively find files ending with ``.conf.json`` and consider it a
> -      :term:`Generic Configuration`.
> +      :term:`BitBake Setup Template`.
>  
>        The registry location is configured through the
>        :ref:`ref-bbsetup-setting-registry` setting. This location can be the URL to
> @@ -279,7 +279,7 @@ The ``bitbake-setup init`` sub-command helps initializing a :term:`Setup`.
>  
>  This command can be run without any arguments to prompt the user with
>  configuration options to choose from. These configuration options are taken from
> -the input :term:`Generic Configuration` files in the :term:`registry`.
> +the input :term:`BitBake Setup Template` files in the :term:`registry`.
>  
>  .. note::
>  
> @@ -288,9 +288,9 @@ the input :term:`Generic Configuration` files in the :term:`registry`.
>  
>  Otherwise, the first argument to :ref:`ref-bbsetup-command-init` can be:
>  
> --  A generic configuration ID in the registry.
> --  A path to a generic configuration file on a local disk.
> --  An HTTP URI to the generic configuration file.
> +-  A BitBake Setup Template ID in the registry.
> +-  A path to a BitBake Setup Template file on a local disk.
> +-  An HTTP URI to the BitBake Setup Template file.
>  
>  The choices made during the bare ``bitbake-setup init`` command can also be
>  passed directly on the command-line, for example::
> @@ -331,7 +331,7 @@ In addition, the command can take the following arguments:
>  ``bitbake-setup init`` Examples
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> --  This example prompts the user to choose a :term:`Generic Configuration` from
> +-  This example prompts the user to choose a :term:`BitBake Setup Template` from
>     a custom registry:
>  
>     .. code-block:: shell
> @@ -340,7 +340,7 @@ In addition, the command can take the following arguments:
>            --setting default registry 'git://example.com/bitbake-setup-configurations.git;protocol=https;branch=main;rev=main' \
>            init
>  
> --  This example takes a :term:`Generic Configuration` from a remote location
> +-  This example takes a :term:`BitBake Setup Template` from a remote location
>     (here, one of the default configuration in BitBake):
>  
>     .. code-block:: shell
> @@ -351,7 +351,7 @@ In addition, the command can take the following arguments:
>  
>     -  A custom :ref:`ref-bbsetup-setting-top-dir-prefix` and :ref:`ref-bbsetup-setting-top-dir-name`
>     -  A :term:`source override`, and additionally overriding openembedded-core with a locally managed directory.
> -   -  A standalone :term:`generic configuration` file.
> +   -  A standalone :term:`BitBake Setup Template` file.
>     -  Choices passed on the command-line, applied non-interactively.
>  
>     .. code-block:: shell
> @@ -371,8 +371,8 @@ In addition, the command can take the following arguments:
>  ``bitbake-setup list``
>  ----------------------
>  
> -The ``bitbake-setup list`` sub-command lists the available :term:`generic
> -configurations <generic configuration>` in the current :term:`registry`.
> +The ``bitbake-setup list`` sub-command lists the available :term:`BitBake Setup
> +Templates <BitBake Setup Template>` in the current :term:`registry`.
>  
>  In addition, the command can take the following arguments:
>  
> @@ -388,8 +388,8 @@ In addition, the command can take the following arguments:
>  ------------------------
>  
>  The ``bitbake-setup status`` sub-command shows the status of a
> -:term:`Setup`. Any differences between the local copy of the :term:`generic
> -configuration` and the upstream one are printed on the console.
> +:term:`Setup`. Any differences between the local copy of the :term:`BitBake Setup
> +Template` and the upstream one are printed on the console.
>  
>  If the BitBake environment is sourced and ready to build, the ``bitbake-setup
>  status`` command (without any arguments) will show the status of the current
> @@ -407,7 +407,7 @@ In addition, the command can take the following arguments:
>  ------------------------
>  
>  The ``bitbake-setup update`` sub-command updates a :term:`Setup` to sync with
> -the latest changes from a :term:`generic configuration` it was constructed from.
> +the latest changes from the :term:`BitBake Setup Template` it was constructed from.
>  The :ref:`ref-bbsetup-command-status` command can be used to show the current
>  status of the :term:`Setup` before updating it.
>  
> @@ -617,16 +617,16 @@ manner.
>  
>  The :ref:`ref-bbsetup-setting-use-full-setup-dir-name` setting, if set to ``yes``
>  will override the suggestions for the :term:`Setup` directory name made by
> -``setup-dir-name`` entries in :term:`Generic Configuration` files. This
> +``setup-dir-name`` entries in :term:`BitBake Setup Template` files. This
>  will make the directory names longer, but fully specific: they will contain
>  all selections made during initialization.
>  
>  .. _ref-bbsetup-section-config-reference:
>  
> -Generic Configuration Files Reference
> -=====================================
> +BitBake Setup Template Files Reference
> +======================================

I think this is missing some modifications below?

e.g:

"""
-  ``bitbake-setup`` (**required**): contains a list of configurations.
"""

can be turned into

"""
-  ``bitbake-setup`` (**required**): contains a list of :term:`Variants
   <Variant>`.
"""

Antonin

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



^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [docs][PATCH 1/5] doc: change some terminology around bitbake-setup
  2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
                   ` (5 preceding siblings ...)
  2026-01-27 10:28 ` Antonin Godard
@ 2026-01-27 10:35 ` Alexander Kanavin
  6 siblings, 0 replies; 22+ messages in thread
From: Alexander Kanavin @ 2026-01-27 10:35 UTC (permalink / raw)
  To: daiane.angolini; +Cc: bitbake-devel, docs

On Mon, 26 Jan 2026 at 23:28, Daiane Angolini via
lists.yoctoproject.org
<daiane.angolini=foundries.io@lists.yoctoproject.org> wrote:

> -   -  ``configurations``: Configurations can recursively contain as many nested
> -      configurations as needed. This will create more choices when running the
> +   -  ``configurations``: Configurations can recursively contain as many
> +      variants as needed. This will create more choices when running the
>        :ref:`ref-bbsetup-command-init` command.

This is describing the format of the json file, and it should be
conveying that 'configurations' are recursive: they can contain nested
'configurations' in their values.

Configuration variants come into play when the tool has processed the
template, and made a flat list that can be presented to users.

Alex


^ permalink raw reply	[flat|nested] 22+ messages in thread

end of thread, other threads:[~2026-01-27 18:17 UTC | newest]

Thread overview: 22+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-01-26 22:27 [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Daiane Angolini
2026-01-26 22:27 ` [docs][PATCH 2/5] bitbake-setup: Change the output to match the terminology in the docs Daiane Angolini
2026-01-27 10:29   ` Antonin Godard
2026-01-27 10:38     ` Alexander Kanavin
2026-01-27 13:21       ` Daiane Angolini
2026-01-27 17:45         ` Alexander Kanavin
2026-01-27 18:17           ` Daiane Angolini
2026-01-26 22:27 ` [docs][PATCH 3/5] docs: Fix leading text for bitbake-setup init Daiane Angolini
2026-01-27 10:29   ` Antonin Godard
2026-01-27 10:43     ` Alexander Kanavin
2026-01-26 22:27 ` [docs][PATCH 4/5] doc: Add the term Variant Daiane Angolini
2026-01-27 10:28   ` Antonin Godard
2026-01-27 10:46     ` Alexander Kanavin
2026-01-26 22:27 ` [docs][PATCH 5/5] docs: Fix sources as required Daiane Angolini
2026-01-27 10:28   ` [bitbake-devel] " Antonin Godard
2026-01-27 10:50     ` Alexander Kanavin
2026-01-27 13:27       ` Daiane Angolini
2026-01-27 17:46         ` Alexander Kanavin
2026-01-27 18:06           ` Daiane Angolini
2026-01-27 10:18 ` [docs][PATCH 1/5] doc: change some terminology around bitbake-setup Alexander Kanavin
2026-01-27 10:28 ` Antonin Godard
2026-01-27 10:35 ` Alexander Kanavin

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.