[RFC,0/3] bitbake-setup: config-driven local.conf, default target and docs

Hi all,

This RFC explores small additions to reduce project-side wrapper logic
when using bitbake-setup for machine-specific build flows.

Patch 1 allows local.conf snippets to be provided by configuration data.
Patch 2 allows a default build target to be provided by configuration
and exposed via a generated build-target helper script.
Patch 3 documents both new optional keys in the user manual.

The field names in this RFC are intentionally aligned with existing
bitbake-setup naming style and kept open for feedback:
- bb-local-conf-header
- bb-target

Goal:
- move common project policy from external wrappers into setup config
- keep setup usage closer to one-command build workflows

Before/after example (qemux86-64):

With this RFC, config can define:
- bb-target = "xxx-image-minimal-sdk"
- bb-local-conf-header = [
    "MACHINE ?= \"qemux86-64\"",
    "DISTRO ?= \"xxx\"",
    "EXTRA_IMAGECMD:ext4 = \"-O ^metadata_csum,^dir_index\""
  ]

Then a plain:
  bitbake-setup init --non-interactive qemux86-64.conf.json

is enough to:
- populate build/conf/local.conf with the configured lines
- generate setupdir/build-target for default target build

Without this RFC, projects must do extra wrapper steps for each machine,
for example:

1) Initialize setup:
   bitbake-setup init --non-interactive qemux86-64.conf.json

2) Append machine policy into local.conf (manually or via wrapper):
   echo 'MACHINE ?= "qemux86-64"' >> <setup>/build/conf/local.conf
   echo 'DISTRO ?= "xxx"' >> <setup>/build/conf/local.conf
   echo 'EXTRA_IMAGECMD:ext4 = "-O ^metadata_csum,^dir_index"' >> \
        <setup>/build/conf/local.conf

3) Source environment and build an explicit target in wrapper logic:
   . <setup>/build/init-build-env
   bitbake xxx-image-minimal-sdk

This is functional, but significantly more verbose and error-prone,
especially when scaling across many machine configs.

This is RFC because naming/schema expectations may need adjustment.

Thanks for review.

Zhangfei Gao (3):
  bitbake-setup: support bb-local-conf-header injection
  bitbake-setup: add bb-target build wrapper
  doc: document bb-local-conf-header and bb-target

 bin/bitbake-setup                                   | 34 +++++++++++++++++++++
 .../bitbake-user-manual-environment-setup.rst       | 23 ++++++++++++++
 2 files changed, 57 insertions(+)

On Fri, 20 Mar 2026 at 16:03, Zhangfei Gao via lists.openembedded.org
<zhangfei.gao=linaro.org@lists.openembedded.org> wrote:
> With this RFC, config can define:
> - bb-target = "xxx-image-minimal-sdk"
> - bb-local-conf-header = [
>     "MACHINE ?= \"qemux86-64\"",
>     "DISTRO ?= \"xxx\"",
>     "EXTRA_IMAGECMD:ext4 = \"-O ^metadata_csum,^dir_index\""
>   ]

Hello Zhangfei,

thank you for the contributions, and trying bitbake-setup for
production builds. Let me review this in two parts:

1. bitbbake-setup is explicitly designed such that it never writes any
bitbake configurations statements to local.conf, and its own config
files do not contain them either.  We want to steer people away from
'custom hacks' in local.conf, and have them use it strictly for what
it was intended for: local tweaks to standard build configurations,
for experiments or local development.

To parametrize the standard build configurations we've developed a new
mechanism called fragments, described here:
https://docs.yoctoproject.org/dev/ref-manual/fragments.html

Particularly MACHINE and DISTRO can be set with 'oe-fragments' or
'oe-fragments-one-of' as can be see in standard poky configs:
https://git.openembedded.org/bitbake/tree/default-registry/configurations/poky-master.conf.json

The EXTRA_IMAGECMD settings similarly should go to a fragment file,
that file should go to a layer, and the fragment file must contain a
summary and description of what it does and why. Which is better for
maintainability.

2. I agree that a mechanism to define standard targets would be really
useful. I even had something almost exactly like the one you
implemented in earlier bitbake-setup prototypes. Then I took it out:
bitbake-setup configs are again the wrong place for it, and having a
single, generic target is not flexible enough.

What I'd like to see is ability to have multiple standard targets that
you can give directly to bitbake:
bitbake product-build
bitbake product-test
bitbake product-deploy
etc.

And what they do would be defined directly in bitbake metadata, e.g.
in a distro configuration or in fragments. Syntax could be something
like:
BB_STANDARD_TARGETS = "product-build product-test product-deploy"
BB_STANDARD_TARGET_product-test = "-c testimage some-test-image"

We ran out of time and developer bandwidth to prototype this (let
alone make this work for upcoming LTS), but I think it should be
considered further.

Hope this helps,
Alex