diff mbox series

[v2,09/10] doc: document fixed revisions override in bitbake-setup manual

Message ID 20260106121033.3892596-9-alex.kanavin@gmail.com
State New
Headers show
Series [v2,01/10] bitbake-setup: move the local source tests to the end | expand

Commit Message

Alexander Kanavin Jan. 6, 2026, 12:10 p.m. UTC 
From: Alexander Kanavin <alex@linutronix.de>

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
---
v2: address feedback by Antonin
---
 .../bitbake-user-manual-environment-setup.rst | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

Comments

Antonin Godard Jan. 6, 2026, 12:17 p.m. UTC | #1 
Hi,

On Tue Jan 6, 2026 at 1:10 PM CET, Alexander Kanavin via lists.openembedded.org wrote:
> From: Alexander Kanavin <alex@linutronix.de>
>
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
> v2: address feedback by Antonin
> ---
>  .../bitbake-user-manual-environment-setup.rst | 48 +++++++++++++++++++
>  1 file changed, 48 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 ec1bdeecd..fcffab812 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -938,3 +938,51 @@ Here is an example file that overrides the branch of the BitBake repository to
>  -  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.
> +
> +.. _ref-bbsetup-fixed-revisions:
> +
> +Fixed source revisions
> +======================
> +
> +:term:`Generic Configuration` 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.
> +
> +This file is named ``sources-fixed-revisions.json`` and is available in ``layers/``
> +under the :term:`Setup` directory (as well as under ``config/`` for backwards compatibility).
> +It can be used to keep record of what was checked out when using configurations that do not
> +specify exact revisions.
> +
> +Also, as it is an override file, it can be combined with the original configurations
> +to initialize a setup in a reproducible way that guarantees an exact, never-changing
> +set of revisions, by using the ``--source-overrides`` option of the
> +:ref:`ref-bbsetup-command-init` command.
> +
> +For example if the original configuration had specified only a master branch
> +for a source::
> +
> +     "bitbake": {
> +         "git-remote": {
> +             "remotes": {
> +                 "origin": {
> +                     "uri": "https://git.openembedded.org/bitbake"
> +                 }
> +             },
> +             "branch": "master",
> +             "rev": "master"
> +     }
> +
> +
> +the override will contain the exact revisions::
> +
> +     "bitbake": {
> +         "git-remote": {
> +             "remotes": {
> +                 "origin": {
> +                     "uri": "https://git.openembedded.org/bitbake"
> +                 }
> +             },
> +             "branch": "master",
> +             "rev": "720df1a53452983c1c832f624490e255cf389204"
> +     }

Looking good, thanks!

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

Antonin
diff mbox series

Patch

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 ec1bdeecd..fcffab812 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -938,3 +938,51 @@  Here is an example file that overrides the branch of the BitBake repository to
 -  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.
+
+.. _ref-bbsetup-fixed-revisions:
+
+Fixed source revisions
+======================
+
+:term:`Generic Configuration` 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.
+
+This file is named ``sources-fixed-revisions.json`` and is available in ``layers/``
+under the :term:`Setup` directory (as well as under ``config/`` for backwards compatibility).
+It can be used to keep record of what was checked out when using configurations that do not
+specify exact revisions.
+
+Also, as it is an override file, it can be combined with the original configurations
+to initialize a setup in a reproducible way that guarantees an exact, never-changing
+set of revisions, by using the ``--source-overrides`` option of the
+:ref:`ref-bbsetup-command-init` command.
+
+For example if the original configuration had specified only a master branch
+for a source::
+
+     "bitbake": {
+         "git-remote": {
+             "remotes": {
+                 "origin": {
+                     "uri": "https://git.openembedded.org/bitbake"
+                 }
+             },
+             "branch": "master",
+             "rev": "master"
+     }
+
+
+the override will contain the exact revisions::
+
+     "bitbake": {
+         "git-remote": {
+             "remotes": {
+                 "origin": {
+                     "uri": "https://git.openembedded.org/bitbake"
+                 }
+             },
+             "branch": "master",
+             "rev": "720df1a53452983c1c832f624490e255cf389204"
+     }