summaryrefslogtreecommitdiffstats
path: root/bitbake
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-07-21 10:37:09 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-08-02 15:22:15 +0100
commit6aaf37911965cbbdf7ac18433613d3fec356f906 (patch)
tree863a473d2abba7698467b83247b3492ee3829912 /bitbake
parentd1e3f0bb16bf669f2775d44d8e3ce91928ab74f1 (diff)
downloadpoky-6aaf37911965cbbdf7ac18433613d3fec356f906.tar.gz
bitbake: bitbake-user-manual: Clarified override-style operators.
Fixes [YOCTO #9985] Made the following changes: * Section Removal (Override Style Syntax): Added a small qualifying sentence at the end to further define behavior * Added new section "Override Style Operation Advantages": This section provides some rationale behind the "_append" style operations. * Section "Examples": Changed an example to use the "=" operator rather than the "+=" operator. (Bitbake rev: 797d9627baad9ccd3d55e825c0d705311f631f78) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml58
1 files changed, 56 insertions, 2 deletions
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 @@
278 "789 123456" and <filename>FOO2</filename> becomes 278 "789 123456" and <filename>FOO2</filename> becomes
279 "ghi abcdef". 279 "ghi abcdef".
280 </para> 280 </para>
281
282 <para>
283 Like <filename>_append</filename> and
284 <filename>_prepend</filename>, <filename>_remove</filename>
285 is deferred until after parsing completes.
286 </para>
287 </section>
288
289 <section id='override-style-operation-advantages'>
290 <title>Override Style Operation Advantages</title>
291
292 <para>
293 An advantage of the override style operations
294 "_append", "_prepend", and "_remove" as compared to the
295 "+=" and "=+" operators is that the override style
296 operators provide guaranteed operations.
297 For example, consider a class iilename>foo.bbclass</filename>
298 that needs to add the value "val" to the variable
299 <filename>FOO</filename>, and a recipe that uses
300 <filename>foo.bbclass</filename> as follows:
301 <literallayout class='monospaced'>
302 inherit foo
303
304 FOO = "initial"
305 </literallayout>
306 If <filename>foo.bbclass</filename> uses the "+=" operator,
307 as follows, then the final value of <filename>FOO</filename>
308 will be "initial", which is not what is desired:
309 <literallayout class='monospaced'>
310 FOO += "val"
311 </literallayout>
312 If, on the other hand, <filename>foo.bbclass</filename>
313 uses the "_append" operator, then the final value of
314 <filename>FOO</filename> will be "initial val", as intended:
315 <literallayout class='monospaced'>
316 FOO_append = " val"
317 </literallayout>
318 <note>
319 It is never necessary to use "+=" together with "_append".
320 The following sequence of assignments appepnds "barbaz" to
321 <filename>FOO</filename>:
322 <literallayout class='monospaced'>
323 FOO_append = "bar"
324 FOO_append = "baz"
325 </literallayout>
326 The only effect of changing the second assignment in the
327 previous example is to add a space before "baz" in the
328 appended value (due to how the "+=" operator works.
329 </note>
330 Another advantage of the override style operations is that
331 you can combine them with other overrides as described in the
332 "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
333 section.
334 </para>
281 </section> 335 </section>
282 336
283 <section id='variable-flag-syntax'> 337 <section id='variable-flag-syntax'>
@@ -564,13 +618,13 @@
564 OVERRIDES = "foo" 618 OVERRIDES = "foo"
565 A = "Y" 619 A = "Y"
566 A_foo_append = "Z" 620 A_foo_append = "Z"
567 A_foo_append += "X" 621 A_foo_append = "X"
568 </literallayout> 622 </literallayout>
569 For this case, before any overrides are resolved, 623 For this case, before any overrides are resolved,
570 <filename>A</filename> is set to "Y" using an immediate assignment. 624 <filename>A</filename> is set to "Y" using an immediate assignment.
571 After this immediate assignment, <filename>A_foo</filename> is set 625 After this immediate assignment, <filename>A_foo</filename> is set
572 to "Z", and then further appended with 626 to "Z", and then further appended with
573 "X" leaving the variable set to "Z X". 627 "X" leaving the variable set to "ZX".
574 Finally, applying the override for "foo" results in the conditional 628 Finally, applying the override for "foo" results in the conditional
575 variable <filename>A</filename> becoming "Z X" (i.e. 629 variable <filename>A</filename> becoming "Z X" (i.e.
576 <filename>A</filename> is replaced with <filename>A_foo</filename>). 630 <filename>A</filename> is replaced with <filename>A_foo</filename>).