[2/2] bitbake-setup: write notes for generated build configs

From: Ernest Van Hoecke <ernest.vanhoecke@toradex.com>

For bb-layers configurations, bitbake-setup currently writes an empty
"conf-notes.txt". Configurations using "oe-template" get this file from
the template.

Add an optional field called "notes" to configurations that populates
this field when "bb-layers" is used instead of "oe-template".

Signed-off-by: Ernest Van Hoecke <ernest.vanhoecke@toradex.com>
---
 bin/bitbake-setup                                                 | 3 ++-
 doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst | 5 +++++
 lib/bb/tests/setup.py                                             | 4 ++++
 setup-schema/bitbake-setup.schema.json                            | 4 ++++
 4 files changed, 15 insertions(+), 1 deletion(-)

Thanks, this lgtm too.

Alex

On Fri, 29 May 2026 at 17:00, Ernest Van Hoecke via
lists.openembedded.org
<ernestvanhoecke=gmail.com@lists.openembedded.org> wrote:
>
> From: Ernest Van Hoecke <ernest.vanhoecke@toradex.com>
>
> For bb-layers configurations, bitbake-setup currently writes an empty
> "conf-notes.txt". Configurations using "oe-template" get this file from
> the template.
>
> Add an optional field called "notes" to configurations that populates
> this field when "bb-layers" is used instead of "oe-template".
>
> Signed-off-by: Ernest Van Hoecke <ernest.vanhoecke@toradex.com>
> ---
>  bin/bitbake-setup                                                 | 3 ++-
>  doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst | 5 +++++
>  lib/bb/tests/setup.py                                             | 4 ++++
>  setup-schema/bitbake-setup.schema.json                            | 4 ++++
>  4 files changed, 15 insertions(+), 1 deletion(-)
>
> diff --git a/bin/bitbake-setup b/bin/bitbake-setup
> index 220540f7f9ca..e22e5b77bde1 100755
> --- a/bin/bitbake-setup
> +++ b/bin/bitbake-setup
> @@ -301,7 +301,8 @@ def setup_bitbake_build(bitbake_config, layerdir, setupdir, thisdir, update_bb_c
>              f.write(bitbake_config["description"] + "\n")
>
>          with open(os.path.join(build_conf_dir, "conf-notes.txt"), 'w') as f:
> -            f.write("")
> +            notes = bitbake_config.get("notes")
> +            f.write(notes + "\n" if notes else "")
>
>      def _make_init_build_env(builddir, oeinitbuildenvdir):
>          builddir = os.path.realpath(builddir)
> 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 1252f22c823a..e99cf7b3415d 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -1057,6 +1057,11 @@ They contain the following sections:
>        snippet. This is what is prompted during the
>        :ref:`ref-bbsetup-command-init` command execution.
>
> +   -  ``notes`` (*optional*): additional information written to
> +      ``build/conf/conf-notes.txt`` when ``bitbake-setup`` generates the build
> +      configuration from ``bb-layers``. For ``oe-template`` configurations,
> +      this file is provided by the template.
> +
>     -  ``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.
> diff --git a/lib/bb/tests/setup.py b/lib/bb/tests/setup.py
> index 638d56d3bb32..ffe390db1bda 100644
> --- a/lib/bb/tests/setup.py
> +++ b/lib/bb/tests/setup.py
> @@ -136,6 +136,7 @@ print("BBPATH is {{}}".format(os.environ["BBPATH"]))
>              {
>                  "name": "gadget-notemplate",
>                  "description": "Gadget notemplate configuration",
> +                "notes": "Gadget notemplate notes",
>                  "bb-layers": ["layerA","layerB/meta-layer"],
>                  "oe-fragments": ["test-fragment-1"]
>              },
> @@ -249,6 +250,9 @@ print("BBPATH is {{}}".format(os.environ["BBPATH"]))
>          else:
>              with open(os.path.join(bb_conf_path, 'conf-summary.txt')) as f:
>                  self.assertIn(bitbake_config["description"], f.read())
> +            with open(os.path.join(bb_conf_path, 'conf-notes.txt')) as f:
> +                expected_notes = bitbake_config.get("notes")
> +                self.assertEqual(f.read(), expected_notes + "\n" if expected_notes else "")
>              with open(os.path.join(bb_conf_path, 'bblayers.conf')) as f:
>                  bblayers = f.read()
>                  for l in bitbake_config["bb-layers"]:
> diff --git a/setup-schema/bitbake-setup.schema.json b/setup-schema/bitbake-setup.schema.json
> index be8772db1b2d..6a39e66a0ae4 100644
> --- a/setup-schema/bitbake-setup.schema.json
> +++ b/setup-schema/bitbake-setup.schema.json
> @@ -41,6 +41,10 @@
>                                  "type": "string",
>                                  "description": "Human-readable description of the configuration"
>                              },
> +                            "notes": {
> +                                "type": "string",
> +                                "description": "Extra notes that populate conf-notes.txt when bb-layers is used"
> +                            },
>                              "bb-layers": {
>                                  "type": "array",
>                                  "description": "List of BitBake layer paths to include, relative to the layers download directory",
>
> --
> 2.43.0
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#19565): https://lists.openembedded.org/g/bitbake-devel/message/19565
> Mute This Topic: https://lists.openembedded.org/mt/119548246/1686489
> Group Owner: bitbake-devel+owner@lists.openembedded.org
> Unsubscribe: https://lists.openembedded.org/g/bitbake-devel/unsub [alex.kanavin@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>

On Fri May 29, 2026 at 5:00 PM CEST, Ernest Van Hoecke via lists.openembedded.org wrote:
> From: Ernest Van Hoecke <ernest.vanhoecke@toradex.com>
>
> For bb-layers configurations, bitbake-setup currently writes an empty
> "conf-notes.txt". Configurations using "oe-template" get this file from
> the template.
>
> Add an optional field called "notes" to configurations that populates
> this field when "bb-layers" is used instead of "oe-template".

Suggestion: call the field "conf-notes" so it matches the resulting filename?

Also, I supposed newlines must be explicitly written in the string ("\n")? Are
those properly converted, or does it need escaping of some sorts?

Thanks,
Antonin

On Mon, 1 Jun 2026 at 09:05, Antonin Godard via lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> Suggestion: call the field "conf-notes" so it matches the resulting filename?

I disagree. It's meant for general-purpose freeform notes about the
configuration; that they also get written into conf-notes.txt is an
implementation detail. It's also more consistent, as there's already
"description" which gets written into conf-summary.txt.

Alex

On Mon, Jun 01, 2026 at 09:05:17AM +0200, Antonin Godard wrote:
> On Fri May 29, 2026 at 5:00 PM CEST, Ernest Van Hoecke via lists.openembedded.org wrote:
> > From: Ernest Van Hoecke <ernest.vanhoecke@toradex.com>
> >
> > For bb-layers configurations, bitbake-setup currently writes an empty
> > "conf-notes.txt". Configurations using "oe-template" get this file from
> > the template.
> >
> > Add an optional field called "notes" to configurations that populates
> > this field when "bb-layers" is used instead of "oe-template".
> 
> Suggestion: call the field "conf-notes" so it matches the resulting filename?
> 
> Also, I supposed newlines must be explicitly written in the string ("\n")? Are
> those properly converted, or does it need escaping of some sorts?
> 
> Thanks,
> Antonin
> 

Hi Antonin,

Yes, I tested with some newlines explicitly written and this worked fine.
Since it just comes from a json string and is passed to `f.write()` I
don't believe any special escaping is necessary, just "\n" is fine.

My understanding is that the Python json library should handle this well
and converts it to a real newline in the python string.

Thanks,
Ernest

On Mon, 1 Jun 2026 at 14:53, Ernest Van Hoecke via
lists.openembedded.org
<ernestvanhoecke=gmail.com@lists.openembedded.org> wrote:

> Yes, I tested with some newlines explicitly written and this worked fine.
> Since it just comes from a json string and is passed to `f.write()` I
> don't believe any special escaping is necessary, just "\n" is fine.
>
> My understanding is that the Python json library should handle this well
> and converts it to a real newline in the python string.

I need to ask though: how practical and readable is it going to be,
when written into the json? Notes are meant as multiple paragraphs of
text, and it would be good to be able to write them that way, instead
of some specially-formatted single string.

Alex

On Mon, Jun 01, 2026 at 03:30:48PM +0200, Alexander Kanavin wrote:
> On Mon, 1 Jun 2026 at 14:53, Ernest Van Hoecke via
> lists.openembedded.org
> <ernestvanhoecke=gmail.com@lists.openembedded.org> wrote:
> 
> > Yes, I tested with some newlines explicitly written and this worked fine.
> > Since it just comes from a json string and is passed to `f.write()` I
> > don't believe any special escaping is necessary, just "\n" is fine.
> >
> > My understanding is that the Python json library should handle this well
> > and converts it to a real newline in the python string.
> 
> I need to ask though: how practical and readable is it going to be,
> when written into the json? Notes are meant as multiple paragraphs of
> text, and it would be good to be able to write them that way, instead
> of some specially-formatted single string.
> 
> Alex
>

I considered this and agree, there's no true beautiful solution here.
The description field also has this issue, granted, that's meant to be
much shorter than notes.

Since json doesn't support multiline strings, the only alternative is
making this field a list of strings and concatenating them in code. I'm
certainly open to that and can send a v2 doing it that way (it'd look
like an extra "\n".join()).
 
Ernest

On Mon, 1 Jun 2026 at 15:55, Ernest Van Hoecke
<ernestvanhoecke@gmail.com> wrote:
> I considered this and agree, there's no true beautiful solution here.
> The description field also has this issue, granted, that's meant to be
> much shorter than notes.
>
> Since json doesn't support multiline strings, the only alternative is
> making this field a list of strings and concatenating them in code. I'm
> certainly open to that and can send a v2 doing it that way (it'd look
> like an extra "\n".join()).

Yes. We're basically restricted by json's original purpose of being a
data transfer format, and not a config file format. (the "no comments"
restriction is in the same vein). It's a lot more human friendly than
xml, but still not friendly enough, by modern standards.

It's tempting to make it a reference to an external file, but this
wouldn't work well when the config is fetched with http:
$ bitbake-setup init https://my.server/some-build.conf.json
would have to also fetch the notes file.

A list of strings isn't horrible, perhaps either can be supported?

Alex