want to clarify a few things about OVERRIDES

want to clarify a few things about OVERRIDES

[Robert P. J. Day]

  i think the explanation of overrides in the docs could use some
tweaking so a few questions and nitpicks.

  using "qemuarm64" as my example, i can see the OVERRIDES that are
set via "bitbake -e perf" for the perf recipe (broken over two lines
for aesthetics):

OVERRIDES="linux:aarch64:pn-perf:layer-core:qemuall:aarch64:
  qemuarm64:poky:class-target:toolchain-gcc:libc-glibc:forcevariable"

so far, so good.

  my first observation is that, when an override is combined with
"append:", that "append" bit shouldn't be described as just another
"override". IMHO, it's an *operator*, as in, it's just a variation of
"+=", which one would never describe as an "override", so when you see
something like this:

  SRC_URI:append:qemuarm = ...

to me, that's SRC_URI, then the append operator, followed by an
override -- it's just the way i like to interpret it.

  next, when you have *multiple* overrides, like here:

  CFLAGS:append:powerpc:libc-musl = ...

i assume that *all* of the overrides must be satisfied (in this case,
powerpc and the MUSL C library have to be selected).  but when you
have multiple overrides, it only makes sense if those overrides are
orthogonal to each other, which makes this snippet from bitbake.conf
potentially confusing:

# Overrides are processed left to right, so the ones that are named later take precedence.
# You generally want them to go from least to most specific. This means that:
# A variable '<foo>:arm' overrides a variable '<foo>' when ${TARGET_ARCH} is arm.
# A variable '<foo>:qemuarm' overrides '<foo>' and overrides '<foo>:arm' when ${MACHINE} is 'qemuarm'.
# If you use combination ie '<foo>:qemuarm:arm', then '<foo>:qemuarm:arm' will override
# '<foo>:qemuarm' and then '<foo>' will be overriden with that value from '<foo>:qemuarm'.

  that expression "<foo>:qemuarm:arm" makes no sense to me since
qemuarm is clearly(?) a subset of arm, so why would you ever combine
those two overrides in the same expression? i think anyone trying to
understand overrides reading that comment is going to be confused.

  thoughts?

rday

Re: [docs] want to clarify a few things about OVERRIDES

[Quentin Schulz]

Hi Robert,

On 7/24/25 5:20 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> 
>    i think the explanation of overrides in the docs could use some
> tweaking so a few questions and nitpicks.
> 
>    using "qemuarm64" as my example, i can see the OVERRIDES that are
> set via "bitbake -e perf" for the perf recipe (broken over two lines

bitbake-getvar -r perf OVERRIDES

for the cool kidz on the block ;)

> for aesthetics):
> 
> OVERRIDES="linux:aarch64:pn-perf:layer-core:qemuall:aarch64:
>    qemuarm64:poky:class-target:toolchain-gcc:libc-glibc:forcevariable"
> 
> so far, so good.
> 
>    my first observation is that, when an override is combined with
> "append:", that "append" bit shouldn't be described as just another
> "override". IMHO, it's an *operator*, as in, it's just a variation of

Agreed. It does have a completely different meaning than an override and 
this is something I've struggled to explain in my presentation (I use 
the term "post-it" to explain the postponing of that operator).

> "+=", which one would never describe as an "override", so when you see
> something like this:
> 
>    SRC_URI:append:qemuarm = ...
> 
> to me, that's SRC_URI, then the append operator, followed by an
> override -- it's just the way i like to interpret it.
> 
>    next, when you have *multiple* overrides, like here:
> 
>    CFLAGS:append:powerpc:libc-musl = ...
> 
> i assume that *all* of the overrides must be satisfied (in this case,
> powerpc and the MUSL C library have to be selected).  but when you

Correct.

> have multiple overrides, it only makes sense if those overrides are
> orthogonal to each other, which makes this snippet from bitbake.conf

This made me test some other scenario.

What do you think is the output of:

FOO = "bar"
FOO:append:arm = "baz"
FOO:append:arm:qemuarm = "bat"

?

I would have thought maybe barbat and not barbazbat like it actually.

I'm trying to find a usecase for non-orthogonal combinations but failing 
at the moment, so maybe you're right :)

> potentially confusing:
> 
> # Overrides are processed left to right, so the ones that are named later take precedence.
> # You generally want them to go from least to most specific. This means that:
> # A variable '<foo>:arm' overrides a variable '<foo>' when ${TARGET_ARCH} is arm.
> # A variable '<foo>:qemuarm' overrides '<foo>' and overrides '<foo>:arm' when ${MACHINE} is 'qemuarm'.
> # If you use combination ie '<foo>:qemuarm:arm', then '<foo>:qemuarm:arm' will override
> # '<foo>:qemuarm' and then '<foo>' will be overriden with that value from '<foo>:qemuarm'.
> 
>    that expression "<foo>:qemuarm:arm" makes no sense to me since
> qemuarm is clearly(?) a subset of arm, so why would you ever combine
> those two overrides in the same expression? i think anyone trying to
> understand overrides reading that comment is going to be confused.
> 

That's fair, we could simply replace arm or qemuarm with class-target 
instead for example.

Cheers,
Quentin

Re: [docs] want to clarify a few things about OVERRIDES

[Robert P. J. Day]

(sometimes, i think it's just easier to stay slightly confused about
some stuff and accept that i don't completely understand it. :-)

On Thu, 24 Jul 2025, Quentin Schulz wrote:

> Hi Robert,
>
> On 7/24/25 5:20 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> >
> >    i think the explanation of overrides in the docs could use some
> > tweaking so a few questions and nitpicks.
> >
> >    using "qemuarm64" as my example, i can see the OVERRIDES that are
> > set via "bitbake -e perf" for the perf recipe (broken over two lines
>
> bitbake-getvar -r perf OVERRIDES
>
> for the cool kidz on the block ;)

  i know, i was just being old school.

> > OVERRIDES="linux:aarch64:pn-perf:layer-core:qemuall:aarch64:
> >    qemuarm64:poky:class-target:toolchain-gcc:libc-glibc:forcevariable"
> >
> > so far, so good.
> >
> >    my first observation is that, when an override is combined with
> > "append:", that "append" bit shouldn't be described as just another
> > "override". IMHO, it's an *operator*, as in, it's just a variation of
>
> Agreed. It does have a completely different meaning than an override
> and this is something I've struggled to explain in my presentation
> (I use the term "post-it" to explain the postponing of that
> operator).

  quite. philosophically, i think that the way i would describe it is
-- those weird corner cases aside -- the proper way to write stuff
like this is the expression, *followed* by all of the conditional
overrides to be applied, so:

 FOO:qemuall = ...
 BAR:append:qemuarm64 = ...

embedding the "append:" operator in the *middle* of overrides (or
adding it to the end) is just begging for misunderstanding or
misinterpretation.

> > "+=", which one would never describe as an "override", so when you see
> > something like this:
> >
> >    SRC_URI:append:qemuarm = ...
> >
> > to me, that's SRC_URI, then the append operator, followed by an
> > override -- it's just the way i like to interpret it.
> >
> >    next, when you have *multiple* overrides, like here:
> >
> >    CFLAGS:append:powerpc:libc-musl = ...
> >
> > i assume that *all* of the overrides must be satisfied (in this case,
> > powerpc and the MUSL C library have to be selected).  but when you
>
> Correct.
>
> > have multiple overrides, it only makes sense if those overrides are
> > orthogonal to each other, which makes this snippet from bitbake.conf
>
> This made me test some other scenario.
>
> What do you think is the output of:
>
> FOO = "bar"
> FOO:append:arm = "baz"
> FOO:append:arm:qemuarm = "bat"
>
> ?
>
> I would have thought maybe barbat and not barbazbat like it actually.

  fascinating ... i would have predicted "barbazbat", since the first
statement assigns, and the next two append. those are entirely
independent statements, so "barbazbat" seems the obvious answer.

> I'm trying to find a usecase for non-orthogonal combinations but
> failing at the moment, so maybe you're right :)

  i think the only components of OVERRIDES that are potentially
non-orthogonal are TRANSLATED_TARGET_ARCH and MACHINE_OVERRIDES. i
can't say what *should* happen in cases like that; i guess just take
the matching override of highest (right-most) precedence.

> > potentially confusing:
> >
> > # Overrides are processed left to right, so the ones that are named later
> > take precedence.
> > # You generally want them to go from least to most specific. This means
> > that:
> > # A variable '<foo>:arm' overrides a variable '<foo>' when ${TARGET_ARCH} is
> > arm.
> > # A variable '<foo>:qemuarm' overrides '<foo>' and overrides '<foo>:arm'
> > when ${MACHINE} is 'qemuarm'.
> > # If you use combination ie '<foo>:qemuarm:arm', then '<foo>:qemuarm:arm'
> > will override
> > # '<foo>:qemuarm' and then '<foo>' will be overriden with that value from
> > '<foo>:qemuarm'.
> >
> >    that expression "<foo>:qemuarm:arm" makes no sense to me since
> > qemuarm is clearly(?) a subset of arm, so why would you ever combine
> > those two overrides in the same expression? i think anyone trying to
> > understand overrides reading that comment is going to be confused.
> >
>
> That's fair, we could simply replace arm or qemuarm with class-target instead
> for example.

  yeah, that's what i was thinking ... that comment really doesn't
clarify anything and just makes it more confusing.

 i will ponder on how to properly and comprehensively explain
overrides with some real-life examples.

rday