[v3,2/2] Add bitbake-setup documentation

Add documentation for bitbake-setup. This is split in 6 sections,
including a quick start guide, terminology and reference.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 .../bitbake-user-manual-environment-setup.rst      | 822 +++++++++++++++++++++
 doc/index.rst                                      |   1 +
 2 files changed, 823 insertions(+)

On Fri, 2025-11-07 at 12:16 +0100, Antonin Godard via
lists.yoctoproject.org wrote:
> Add documentation for bitbake-setup. This is split in 6 sections,
> including a quick start guide, terminology and reference.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>  .../bitbake-user-manual-environment-setup.rst      | 822
> +++++++++++++++++++++
>  doc/index.rst                                      |   1 +
>  2 files changed, 823 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
> new file mode 100644
> index 0000000000..66c0b0fa68
> --- /dev/null
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-
> setup.rst
> @@ -0,0 +1,822 @@
> +.. SPDX-License-Identifier: CC-BY-2.5
> +
> +=============================================
> +Setting Up The Environment With bitbake-setup
> +=============================================
> +
> +|
> +
> +Setting up layers and configuring builds can be done with the
> +``bitbake-setup`` tool. This tool acts as a top-level utility which
> can perform
> +the following tasks:
> +
> +-  Parse a JSON configuration file that describes what layers and
> which snippets
> +   of configuration to use.
> +
> +-  Clone the layers onto the versions specified in the configuration
> file.
> +
> +-  Create and setup a directory ready for building what is specified
> in
> +   configuration files.
> +
> +-  Behave according to global or per-project settings.
> +
> +-  Synchronize with upstream configuration changes.
> +
> +Quick Start
> +===========
> +
> +#. ``bitbake-setup`` is part of the BitBake repository under
> +   ``./bin/bitbake-setup``. To start, run:

This is based on the assumption that everybody knows how to get
BitBake, but that's probably not the case. For many users, it was part
of Poky for a decade, which is now gone. There should be at least a
link to https://git.openembedded.org/bitbake and a hint that git clone
is used to get it.

From an OE-Core developer's perspective, it might be self-explanatory
that BitBake is a separate Git repository which can be cloned and
executed without any dependencies to fancy Python modules. It's also
obvious why we need BitBake (the fetcher) to fetch BitBake.
But for some users this might looks a bit strange. Why not pip? Why do
I need BitBake if there is now bitbake-setup to get BitBake setups to
my machine? To which path should the bitbake repo be cloned?

Regards,
Adrian

> +
> +   .. code-block:: shell
> +
> +      $ ./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>`.
> +
> +   .. note::
> +
> +      These default configurations are located in
> ``./bitbake/default-registry/``.
> +      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
> +   following directories::
> +
> +      ~/bitbake-builds/
> +      └── poky-master-poky-distro_poky-machine_qemux86-64/
> +          ├── build/
> +          ├── config/
> +          └── layers/
> +
> +   With:
> +
> +   -  ``~/bitbake-build``: the :term:`Top Directory`, where
> ``bitbake-setup``
> +      configures everything. This directory can be configured with
> the
> +      :ref:`ref-bbsetup-setting-top-dir-prefix` and
> +      :ref:`ref-bbsetup-setting-top-dir-name` settings.
> +
> +   -  ``poky-master-poky-distro_poky-machine_qemux86-64``: a
> :term:`Setup`
> +      directory, which holds a :term:`Setup`: a result of the
> choices made
> +      during the ``bitbake-setup init`` execution.
> +
> +      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)
> +      and the choices made during the initialization.
> +
> +   -  ``build/``: the :term:`BitBake Build` directory, where BitBake
> stores
> +      its own configuration and outputs for the builds.
> +
> +   -  ``layers/``: the directory where :ref:`layers
> +      <bitbake-user-manual/bitbake-user-manual-intro:Layers>` and
> other
> +      repositories managed by ``bitbake-setup`` are stored and
> updated.
> +
> +#. Source the ``init-build-env`` file present in the :term:`BitBake
> Build`
> +   directory:
> +
> +   .. code-block:: shell
> +
> +      $ source ./poky-master-poky-distro_poky-machine_qemux86-
> 64/build/init-build-env
> +
> +   This command will prepare your current shell with the BitBake
> environment.
> +
> +#. You can then start running ``bitbake`` in the current shell. For
> more information
> +   on how to use ``bitbake``, see the :doc:`/bitbake-user-
> manual/bitbake-user-manual-execution`
> +   section of this manual.
> +
> +Terminology
> +===========
> +
> +The ``bitbake-setup`` tool revolves around some common terms we
> define in this
> +section.
> +
> +``bitbake-setup`` works with a specific hierarchy of directories,
> that can be
> +represented as follows::
> +
> +   Top Directory
> +   ├── Setup 1
> +   │   ├── build/
> +   │   ├── config/
> +   │   └── layers/
> +   ├── Setup 2
> +   │   ├── build/
> +   │   ├── config/
> +   │   └── layers/
> +   ...
> +
> +The "Top Directory" and "Setup" directories are defined as follows:
> +
> +.. glossary::
> +   :term:`Top Directory`
> +      The top directory is the working directory of ``bitbake-
> setup``, where its
> +      outputs end-up (unless otherwise configured by
> :term:`settings` such as
> +      :ref:`ref-bbsetup-setting-dl-dir`).
> +
> +      The location of this directory can be changed with the
> +      :ref:`ref-bbsetup-setting-top-dir-prefix` and
> +      :ref:`ref-bbsetup-setting-top-dir-name` settings.
> +
> +      The top directory contains one or more :term:`Setup`
> directories, each of
> +      them containing a :term:`Setup`.
> +
> +   :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.
> +
> +      It contains at least:
> +
> +      -  A :term:`BitBake Build` (``build/`` directory).
> +      -  A :term:`Specific Configuration` (``config/`` directory).
> +      -  Sources such as :ref:`layers
> +         <bitbake-user-manual/bitbake-user-manual-intro:Layers>` or
> other
> +         repositories managed by ``bitbake-setup`` (``layers/``
> directory).
> +
> +The following components are involved to create the content of these
> directories:
> +
> +.. glossary::
> +   :term:`BitBake Build`
> +      A BitBake Build is a sub-tree inside a :term:`Setup` that
> BitBake itself
> +      operates on. The files in the ``conf/`` directory of a
> :term:`BitBake
> +      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
> +      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
> +      :term:`Setup` to create.
> +
> +      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
> +      <Registry>`, and can be listed with the :ref:`ref-bbsetup-
> command-list`
> +      command.
> +
> +      :term:`Generic Configuration` files must end with the
> ``.conf.json``
> +      suffix for ``bitbake-setup`` to locate them.
> +
> +      .. note::
> +
> +         The default :term:`Generic Configurations <Generic
> Configuration>` 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
> +      (typically: layer updates).
> +
> +      :ref:`ref-bbsetup-command-update` will bring a :term:`Setup`
> +      in sync with its :term:`Generic Configuration`.
> +
> +   :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
> +      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`.
> +
> +   :term:`Registry`
> +      A configuration registry is a place where one or more
> :term:`Generic
> +      Configurations <Generic Configuration>` 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`.
> +
> +      The registry location is configured through the
> +      :ref:`ref-bbsetup-setting-registry` setting. This location can
> be the URL to
> +      a Git repository, a local directory, or any URI supported by
> the BitBake
> +      fetcher (see the :doc:`/bitbake-user-manual/bitbake-user-
> manual-fetching`
> +      section for more information on fetchers).
> +
> +   :term:`Settings`
> +      Settings are operational parameters that are global to all
> builds under a
> +      :term:`Top Directory`, stored in a ``settings.conf`` file. For
> example,
> +      this could be the location of the configuration registry, or
> where the
> +      BitBake fetcher should store the downloads.
> +
> +      There are also global settings, common to all top directories
> that are
> +      stored in ``~/.config/bitbake-setup/settings.conf``.
> +
> +      See the :ref:`bitbake-user-manual/bitbake-user-manual-
> environment-setup:Settings`
> +      section to see the supported settings and where they can be
> stored.
> +
> +   :term:`Source Override`
> +      A source override is a JSON file that can be used to modify
> revisions and
> +      origins of layers or other sources that need to be checked out
> into a
> +      :term:`Setup` (in the ``layers/`` directory). It can be useful
> for example
> +      when the master branches need to be changed to master-next for
> the purpose
> +      of testing, or to set up a CI pipeline that tests code in a
> pull request
> +      coming from a developer's repository and branch.
> +
> +      Such a file is specified with a command-line option to
> +      :ref:`ref-bbsetup-command-init`.
> +
> +      See the :ref:`ref-bbsetup-source-overrides` section for more
> information on
> +      the format of these files.
> +
> +The ``bitbake-setup`` command
> +=============================
> +
> +The ``bitbake-setup`` program has general options and sub-commands.
> These can be
> +obtained using ``bitbake-setup --help``.
> +
> +The general options, common to all commands, are:
> +
> +-  ``-h`` or ``--help``: Show the help message and exit.
> +-  ``-d`` or ``--debug``: Enable debug outputs.
> +-  ``-q`` or ``--quiet``: Print only errors.
> +-  ``--color``: Colorize output (where COLOR is auto, always,
> never).
> +-  ``--no-network``: Do not check whether configuration repositories
> and layer
> +   repositories have been updated; use only the local cache.
> +-  ``--global-settings``: Path to the global settings file.
> +-  ``--setting``: Modify a setting (for this bitbake-setup
> invocation only).
> +   For example ``--setting default top-dir-prefix /path/to/top-
> dir``.
> +
> +.. _ref-bbsetup-command-init:
> +
> +``bitbake-setup init``
> +----------------------
> +
> +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`.
> +
> +.. note::
> +
> +   The registry location can be set with the :ref:`ref-bbsetup-
> setting-registry`
> +   setting and the :ref:`ref-bbsetup-command-settings` command.
> +
> +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.
> +
> +The choices made during the bare ``bitbake-setup init`` command can
> also be
> +passed directly on the command-line, for example::
> +
> +   bitbake-setup init <generic config> poky distro/poky-tiny ...
> +
> +``bitbake-setup`` will stop and ask to make a choice if the above
> command does
> +not contain all of the required configurations to complete the
> sequence of
> +choices.
> +
> +In addition, the command can take the following arguments:
> +
> +-  ``--non-interactive``: can be used to create :term:`Setups
> <Setup>`
> +   without interactions from the user. The command will fail if not
> all the
> +   required choices are provided in the command.
> +
> +-  ``--source-overrides``: can be used to pass one or more
> +   :ref:`source override <ref-bbsetup-source-overrides>`. See the
> +   :ref:`ref-bbsetup-source-overrides` section.
> +
> +-  ``--setup-dir-name``: can be used to configure the name of the
> :term:`Setup`
> +   directory.
> +
> +-  ``--skip-selection``: can be used to skip some of the choices
> +   (which may result in an incomplete :term:`Setup`!)
> +
> +``bitbake-setup init`` Examples
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +-  This example prompts the user to choose a :term:`Generic
> Configuration` from
> +   a custom registry:
> +
> +   .. code-block:: shell
> +
> +      $ ./bitbake/bin/bitbake-setup \
> +          --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
> +   (here, one of the default configuration in BitBake):
> +
> +   .. code-block:: shell
> +
> +      $ ./bitbake/bin/bitbake-setup init
> https://git.openembedded.org/bitbake/plain/default-registry/configurations/oe-nodistro.conf.json
> +
> +-  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`.
> +   -  A standalone :term:`generic configuration` file.
> +   -  Choices passed on the command-line, applied non-interactively.
> +
> +   .. code-block:: shell
> +
> +      $ ./bitbake/bin/bitbake-setup \
> +          --setting default top-dir-prefix /work/bitbake-setup \
> +          --setting default top-dir-name custom-project \
> +          init \
> +          --non-interactive \
> +          --source-overrides develop-branch.json \
> +          ./gadget_master.conf.json \
> +          gadget distro/gadget machine/gadget
> +
> +.. _ref-bbsetup-command-list:
> +
> +``bitbake-setup list``
> +----------------------
> +
> +The ``bitbake-setup list`` sub-command lists the available
> :term:`generic
> +configurations <generic configuration>` in the current
> :term:`registry`.
> +
> +In addition, the command can take the following arguments:
> +
> +-  ``--with-expired``: list the expired configuration (e.g. older
> Yocto releases
> +   that have reached their End-Of-Life dates).
> +
> +-  ``--write-json``: write the configurations into a JSON file so
> they can be
> +   programmatically processed.
> +
> +.. _ref-bbsetup-command-status:
> +
> +``bitbake-setup status``
> +------------------------
> +
> +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.
> +
> +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
> +:term:`Setup`.
> +
> +In addition, the command can take the following arguments:
> +
> +-  ``--setup-dir``: path to the :term:`Setup` to check to status
> for. Not
> +   required if the command is invoked from an initialized BitBake
> environment
> +   that contains :term:`BBPATH`.
> +
> +.. _ref-bbsetup-command-update:
> +
> +``bitbake-setup update``
> +------------------------
> +
> +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 :ref:`ref-bbsetup-command-status` command can be used to show
> the current
> +status of the :term:`Setup` before updating it.
> +
> +In addition, the command can take the following arguments:
> +
> +-  ``--setup-dir``: path to the :term:`Setup` to update. Not
> required if the
> +   command is invoked from an initialized BitBake environment that
> contains
> +   :term:`BBPATH`.
> +
> +.. _ref-bbsetup-command-install-buildtools:
> +
> +``bitbake-setup install-buildtools``
> +------------------------------------
> +
> +The ``bitbake-setup install-buildtools`` sub-command installs and
> extracts a
> +buildtools tarball into the specified :term:`Setup`.
> +
> +After completion, help is printed to help the user on how to use the
> extracted
> +tarball.
> +
> +.. note::
> +
> +   The purpose of the Buildtools tarball is to provide tools needed
> to run
> +   BitBake on build machines where such tools cannot be easily
> obtained from the
> +   host Linux distribution (for example on older distribution
> versions that do
> +   not contain a recent enough GCC compiler or Python interpreter,
> or machines
> +   where the user running BitBake cannot easily install additional
> software into
> +   the system). This command requires that the OpenEmbedded-core
> layer is
> +   present in the BitBake configuration.
> +
> +   See
> https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-git-tar-python-make-and-gcc-versions
> +   for more information.
> +
> +In addition, the command can take the following arguments:
> +
> +-  ``--force``: force the re-installation of the tarball.
> +
> +-  ``--setup-dir``: path to the :term:`Setup` to check to status
> for. Not
> +   required if :term:`BBPATH` is already configured.
> +
> +.. _ref-bbsetup-command-settings:
> +
> +``bitbake-setup settings``
> +--------------------------
> +
> +The ``bitbake-setup settings`` sub-command helps modifying the
> settings of
> +``bitbake-setup``. This sub-command has sub-commands itself:
> +
> +-  ``bitbake-setup settings list`` lists the current settings and
> their value.
> +-  ``bitbake-setup settings set`` sets a setting.
> +-  ``bitbake-setup settings unset`` removes a setting.
> +
> +Settings must be set with a section and a value, for example::
> +
> +   bitbake-setup setting set default top-dir-name bitbake-builds
> +
> +Will set the value of ``top-dir-name`` in the ``default`` section to
> +"bitbake-builds".
> +
> +In addition, the command can take the following arguments:
> +
> +-  ``--global``: write to the global settings
> +   (``~/.config/bitbake-setup/settings.conf``) instead of the
> :term:`Top
> +   Directory` settings.
> +
> +See the :ref:`bitbake-user-manual/bitbake-user-manual-environment-
> setup:Settings`
> +section to see the supported settings.
> +
> +.. note::
> +
> +   The supported setting listed in the
> +   :ref:`bitbake-user-manual/bitbake-user-manual-environment-
> setup:Settings`
> +   section are only affected when set in the ``default`` section.
> +
> +Settings
> +========
> +
> +The settings allow configuring ``bitbake-setup``. Settings are
> stored in a file
> +named ``settings.conf``, in :wikipedia:`INI <INI_file>` format.
> +
> +There are multiple locations for storing settings. Settings in
> different
> +locations can override each other, but the final value of a setting
> is computed
> +from reading the files in this order:
> +
> +#. Global settings file: ``~/.config/bitbake-setup/settings.conf``.
> +
> +#. Local settings file, taken from a ``settings.conf`` file in the
> :term:`Top
> +   Directory`.
> +
> +#. Command-line settings, passed with the ``--setting`` argument.
> +
> +A valid settings file would for example be:
> +
> +.. code-block:: ini
> +
> +   [default]
> +   top-dir-prefix = /path/to/workspace
> +   top-dir-name = bitbake-builds
> +   registry = /path/to/bitbake/default-registry
> +   dl-dir = /path/to/bitbake-setup-downloads
> +
> +Settings and their values can be listed and modified with the
> ``bitbake-setup
> +settings`` command. See the :ref:`ref-bbsetup-command-settings`
> section for
> +more information.
> +
> +Below are the available settings.
> +
> +.. _ref-bbsetup-setting-top-dir-prefix:
> +
> +``top-dir-prefix``
> +------------------
> +
> +The :ref:`ref-bbsetup-setting-top-dir-prefix` setting helps
> configuring the
> +leftmost part of the path to the :term:`Top Directory`.
> +
> +For example, with:
> +
> +.. code-block:: ini
> +
> +   [default]
> +   top-dir-prefix = /path/to/workspace
> +
> +The :term:`top directory` would be ``/path/to/workspace/<top-dir-
> name>`` with
> +the ``<top-dir-name>`` corresponding to the :ref:`ref-bbsetup-
> setting-top-dir-name`
> +setting.
> +
> +This is most useful to customize on systems where the default
> location of the
> +:term:`Top Directory` (``~/bitbake-builds``) is not suitable, and
> there is a
> +dedicated directory for builds somewhere else.
> +
> +.. _ref-bbsetup-setting-top-dir-name:
> +
> +``top-dir-name``
> +----------------
> +
> +The :ref:`ref-bbsetup-setting-top-dir-name` setting helps
> configuring the
> +rightmost part of the path to the :term:`Top Directory`.
> +
> +For example, with:
> +
> +.. code-block:: ini
> +
> +   [default]
> +   top-dir-name = builds
> +
> +The :term:`top directory` would be ``<top-dir-prefix>/builds`` with
> +the ``<top-dir-prefix>`` corresponding to the :ref:`ref-bbsetup-
> setting-top-dir-prefix`
> +setting.
> +
> +.. _ref-bbsetup-setting-registry:
> +
> +``registry``
> +------------
> +
> +The :ref:`ref-bbsetup-setting-registry` setting sets the URI
> location of the
> +registry. This URI can be any URI supported by the BitBake fetcher.
> +
> +A local registry would be configured as follows:
> +
> +.. code-block:: ini
> +
> +   [default]
> +   registry = /path/to/registry
> +
> +When using another fetcher, it must be specified in the URI scheme.
> For example:
> +
> +.. code-block:: ini
> +
> +   [default]
> +   registry = git://example.com/bitbake-setup-
> configurations;protocol=https;branch=master;rev=master
> +
> +This would fetch the remote configurations from a remote Git remote
> repository,
> +on the ``master`` branch.
> +
> +See the :doc:`/bitbake-user-manual/bitbake-user-manual-fetching`
> section for more
> +information on BitBake fetchers.
> +
> +.. _ref-bbsetup-setting-dl-dir:
> +
> +``dl-dir``
> +----------
> +
> +The :ref:`ref-bbsetup-setting-dl-dir` setting sets the location of
> the download
> +cache that ``bitbake-setup`` will configure for the purpose of
> downloading
> +configuration repositories, layers and other sources using BitBake
> fetchers.
> +Please see :doc:`/bitbake-user-manual/bitbake-user-manual-fetching`
> and the
> +:term:`DL_DIR` variable for more information.
> +
> +The location can be set such that it is shared with :term:`DL_DIR`
> specified by
> +BitBake builds, so that there is a single directory containing a
> copy of
> +everything needed to set up and run a BitBake build offline in a
> reproducible
> +manner.
> +
> +.. _ref-bbsetup-section-config-reference:
> +
> +Generic Configuration Files Reference
> +=====================================
> +
> +:term:`Generic Configurations <Generic Configuration>` 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
> +:term:`Registry`. They can also be standalone files directly passed
> to the
> +:ref:`ref-bbsetup-command-init` command:
> +
> +.. code-block:: shell
> +
> +   $ bitbake-setup init /path/to/config.conf.json
> +
> +They contain the following sections:
> +
> +-  ``version`` (**required**): version of the configuration file.
> +
> +   Example:
> +
> +   .. code-block:: json
> +      :force:
> +
> +      {
> +          "version": "1.0"
> +      }
> +
> +-  ``description`` (**required**): the description of the
> configuration.
> +
> +   Example:
> +
> +   .. code-block:: json
> +      :force:
> +
> +      {
> +          "description": "OpenEmbedded - 'nodistro' basic
> configuration"
> +      }
> +
> +-  ``sources`` (*optional*): Git repositories to fetch.
> +
> +   Example:
> +
> +   .. code-block:: json
> +      :force:
> +
> +      {
> +         "sources": {
> +             "bitbake": {
> +                 "git-remote": {
> +                     "remotes": {
> +                         "origin": {
> +                             "uri":
> "git://git.openembedded.org/bitbake;protocol=https"
> +                         }
> +                     },
> +                     "branch": "master",
> +                     "rev": "master"
> +                 },
> +                 "path": "bitbake"
> +             }
> +         }
> +      }
> +
> +   Sources can be specified with the following options:
> +
> +   -  ``uri`` (**required**): a URI that follows the BitBake Git
> fetcher syntax.
> +      See the :doc:`/bitbake-user-manual/bitbake-user-manual-
> fetching` section
> +      for more information on the Git fetcher.
> +
> +   -  ``rev`` (**required**): the revision to checkout. Can be the
> name of the
> +      branch to checkout on the latest revision of the specified
> ``branch``.
> +
> +      If the value is the branch name, ``bitbake-setup`` will check
> out the
> +      latest revision on that branch, and keep it updated when using
> the
> +      :ref:`ref-bbsetup-command-update` command.
> +
> +   -  ``branch`` (**required**): the Git branch, used to check that
> the
> +      specified ``rev`` is indeed on that branch.
> +
> +   -  ``path`` is where the source is extracted.
> +
> +-  ``expires`` (*optional*): Expiration date of the configuration.
> This date
> +   should be in :wikipedia:`ISO 8601 <ISO_8601>` format (``YYYY-MM-
> DDTHH:MM:SS``).
> +
> +-  ``bitbake-setup`` (**required**): contains a list of
> configurations.
> +
> +   Example:
> +
> +   .. code-block:: json
> +
> +      {
> +         "bitbake-setup": {
> +            "configurations": [
> +            {
> +                "bb-layers": ["openembedded-core/meta","meta-
> yocto/meta-yocto-bsp","meta-yocto/meta-poky"],
> +                "bb-env-passthrough-additions":
> ["DL_DIR","SSTATE_DIR"],
> +                "oe-fragments-one-of": {
> +                    "machine": {
> +                        "description": "Target machines",
> +                        "options" : ["machine/qemux86-64",
> "machine/qemuarm64", "machine/qemuriscv64", "machine/genericarm64",
> "machine/genericx86-64"]
> +                    },
> +                    "distro": {
> +                        "description": "Distribution configuration
> variants",
> +                        "options" : ["distro/poky", "distro/poky-
> altcfg", "distro/poky-tiny"]
> +                    }
> +                },
> +                "configurations": [
> +                {
> +                    "name": "poky",
> +                    "description": "Poky - The Yocto Project testing
> distribution"
> +                },
> +                {
> +                    "name": "poky-with-sstate",
> +                    "description": "Poky - The Yocto Project testing
> distribution with internet sstate acceleration. Use with caution as
> it requires a completely robust local network with sufficient
> bandwidth.",
> +                    "oe-fragments": ["core/yocto/sstate-mirror-cdn"]
> +                }
> +                ]
> +            }
> +            ]
> +         }
> +      }
> +
> +   Configurations can be specified with the following options:
> +
> +   -  ``name`` (**required**): the name of this configuration
> snippet. This is
> +      what is prompted during the :ref:`ref-bbsetup-command-init`
> command
> +      execution.
> +
> +   -  ``description`` (**required**): the description of this
> configuration
> +      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
> +      :ref:`ref-bbsetup-command-init` command.
> +
> +      The purpose of such nesting is to be able to scale the
> configurations, for
> +      example when there is a need to create multiple configurations
> that share
> +      some parameters (which are specified in their common parent),
> but differ
> +      between themselves in other parameters. ``bitbake-setup`` will
> assemble
> +      configuration choices by putting together information from a
> leaf
> +      configuration and all of its ancestors.
> +
> +   -  ``bb-env-passthrough-additions`` (*optional*): List of
> environment
> +      variables to include in :term:`BB_ENV_PASSTHROUGH_ADDITIONS`.
> +
> +   -  ``bb-layers`` (*optional*): List of layers to add to the
> ``bblayers.conf``
> +      file. Paths in this list are relative to the ``layers/``
> directory of a
> +      :term:`Setup`.
> +
> +      The ``bb-layers`` keyword cannot be used in conjunction with
> the
> +      ``oe-template`` option, as the ``bblayers.conf`` file comes
> from the
> +      template itself.
> +
> +   -  ``bb-layers-file-relative`` (*optional*): List of layers that
> are not
> +      managed by ``bitbake-setup`` but that need to be included as
> part of the
> +      ``bblayers.conf`` file. Paths in this list are relative to the
> +      configuration file.
> +
> +      This is useful when (one or more) configuration files and (one
> or
> +      more) layers are hosted in the same Git repository, which is
> cloned
> +      and managed independently from bitbake-setup workflows. For
> example::
> +
> +         ├── meta-myproject/
> +         └── myproject.conf.json
> +
> +      Then ``myproject.conf.json`` can contain the following to add
> +      ``meta-myproject`` to ``bblayers.conf``::
> +
> +         {
> +            ...
> +            "bb-layers-file-relative": [
> +               "meta-myproject"
> +            ],
> +            ...
> +         }
> +
> +      The ``bb-layers-file-relative`` keyword cannot be used in
> conjunction with the
> +      ``oe-template`` keyword, as the ``bblayers.conf`` file comes
> from the
> +      template itself.
> +
> +   -  ``oe-template`` (*optional*, OpenEmbedded specific):
> OpenEmbedded template
> +      to use. This cannot be used in conjunction with the
> +      ``bb-layers`` or ``bb-layers-file-relative`` keywords as it
> +      already provides a ready ``bblayers.conf`` file to use.
> +
> +      See
> https://docs.yoctoproject.org/dev-manual/custom-template-configuration-directory.html
> +      for more information of OpenEmbedded templates.
> +
> +   -  ``oe-fragments-one-of`` (*optional*, OpenEmbedded specific):
> the OpenEmbedded
> +      fragments to select as part of the build.
> +
> +      This will trigger choices to make during the
> +      :ref:`ref-bbsetup-command-init` command execution.
> +
> +      See
> https://docs.yoctoproject.org/dev/ref-manual/fragments.html for
> +      more information of OpenEmbedded configuration fragments.
> +
> +   -  ``oe-fragments`` (*optional*, OpenEmbedded specific):
> fragments to select
> +      as part of the build.
> +
> +      See
> https://docs.yoctoproject.org/dev/ref-manual/fragments.html for
> +      more information of OpenEmbedded configuration fragments.
> +
> +Generic Configuration Examples
> +------------------------------
> +
> +OpenEmbedded "nodistro" configuration for master branches:
> +
> +.. literalinclude:: ../../default-registry/configurations/oe-
> nodistro.conf.json
> +   :language: json
> +
> +Poky distribution configuration for master branches:
> +
> +.. literalinclude:: ../../default-registry/configurations/poky-
> master.conf.json
> +   :language: json
> +
> +.. _ref-bbsetup-source-overrides:
> +
> +Source Overrides
> +================
> +
> +See the definition of :term:`Source Override` in the Terminology
> section.
> +
> +These files are written in the JSON file format and are optionally
> passed to the
> +``--source-overrides`` argument of the :ref:`ref-bbsetup-command-
> init` command.
> +The ``--source-overrides`` option can be passed multiple times, in
> which case the
> +overrides are applied in the order specified in the command-line.
> +
> +Here is an example file that overrides the branch of the BitBake
> repository to
> +"master-next":
> +
> +.. code-block:: json
> +
> +   {
> +       "description": "Source override file",
> +       "sources": {
> +           "bitbake": {
> +               "git-remote": {
> +                   "branch": "master-next",
> +                   "remotes": {
> +                       "origin": {
> +                           "uri":
> "git://git.openembedded.org/bitbake;protocol=https"
> +                       }
> +                   },
> +                   "rev": "master-next"
> +               }
> +           }
> +       },
> +       "version": "1.0"
> +   }
> +
> +-  The ``version`` parameter contains the version of the used
> configuration, and
> +   should match the one of the :term:`Generic Configuration` file in
> use.
> +
> +-  The ``sources`` section contains the same options as the
> ``sources`` option
> +   of a :term:`Generic Configuration` file. See the
> +   :ref:`ref-bbsetup-section-config-reference` section for more
> information.
> diff --git a/doc/index.rst b/doc/index.rst
> index 546ef36c16..9f2a9067d3 100644
> --- a/doc/index.rst
> +++ b/doc/index.rst
> @@ -12,6 +12,7 @@ BitBake User Manual
>  
>     bitbake-user-manual/bitbake-user-manual-intro
>     bitbake-user-manual/bitbake-user-manual-execution
> +   bitbake-user-manual/bitbake-user-manual-environment-setup
>     bitbake-user-manual/bitbake-user-manual-metadata
>     bitbake-user-manual/bitbake-user-manual-ref-variables-context
>     bitbake-user-manual/bitbake-user-manual-fetching
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#8014):
> https://lists.yoctoproject.org/g/docs/message/8014
> Mute This Topic: https://lists.yoctoproject.org/mt/116168702/4454582
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe:
> https://lists.yoctoproject.org/g/docs/unsub [adrian.freihofer@gmail.com
> ]
> -=-=-=-=-=-=-=-=-=-=-=-

On Sun, 9 Nov 2025 at 16:29, Adrian Freihofer via
lists.openembedded.org
<adrian.freihofer=gmail.com@lists.openembedded.org> wrote:
> This is based on the assumption that everybody knows how to get
> BitBake, but that's probably not the case. For many users, it was part
> of Poky for a decade, which is now gone. There should be at least a
> link to https://git.openembedded.org/bitbake and a hint that git clone
> is used to get it.
>
> From an OE-Core developer's perspective, it might be self-explanatory
> that BitBake is a separate Git repository which can be cloned and
> executed without any dependencies to fancy Python modules. It's also
> obvious why we need BitBake (the fetcher) to fetch BitBake.
> But for some users this might looks a bit strange. Why not pip? Why do
> I need BitBake if there is now bitbake-setup to get BitBake setups to
> my machine? To which path should the bitbake repo be cloned?

Please trim the quotations when replying Adrian.

Otherwise, I agree, this does need a section, up front, on how to
obtain the tool. And we absolutely can and should put bitbake into
pip, once there is a release tag that has bitbake-setup in it.

I've already had one confused user [1], for whom it wasn't clear that
bitbake-setup is not tightly coupled to the yocto release it's aiming
to build, and one should default to latest bitbake master. But because
bitbake-setup is hosted in bitbake repo, that isn't immediately
obvious, so the docs should stress that too.

[1] https://www.linkedin.com/posts/michaelopdenacker_yocto-bitbake-openembedded-activity-7393585408602718208-0kUF?utm_source=share&utm_medium=member_desktop&rcm=ACoAABJHgsUBoC4rs3Cqeu3vM4cHkuvzT90KZf4

Alex