Yocto Project® — How to replace the content of a variable (BitBake) Part 3

Last Updated on November 2, 2025

Objectives

This blog post aims to show how to replace the content of a variable in a BitBake recipe (BitBake). The recipe resides in a third-party layer. Understanding this process is essential for customization, particularly when dealing with third-party layers. Maybe this part should be named “How not to replace the content of a variable”, but let’s see this later. It is recommended that you start with part 1 (Part 1) followed by part 2 (Part 2).

A recipe in a third party layer (layer)

Remember? We have got a third-party layer (layer) from somewhere with a recipe called mod-var_1.0.bb:

SUMMARY = "Test case for overwriting/replacing a variable"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

BOOTENV_OVERLAYS_APPEND = "from-bb-imx93-phyboard-nash-jtag.dtbo"

do_mod_var() {
    bbwarn "bb BOOTENV_OVERLAYS_APPEND: ${BOOTENV_OVERLAYS_APPEND}"
}
addtask do_mod_var

Let’s bake it with BitBake. We’ll utilize the procedure of replacing the variable’s content in a BitBake recipe from a third-party layer further down.

bitbake mod-var -c do_mod_var

And it will output something like this:

WARNING: mod-var-1.0-r0 do_mod_var: bb BOOTENV_OVERLAYS_APPEND: from-bb-imx93-phyboard-nash-jtag.dtbo

We can try to investigate it a bit further and try to find out who sets the variable (BOOTENV_OVERLAYS_APPEND):

bitbake-getvar -r mod-var BOOTENV_OVERLAYS_APPEND

This will show something like this:

#
# $BOOTENV_OVERLAYS_APPEND
#   set /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bb:5
#     "from-bb-imx93-phyboard-nash-jtag.dtbo"
BOOTENV_OVERLAYS_APPEND="from-bb-imx93-phyboard-nash-jtag.dtbo"

This tells us: The content of the variable BOOTENV_OVERLAYS_APPEND is "from-bb-imx93-phyboard-nash-jtag.dtbo". It was modified in line 5 of this file: mod-var_1.0.bb. When you replace a variable’s content in a BitBake recipe of a third-party layer, it’s important to consider examples like these below.

Replace the content of the variable

Append File — Lazy Assignment

The BitBake manual says: “Append files are used to extend or override information in an existing (third-party) recipe file. They have the .bbappend file extension.” Take a look at Basic Variable Setting and Variable Expansion.

In other words: We make a .bbappend file, and we place it in our layer (layer). The directory structure has to be the same as the corresponding third-party layer. Like this, BitBake can find the .bb file. Such as mod-var_1.0.bbappend:

# let the bbappend replace BOOTENV_OVERLAYS_APPEND

BOOTENV_OVERLAYS_APPEND = "from-bbappend-imx93-phyboard-nash-jtag.dtbo"

do_mod_var:append() {
    bbwarn "bbappend BOOTENV_OVERLAYS_APPEND: ${BOOTENV_OVERLAYS_APPEND}"
}

bitbake mod-var -c do_mod_var

WARNING: mod-var-1.0-r0 do_mod_var: bb BOOTENV_OVERLAYS_APPEND: from-bbappend-imx93-phyboard-nash-jtag.dtbo
WARNING: mod-var-1.0-r0 do_mod_var: bbappend BOOTENV_OVERLAYS_APPEND: from-bbappend-imx93-phyboard-nash-jtag.dtbo

bitbake-getvar -r mod-var BOOTENV_OVERLAYS_APPEND

#
# $BOOTENV_OVERLAYS_APPEND [2 operations]
#   set /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bb:5
#     "from-bb-imx93-phyboard-nash-jtag.dtbo"
#   set /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bbappend:3
#     "from-bbappend-imx93-phyboard-nash-jtag.dtbo"
# pre-expansion value:
#   "from-bbappend-imx93-phyboard-nash-jtag.dtbo"
BOOTENV_OVERLAYS_APPEND="from-bbappend-imx93-phyboard-nash-jtag.dtbo"

How does this work? The .bbappend file comes after the .bb file. Line 3 of the .bbappend overwrites the variable’s content (from line 5 of the .bb file). When dealing with recipes in third-party layers, it’s important to follow this steps so that modification occurs correctly.

Let’s take a look at the logs (logs). They are here:

bitbake mod_var -e | grep ^T=

T="/workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp"

It’s a good idea to erase all the log files for this recipe:

cd /workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp
rm -rf *

Let’s bake it:

bitbake mod-var -c do_mod_var

Let’s see the interesting part of the logs (run.do_mod_var):

# line: 7, file: /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bb
do_mod_var() {
    bbwarn "bb BOOTENV_OVERLAYS_APPEND: from-bbappend-imx93-phyboard-nash-jtag.dtbo"
    bbwarn "bbappend BOOTENV_OVERLAYS_APPEND: from-bbappend-imx93-phyboard-nash-jtag.dtbo"
}

That’s all good, does what it is supposed to do and also what we want.

Let’s slightly modify the .bbappend file:

# let the bbappend replace BOOTENV_OVERLAYS_APPEND

BOOTENV_OVERLAYS_APPEND="from-bbappend-imx93-phyboard-nash-jtag.dtbo"

do_mod_var:append() {
    bbwarn "bbappend BOOTENV_OVERLAYS_APPEND: ${BOOTENV_OVERLAYS_APPEND}"
}

Did you notice the difference? Hint: “Lack of whitespace around the assignment“. This small detail, under certain circumstances, can affect replacing a variable’s content in a BitBake recipe of a third-party layer, as we’ll see below.

If you use a recent version of BitBake you’ll get a warning:

WARNING: /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bb: /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bbappend:3 has a lack of whitespace around the assignment: 'BOOTENV_OVERLAYS_APPEND="from-bbappend-imx93-phyboard-nash-jtag.dtbo"'

Append File — Lazy Assignment – unfortunately wrong

A common mistake is to write your .bbappend file like this:

do_mod_var:append() {
    BOOTENV_OVERLAYS_APPEND = "from-bbappend-imx93-phyboard-nash-jtag.dtbo"
    bbwarn "bbappend BOOTENV_OVERLAYS_APPEND: ${BOOTENV_OVERLAYS_APPEND}"
}

Let’s bake it:

bitbake mod-var -c do_mod_var

Now you’ll get an error like this:

WARNING: mod-var-1.0-r0 do_mod_var: bb BOOTENV_OVERLAYS_APPEND: from-bb-imx93-phyboard-nash-jtag.dtbo
ERROR: mod-var-1.0-r0 do_mod_var: Execution of '/workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp/run.do_mod_var.1994010' failed with exit code 127
ERROR: Logfile of failure stored in: /workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp/log.do_mod_var.1994010
Log data follows:
| DEBUG: Executing shell function do_mod_var
| WARNING: bb BOOTENV_OVERLAYS_APPEND: from-bb-imx93-phyboard-nash-jtag.dtbo
| /workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp/run.do_mod_var.1994010: line 141: BOOTENV_OVERLAYS_APPEND: command not found
| WARNING: /workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp/run.do_mod_var.1994010:141 exit 127 from 'BOOTENV_OVERLAYS_APPEND = "from-bbappend-imx93-phyboard-nash-jtag.dtbo"'
| WARNING: Backtrace (BB generated script):
|       #1: do_mod_var, /workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp/run.do_mod_var.1994010, line 141
|       #2: main, /workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp/run.do_mod_var.1994010, line 154
ERROR: Task (/workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bb:do_mod_var) failed with exit code '1'
NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and 1 failed.
NOTE: The errors for this build are stored in /workdir/build/multi-v7-ml-debug-training-master/tmp/log/error-report/error_report_20250803170216.txt
You can send the errors to a reports server by running:
  send-error-report /workdir/build/multi-v7-ml-debug-training-master/tmp/log/error-report/error_report_20250803170216.txt [-s server]
NOTE: The contents of these logs will be posted in public if you use the above command with the default server. Please ensure you remove any identifying or proprietary information when prompted before sending.
NOTE: Writing buildhistory
NOTE: Writing buildhistory took: 2 seconds

Summary: 1 task failed:
  /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bb:do_mod_var
    log: /workdir/build/multi-v7-ml-debug-training-master/tmp/work/armv7at2hf-neon-resy-linux-gnueabi/mod-var/1.0/temp/log.do_mod_var.1994010
Summary: There was 1 WARNING message.
Summary: There was 1 ERROR message, returning a non-zero exit code.

Let’s try to fix this error so the recipe bakes again:

do_mod_var:append() {
    BOOTENV_OVERLAYS_APPEND="from-bbappend-imx93-phyboard-nash-jtag.dtbo"
    bbwarn "bbappend BOOTENV_OVERLAYS_APPEND: ${BOOTENV_OVERLAYS_APPEND}"
}

bitbake mod-var -c do_mod_var

The recipe bakes without the warning (“Lack of whitespace around the assignment“), but it does not do what we want. While attempting to replace the content of a variable in a BitBake recipe of a third-party layer, errors such as these can arise.

WARNING: mod-var-1.0-r0 do_mod_var: bb BOOTENV_OVERLAYS_APPEND: from-bb-imx93-phyboard-nash-jtag.dtbo
WARNING: mod-var-1.0-r0 do_mod_var: bbappend BOOTENV_OVERLAYS_APPEND: from-bb-imx93-phyboard-nash-jtag.dtbo

What happened?

Let’s see the interesting part of the logs (run.do_mod_var):

# line: 7, file: /workdir/sources/meta-bb-syntax/recipes-mod-var/mod-var/mod-var_1.0.bb
do_mod_var() {
    bbwarn "bb BOOTENV_OVERLAYS_APPEND: from-bb-imx93-phyboard-nash-jtag.dtbo"
    BOOTENV_OVERLAYS_APPEND="from-bbappend-imx93-phyboard-nash-jtag.dtbo"
    bbwarn "bbappend BOOTENV_OVERLAYS_APPEND: from-bb-imx93-phyboard-nash-jtag.dtbo"
}

A shell variable (BOOTENV_OVERLAYS_APPEND) was created and initialized to from-bbappend-imx93-phyboard-nash-jtag.dtbo, but the variable (BOOTENV_OVERLAYS_APPEND) in Bitbake’s datastore (BitBake's datastore) was not modified.

Conclusion

As always, read the fine print carefully, ask, and experiment. Understanding the nuances when you replace the content of a variable in a BitBake recipe of a third-party layer is beneficial for successful execution. I am writing these kinds of test cases to show attendees of my training sessions how things work and, for me, to understand subtle syntax differences.

Appendix

To learn how Embedded Linux works, take a look here. To learn more about the Yocto Project® take a look here.