diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 3a234e7b7d..a3bfce7978 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -278,6 +278,60 @@
"789 123456" and FOO2 becomes
"ghi abcdef".
+
+
+ Like _append and
+ _prepend, _remove
+ is deferred until after parsing completes.
+
+
+
+
+ Override Style Operation Advantages
+
+
+ An advantage of the override style operations
+ "_append", "_prepend", and "_remove" as compared to the
+ "+=" and "=+" operators is that the override style
+ operators provide guaranteed operations.
+ For example, consider a class iilename>foo.bbclass
+ that needs to add the value "val" to the variable
+ FOO, and a recipe that uses
+ foo.bbclass as follows:
+
+ inherit foo
+
+ FOO = "initial"
+
+ If foo.bbclass uses the "+=" operator,
+ as follows, then the final value of FOO
+ will be "initial", which is not what is desired:
+
+ FOO += "val"
+
+ If, on the other hand, foo.bbclass
+ uses the "_append" operator, then the final value of
+ FOO will be "initial val", as intended:
+
+ FOO_append = " val"
+
+
+ It is never necessary to use "+=" together with "_append".
+ The following sequence of assignments appepnds "barbaz" to
+ FOO:
+
+ FOO_append = "bar"
+ FOO_append = "baz"
+
+ The only effect of changing the second assignment in the
+ previous example is to add a space before "baz" in the
+ appended value (due to how the "+=" operator works.
+
+ Another advantage of the override style operations is that
+ you can combine them with other overrides as described in the
+ "Conditional Syntax (Overrides)"
+ section.
+
@@ -564,13 +618,13 @@
OVERRIDES = "foo"
A = "Y"
A_foo_append = "Z"
- A_foo_append += "X"
+ A_foo_append = "X"
For this case, before any overrides are resolved,
A is set to "Y" using an immediate assignment.
After this immediate assignment, A_foo is set
to "Z", and then further appended with
- "X" leaving the variable set to "Z X".
+ "X" leaving the variable set to "ZX".
Finally, applying the override for "foo" results in the conditional
variable A becoming "Z X" (i.e.
A is replaced with A_foo).