Skip to contentSkip to conversation

bitbake-user-manual: Correct description of the ??= operator

PATCH Superseded Jacob Kroon 4 participants 6 messages Jun 10, 2022 – Jun 14, 2022

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 bitbake-user-manual: Correct description of the ??= operator

Stating that the assignment is done at the end of parsing is misleading. The weak default value is the value which a variable will expand to if no value has been assigned to it using any of the assignment operators.

---

Changes in v3:
* Update commit message
* Change "... via one of ..." to "... via any of ..."

Changes in v2:
* Add comment to line with immediate variable expansion

 .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
 1 file changed, 15 insertions(+), 16 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +15 -16
index af4b1358..45355b6c 100644
@@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is set to "aval".
 Setting a weak default value (??=)
 ----------------------------------
 
-It is possible to use a "weaker" assignment than in the previous section
-by using the "??=" operator. This assignment behaves identical to "?="
-except that the assignment is made at the end of the parsing process
-rather than immediately. Consequently, when multiple "??=" assignments
-exist, the last one is used. Also, any "=" or "?=" assignment will
-override the value set with "??=". Here is an example::
-
-   A ??= "somevalue"
-   A ??= "someothervalue"
-
-If ``A`` is set before the above statements are
-parsed, the variable retains its value. If ``A`` is not set, the
-variable is set to "someothervalue".
-
-Again, this assignment is a "lazy" or "weak" assignment because it does
-not occur until the end of the parsing process.
+The weak default value of a variable is the value which that variable
+will expand to if no value has been assigned to it via any of the other
+assignment operators. Here is an example::
+
+   W ??= "x"
+   A := "${W}" # Immediate variable expansion
+   W ??= "y"
+   B = "${W}"
+   W ?= "z"
+
+After parsing we will have::
+
+   A = "x"
+   B = "z"
+   W = "z"
 
 Immediate variable expansion (:=)
 ---------------------------------
Reviewed-by on v3 1/1
#1 lore raw

Hi Jacob

Quoted 5 lines · Jacob Kroon

Stating that the assignment is done at the end of parsing is misleading. The weak default value is the value which a variable will expand to if no value has been assigned to it using any of the assignment operators.

Many thanks for this update!

Cheers
Michael.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
#2 lore raw
In reply to Jacob Kroon
Quoted 61 lines

-----Original Message-----
From: [email protected] <bitbake- [email protected]> On Behalf Of Jacob Kroon
Sent: den 10 juni 2022 21:09
To: [email protected]
Cc: [email protected]
Subject: [bitbake-devel] [PATCH v3] bitbake-user-manual: Correct description of the ??= operator

Stating that the assignment is done at the end of parsing is misleading. The weak default value is the value which a variable will expand to if no value
has been assigned to it using any of the assignment operators.

---

Changes in v3:
* Update commit message
* Change "... via one of ..." to "... via any of ..."

Changes in v2:
* Add comment to line with immediate variable expansion

 .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
 1 file changed, 15 insertions(+), 16 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0 -0
index af4b1358..45355b6c 100644
@@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is

set to "aval".
Setting a weak default value (??=)
----------------------------------

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +8 -16
-It is possible to use a "weaker" assignment than in the previous section
-by using the "??=" operator. This assignment behaves identical to "?="
-except that the assignment is made at the end of the parsing process
-rather than immediately. Consequently, when multiple "??=" assignments
-exist, the last one is used. Also, any "=" or "?=" assignment will
-override the value set with "??=". Here is an example::
-
-   A ??= "somevalue"
-   A ??= "someothervalue"
-
-If ``A`` is set before the above statements are
-parsed, the variable retains its value. If ``A`` is not set, the
-variable is set to "someothervalue".
-
-Again, this assignment is a "lazy" or "weak" assignment because it does
-not occur until the end of the parsing process.
+The weak default value of a variable is the value which that variable
+will expand to if no value has been assigned to it via any of the other
+assignment operators. Here is an example::
+
+   W ??= "x"
+   A := "${W}" # Immediate variable expansion
+   W ??= "y"
+   B = "${W}"

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst value. However, if ``A`` is not set, the variable is set to "aval". · line 215

Quoted 10 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +7 -0
+   W ?= "z"
+
+After parsing we will have::
+
+   A = "x"
+   B = "z"
+   W = "z"
 
 Immediate variable expansion (:=)
 ---------------------------------

I think the new description is missing some of the information of the original description, e.g., "when multiple "??=" assignments exist, the last one is used". So, e.g.:

W ??= "x"
W ??= "y"

gives

W = "y"

Another interesting case that is easy to get wrong is:

W ??= "x"
W += "y"

that gives

W = " y"

and which should be compared to

W ??= "x"
W:append = " y"

that gives

W = "x y"

//Peter

#3 lore raw

Hi Peter,

Thanks for the comments, I don't claim to be a data_smart.py expert so bear with me below:

Quoted 76 lines · Peter Kjellerstedt
Quoted 61 lines

-----Original Message-----
From: [email protected] <bitbake- [email protected]> On Behalf Of Jacob Kroon
Sent: den 10 juni 2022 21:09
To: [email protected]
Cc: [email protected]
Subject: [bitbake-devel] [PATCH v3] bitbake-user-manual: Correct description of the ??= operator

Stating that the assignment is done at the end of parsing is misleading. The weak default value is the value which a variable will expand to if no value
has been assigned to it using any of the assignment operators.

---

Changes in v3:
* Update commit message
* Change "... via one of ..." to "... via any of ..."

Changes in v2:
* Add comment to line with immediate variable expansion

  .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
  1 file changed, 15 insertions(+), 16 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0 -0
index af4b1358..45355b6c 100644
@@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is

set to "aval".
Setting a weak default value (??=)
----------------------------------

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +8 -16
-It is possible to use a "weaker" assignment than in the previous section
-by using the "??=" operator. This assignment behaves identical to "?="
-except that the assignment is made at the end of the parsing process
-rather than immediately. Consequently, when multiple "??=" assignments
-exist, the last one is used. Also, any "=" or "?=" assignment will
-override the value set with "??=". Here is an example::
-
-   A ??= "somevalue"
-   A ??= "someothervalue"
-
-If ``A`` is set before the above statements are
-parsed, the variable retains its value. If ``A`` is not set, the
-variable is set to "someothervalue".
-
-Again, this assignment is a "lazy" or "weak" assignment because it does
-not occur until the end of the parsing process.
+The weak default value of a variable is the value which that variable
+will expand to if no value has been assigned to it via any of the other
+assignment operators. Here is an example::
+
+   W ??= "x"
+   A := "${W}" # Immediate variable expansion
+   W ??= "y"
+   B = "${W}"

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst value. However, if ``A`` is not set, the variable is set to "aval". · line 215

Quoted 10 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +7 -0
+   W ?= "z"
+
+After parsing we will have::
+
+   A = "x"
+   B = "z"
+   W = "z"
 
  Immediate variable expansion (:=)
  ---------------------------------

I think the new description is missing some of the information of the original description, e.g., "when multiple "??=" assignments exist, the last one is used". So, e.g.:

Quoted 7 lines

W ??= "x"
W ??= "y"

gives

W = "y"

I think saying

"when multiple "??=" assignments exist, the last one is used"

is too vague because it depends on when and how you reference the variable. It is not always the "last one" that ends up "being used".

How about something like:

"The ??= assignment operator takes effect immediately, overriding any previously defined weak default value"

?

Quoted 9 lines

Another interesting case that is easy to get wrong is:

W ??= "x"
W += "y"

that gives

W = " y"

Given the definition of the weak default value and the fact that the += operator does not involve expanding the LHS before appending, this is the result I would expect. Should we add an example to the docs ?

Quoted 9 lines

and which should be compared to

W ??= "x"
W:append = " y"

that gives

W = "x y"

The docs states overrides are applied "at variable expansion time". But if the new definition of a weak default value that I am proposing is true, the variable content is expanded first, then the overrides are applied, in order to match the result above. But is that true ? I'm not that acquainted with data_smart.py to have the confidence in saying so.

Richard or any other data_smart.py expert, can you shed some light on all of this ?

Jacob

#4 lore raw
Quoted 90 lines · Jacob Kroon

Hi Peter,

Thanks for the comments, I don't claim to be a data_smart.py expert so bear with me below:

Quoted 76 lines · Peter Kjellerstedt
Quoted 61 lines

-----Original Message-----
From: [email protected] <bitbake- [email protected]> On Behalf Of Jacob Kroon
Sent: den 10 juni 2022 21:09
To: [email protected]
Cc: [email protected]
Subject: [bitbake-devel] [PATCH v3] bitbake-user-manual: Correct description of the ??= operator

Stating that the assignment is done at the end of parsing is misleading. The weak default value is the value which a variable will expand to if no value
has been assigned to it using any of the assignment operators.

---

Changes in v3:
* Update commit message
* Change "... via one of ..." to "... via any of ..."

Changes in v2:
* Add comment to line with immediate variable expansion

  .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
  1 file changed, 15 insertions(+), 16 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0 -0
index af4b1358..45355b6c 100644
@@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is

set to "aval".
Setting a weak default value (??=)
----------------------------------

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +8 -16
-It is possible to use a "weaker" assignment than in the previous section
-by using the "??=" operator. This assignment behaves identical to "?="
-except that the assignment is made at the end of the parsing process
-rather than immediately. Consequently, when multiple "??=" assignments
-exist, the last one is used. Also, any "=" or "?=" assignment will
-override the value set with "??=". Here is an example::
-
-   A ??= "somevalue"
-   A ??= "someothervalue"
-
-If ``A`` is set before the above statements are
-parsed, the variable retains its value. If ``A`` is not set, the
-variable is set to "someothervalue".
-
-Again, this assignment is a "lazy" or "weak" assignment because it does
-not occur until the end of the parsing process.
+The weak default value of a variable is the value which that variable
+will expand to if no value has been assigned to it via any of the other
+assignment operators. Here is an example::
+
+   W ??= "x"
+   A := "${W}" # Immediate variable expansion
+   W ??= "y"
+   B = "${W}"

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst value. However, if ``A`` is not set, the variable is set to "aval". · line 215

Quoted 10 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +7 -0
+   W ?= "z"
+
+After parsing we will have::
+
+   A = "x"
+   B = "z"
+   W = "z"
 
  Immediate variable expansion (:=)
  ---------------------------------

I think the new description is missing some of the information of the original description, e.g., "when multiple "??=" assignments exist, the last one is used". So, e.g.:

Quoted 7 lines

W ??= "x"
W ??= "y"

gives

W = "y"

Quoted 6 lines

I think saying

"when multiple "??=" assignments exist, the last one is used"

is too vague because it depends on when and how you reference the variable. It is not always the "last one" that ends up "being used".

The last value set during parsing order is used as the weak default value.

Quoted 4 lines

How about something like:

"The ??= assignment operator takes effect immediately, overriding any previously defined weak default value"

I do think you need to spell this out with an example as it isn't what people expect.

Quoted 5 lines
Quoted 5 lines

Another interesting case that is easy to get wrong is:

W ??= "x"
W += "y"

Quoted 8 lines
Quoted 4 lines

that gives

W = " y"

Given the definition of the weak default value and the fact that the += operator does not involve expanding the LHS before appending, this is the result I would expect. Should we add an example to the docs ?

Yes, definitely. Whilst it makes sense, people often don't expect it.

Quoted 10 lines
Quoted 9 lines

and which should be compared to

W ??= "x"
W:append = " y"

that gives

W = "x y"

Quoted 8 lines

The docs states overrides are applied "at variable expansion time". But if the new definition of a weak default value that I am proposing is true, the variable content is expanded first, then the overrides are applied, in order to match the result above. But is that true ? I'm not that acquainted with data_smart.py to have the confidence in saying so.

Richard or any other data_smart.py expert, can you shed some light on all of this ?

??= is the value given to a variable if nothing else sets it.

In the above example it is given a weak default value of "x". " y" is then appended to the base value which would be "x" since nothing else sets it. Again, it does make sense we need to have examples in the manual to make it clear.

Cheers,

Richard

#5 lore raw

Hi Richard,

Quoted 141 lines · Richard Purdie
Quoted 90 lines · Jacob Kroon

Hi Peter,

Thanks for the comments, I don't claim to be a data_smart.py expert so bear with me below:

Quoted 76 lines · Peter Kjellerstedt
Quoted 61 lines

-----Original Message-----
From: [email protected] <bitbake- [email protected]> On Behalf Of Jacob Kroon
Sent: den 10 juni 2022 21:09
To: [email protected]
Cc: [email protected]
Subject: [bitbake-devel] [PATCH v3] bitbake-user-manual: Correct description of the ??= operator

Stating that the assignment is done at the end of parsing is misleading. The weak default value is the value which a variable will expand to if no value
has been assigned to it using any of the assignment operators.

---

Changes in v3:
* Update commit message
* Change "... via one of ..." to "... via any of ..."

Changes in v2:
* Add comment to line with immediate variable expansion

   .../bitbake-user-manual-metadata.rst          | 31 +++++++++----------
   1 file changed, 15 insertions(+), 16 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +0 -0
index af4b1358..45355b6c 100644
@@ -195,22 +195,21 @@ value. However, if ``A`` is not set, the variable is

set to "aval".
Setting a weak default value (??=)
----------------------------------

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +8 -16
-It is possible to use a "weaker" assignment than in the previous section
-by using the "??=" operator. This assignment behaves identical to "?="
-except that the assignment is made at the end of the parsing process
-rather than immediately. Consequently, when multiple "??=" assignments
-exist, the last one is used. Also, any "=" or "?=" assignment will
-override the value set with "??=". Here is an example::
-
-   A ??= "somevalue"
-   A ??= "someothervalue"
-
-If ``A`` is set before the above statements are
-parsed, the variable retains its value. If ``A`` is not set, the
-variable is set to "someothervalue".
-
-Again, this assignment is a "lazy" or "weak" assignment because it does
-not occur until the end of the parsing process.
+The weak default value of a variable is the value which that variable
+will expand to if no value has been assigned to it via any of the other
+assignment operators. Here is an example::
+
+   W ??= "x"
+   A := "${W}" # Immediate variable expansion
+   W ??= "y"
+   B = "${W}"

doc/bitbake-user-manual/bitbake-user-manual-metadata.rst value. However, if ``A`` is not set, the variable is set to "aval". · line 215

Quoted 10 lines
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +7 -0
+   W ?= "z"
+
+After parsing we will have::
+
+   A = "x"
+   B = "z"
+   W = "z"
 
   Immediate variable expansion (:=)
   ---------------------------------

I think the new description is missing some of the information of the original description, e.g., "when multiple "??=" assignments exist, the last one is used". So, e.g.:

Quoted 7 lines

W ??= "x"
W ??= "y"

gives

W = "y"

Quoted 6 lines

I think saying

"when multiple "??=" assignments exist, the last one is used"

is too vague because it depends on when and how you reference the variable. It is not always the "last one" that ends up "being used".

The last value set during parsing order is used as the weak default value.

Quoted 4 lines

How about something like:

"The ??= assignment operator takes effect immediately, overriding any previously defined weak default value"

I do think you need to spell this out with an example as it isn't what people expect.

Quoted 5 lines
Quoted 5 lines

Another interesting case that is easy to get wrong is:

W ??= "x"
W += "y"

Quoted 8 lines
Quoted 4 lines

that gives

W = " y"

Given the definition of the weak default value and the fact that the += operator does not involve expanding the LHS before appending, this is the result I would expect. Should we add an example to the docs ?

Yes, definitely. Whilst it makes sense, people often don't expect it.

Quoted 16 lines
Quoted 9 lines

and which should be compared to

W ??= "x"
W:append = " y"

that gives

W = "x y"

The docs states overrides are applied "at variable expansion time". But if the new definition of a weak default value that I am proposing is true, the variable content is expanded first, then the overrides are applied, in order to match the result above. But is that true ? I'm not that acquainted with data_smart.py to have the confidence in saying so.

Quoted 5 lines
Quoted 2 lines

Richard or any other data_smart.py expert, can you shed some light on all of this ?

??= is the value given to a variable if nothing else sets it.

The problem I have with the above formulation is that "value given to a variable" does not mean that the variable will be assigned that value, which is why I prefer to use "expand to", which makes it clear that there is no assignment going on.

Quoted 8 lines

In the above example it is given a weak default value of "x". " y" is then appended to the base value which would be "x" since nothing else sets it. Again, it does make sense we need to have examples in the manual to make it clear.

Cheers,

Richard

Jacob