summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst172
1 files changed, 86 insertions, 86 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index d4190c26ee..615c9f9ce1 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -26,7 +26,7 @@ assignment. ::
26 VARIABLE = "value" 26 VARIABLE = "value"
27 27
28As expected, if you include leading or 28As expected, if you include leading or
29trailing spaces as part of an assignment, the spaces are retained: :: 29trailing spaces as part of an assignment, the spaces are retained::
30 30
31 VARIABLE = " value" 31 VARIABLE = " value"
32 VARIABLE = "value " 32 VARIABLE = "value "
@@ -40,7 +40,7 @@ blank space (i.e. these are not the same values). ::
40 40
41You can use single quotes instead of double quotes when setting a 41You can use single quotes instead of double quotes when setting a
42variable's value. Doing so allows you to use values that contain the 42variable's value. Doing so allows you to use values that contain the
43double quote character: :: 43double quote character::
44 44
45 VARIABLE = 'I have a " in my value' 45 VARIABLE = 'I have a " in my value'
46 46
@@ -77,7 +77,7 @@ occurs, you can use BitBake to check the actual value of the suspect
77variable. You can make these checks for both configuration and recipe 77variable. You can make these checks for both configuration and recipe
78level changes: 78level changes:
79 79
80- For configuration changes, use the following: :: 80- For configuration changes, use the following::
81 81
82 $ bitbake -e 82 $ bitbake -e
83 83
@@ -91,7 +91,7 @@ level changes:
91 Variables that are exported to the environment are preceded by the 91 Variables that are exported to the environment are preceded by the
92 string "export" in the command's output. 92 string "export" in the command's output.
93 93
94- For recipe changes, use the following: :: 94- For recipe changes, use the following::
95 95
96 $ bitbake recipe -e \| grep VARIABLE=" 96 $ bitbake recipe -e \| grep VARIABLE="
97 97
@@ -105,7 +105,7 @@ Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:fun
105BitBake joins any line ending in 105BitBake joins any line ending in
106a backslash character ("\") with the following line before parsing 106a backslash character ("\") with the following line before parsing
107statements. The most common use for the "\" character is to split 107statements. The most common use for the "\" character is to split
108variable assignments over multiple lines, as in the following example: :: 108variable assignments over multiple lines, as in the following example::
109 109
110 FOO = "bar \ 110 FOO = "bar \
111 baz \ 111 baz \
@@ -116,7 +116,7 @@ character that follow it are removed when joining lines. Thus, no
116newline characters end up in the value of ``FOO``. 116newline characters end up in the value of ``FOO``.
117 117
118Consider this additional example where the two assignments both assign 118Consider this additional example where the two assignments both assign
119"barbaz" to ``FOO``: :: 119"barbaz" to ``FOO``::
120 120
121 FOO = "barbaz" 121 FOO = "barbaz"
122 FOO = "bar\ 122 FOO = "bar\
@@ -149,7 +149,7 @@ The "=" operator does not immediately expand variable references in the
149right-hand side. Instead, expansion is deferred until the variable 149right-hand side. Instead, expansion is deferred until the variable
150assigned to is actually used. The result depends on the current values 150assigned to is actually used. The result depends on the current values
151of the referenced variables. The following example should clarify this 151of the referenced variables. The following example should clarify this
152behavior: :: 152behavior::
153 153
154 A = "${B} baz" 154 A = "${B} baz"
155 B = "${C} bar" 155 B = "${C} bar"
@@ -177,7 +177,7 @@ Setting a default value (?=)
177You can use the "?=" operator to achieve a "softer" assignment for a 177You can use the "?=" operator to achieve a "softer" assignment for a
178variable. This type of assignment allows you to define a variable if it 178variable. This type of assignment allows you to define a variable if it
179is undefined when the statement is parsed, but to leave the value alone 179is undefined when the statement is parsed, but to leave the value alone
180if the variable has a value. Here is an example: :: 180if the variable has a value. Here is an example::
181 181
182 A ?= "aval" 182 A ?= "aval"
183 183
@@ -199,7 +199,7 @@ by using the "??=" operator. This assignment behaves identical to "?="
199except that the assignment is made at the end of the parsing process 199except that the assignment is made at the end of the parsing process
200rather than immediately. Consequently, when multiple "??=" assignments 200rather than immediately. Consequently, when multiple "??=" assignments
201exist, the last one is used. Also, any "=" or "?=" assignment will 201exist, the last one is used. Also, any "=" or "?=" assignment will
202override the value set with "??=". Here is an example: :: 202override the value set with "??=". Here is an example::
203 203
204 A ??= "somevalue" 204 A ??= "somevalue"
205 A ??= "someothervalue" 205 A ??= "someothervalue"
@@ -215,7 +215,7 @@ Immediate variable expansion (:=)
215--------------------------------- 215---------------------------------
216 216
217The ":=" operator results in a variable's contents being expanded 217The ":=" operator results in a variable's contents being expanded
218immediately, rather than when the variable is actually used: :: 218immediately, rather than when the variable is actually used::
219 219
220 T = "123" 220 T = "123"
221 A := "test ${T}" 221 A := "test ${T}"
@@ -241,7 +241,7 @@ the "+=" and "=+" operators. These operators insert a space between the
241current value and prepended or appended value. 241current value and prepended or appended value.
242 242
243These operators take immediate effect during parsing. Here are some 243These operators take immediate effect during parsing. Here are some
244examples: :: 244examples::
245 245
246 B = "bval" 246 B = "bval"
247 B += "additionaldata" 247 B += "additionaldata"
@@ -260,7 +260,7 @@ If you want to append or prepend values without an inserted space, use
260the ".=" and "=." operators. 260the ".=" and "=." operators.
261 261
262These operators take immediate effect during parsing. Here are some 262These operators take immediate effect during parsing. Here are some
263examples: :: 263examples::
264 264
265 B = "bval" 265 B = "bval"
266 B .= "additionaldata" 266 B .= "additionaldata"
@@ -278,7 +278,7 @@ style syntax. When you use this syntax, no spaces are inserted.
278 278
279These operators differ from the ":=", ".=", "=.", "+=", and "=+" 279These operators differ from the ":=", ".=", "=.", "+=", and "=+"
280operators in that their effects are applied at variable expansion time 280operators in that their effects are applied at variable expansion time
281rather than being immediately applied. Here are some examples: :: 281rather than being immediately applied. Here are some examples::
282 282
283 B = "bval" 283 B = "bval"
284 B_append = " additional data" 284 B_append = " additional data"
@@ -309,7 +309,7 @@ syntax. Specifying a value for removal causes all occurrences of that
309value to be removed from the variable. 309value to be removed from the variable.
310 310
311When you use this syntax, BitBake expects one or more strings. 311When you use this syntax, BitBake expects one or more strings.
312Surrounding spaces and spacing are preserved. Here is an example: :: 312Surrounding spaces and spacing are preserved. Here is an example::
313 313
314 FOO = "123 456 789 123456 123 456 123 456" 314 FOO = "123 456 789 123456 123 456 123 456"
315 FOO_remove = "123" 315 FOO_remove = "123"
@@ -334,27 +334,27 @@ An advantage of the override style operations "_append", "_prepend", and
334"_remove" as compared to the "+=" and "=+" operators is that the 334"_remove" as compared to the "+=" and "=+" operators is that the
335override style operators provide guaranteed operations. For example, 335override style operators provide guaranteed operations. For example,
336consider a class ``foo.bbclass`` that needs to add the value "val" to 336consider a class ``foo.bbclass`` that needs to add the value "val" to
337the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: :: 337the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows::
338 338
339 inherit foo 339 inherit foo
340 FOO = "initial" 340 FOO = "initial"
341 341
342If ``foo.bbclass`` uses the "+=" operator, 342If ``foo.bbclass`` uses the "+=" operator,
343as follows, then the final value of ``FOO`` will be "initial", which is 343as follows, then the final value of ``FOO`` will be "initial", which is
344not what is desired: :: 344not what is desired::
345 345
346 FOO += "val" 346 FOO += "val"
347 347
348If, on the other hand, ``foo.bbclass`` 348If, on the other hand, ``foo.bbclass``
349uses the "_append" operator, then the final value of ``FOO`` will be 349uses the "_append" operator, then the final value of ``FOO`` will be
350"initial val", as intended: :: 350"initial val", as intended::
351 351
352 FOO_append = " val" 352 FOO_append = " val"
353 353
354.. note:: 354.. note::
355 355
356 It is never necessary to use "+=" together with "_append". The following 356 It is never necessary to use "+=" together with "_append". The following
357 sequence of assignments appends "barbaz" to FOO: :: 357 sequence of assignments appends "barbaz" to FOO::
358 358
359 FOO_append = "bar" 359 FOO_append = "bar"
360 FOO_append = "baz" 360 FOO_append = "baz"
@@ -381,7 +381,7 @@ standard syntax operations previously mentioned work for variable flags
381except for override style syntax (i.e. "_prepend", "_append", and 381except for override style syntax (i.e. "_prepend", "_append", and
382"_remove"). 382"_remove").
383 383
384Here are some examples showing how to set variable flags: :: 384Here are some examples showing how to set variable flags::
385 385
386 FOO[a] = "abc" 386 FOO[a] = "abc"
387 FOO[b] = "123" 387 FOO[b] = "123"
@@ -393,7 +393,7 @@ respectively. The ``[a]`` flag becomes "abc 456".
393 393
394No need exists to pre-define variable flags. You can simply start using 394No need exists to pre-define variable flags. You can simply start using
395them. One extremely common application is to attach some brief 395them. One extremely common application is to attach some brief
396documentation to a BitBake variable as follows: :: 396documentation to a BitBake variable as follows::
397 397
398 CACHE[doc] = "The directory holding the cache of the metadata." 398 CACHE[doc] = "The directory holding the cache of the metadata."
399 399
@@ -401,7 +401,7 @@ Inline Python Variable Expansion
401-------------------------------- 401--------------------------------
402 402
403You can use inline Python variable expansion to set variables. Here is 403You can use inline Python variable expansion to set variables. Here is
404an example: :: 404an example::
405 405
406 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" 406 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
407 407
@@ -410,7 +410,7 @@ This example results in the ``DATE`` variable being set to the current date.
410Probably the most common use of this feature is to extract the value of 410Probably the most common use of this feature is to extract the value of
411variables from BitBake's internal data dictionary, ``d``. The following 411variables from BitBake's internal data dictionary, ``d``. The following
412lines select the values of a package name and its version number, 412lines select the values of a package name and its version number,
413respectively: :: 413respectively::
414 414
415 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" 415 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
416 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" 416 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
@@ -419,12 +419,12 @@ respectively: ::
419 419
420 Inline Python expressions work just like variable expansions insofar as the 420 Inline Python expressions work just like variable expansions insofar as the
421 "=" and ":=" operators are concerned. Given the following assignment, foo() 421 "=" and ":=" operators are concerned. Given the following assignment, foo()
422 is called each time FOO is expanded: :: 422 is called each time FOO is expanded::
423 423
424 FOO = "${@foo()}" 424 FOO = "${@foo()}"
425 425
426 Contrast this with the following immediate assignment, where foo() is only 426 Contrast this with the following immediate assignment, where foo() is only
427 called once, while the assignment is parsed: :: 427 called once, while the assignment is parsed::
428 428
429 FOO := "${@foo()}" 429 FOO := "${@foo()}"
430 430
@@ -437,7 +437,7 @@ Unsetting variables
437 437
438It is possible to completely remove a variable or a variable flag from 438It is possible to completely remove a variable or a variable flag from
439BitBake's internal data dictionary by using the "unset" keyword. Here is 439BitBake's internal data dictionary by using the "unset" keyword. Here is
440an example: :: 440an example::
441 441
442 unset DATE 442 unset DATE
443 unset do_fetch[noexec] 443 unset do_fetch[noexec]
@@ -452,7 +452,7 @@ When specifying pathnames for use with BitBake, do not use the tilde
452cause BitBake to not recognize the path since BitBake does not expand 452cause BitBake to not recognize the path since BitBake does not expand
453this character in the same way a shell would. 453this character in the same way a shell would.
454 454
455Instead, provide a fuller path as the following example illustrates: :: 455Instead, provide a fuller path as the following example illustrates::
456 456
457 BBLAYERS ?= " \ 457 BBLAYERS ?= " \
458 /home/scott-lenovo/LayerA \ 458 /home/scott-lenovo/LayerA \
@@ -463,7 +463,7 @@ Exporting Variables to the Environment
463 463
464You can export variables to the environment of running tasks by using 464You can export variables to the environment of running tasks by using
465the ``export`` keyword. For example, in the following example, the 465the ``export`` keyword. For example, in the following example, the
466``do_foo`` task prints "value from the environment" when run: :: 466``do_foo`` task prints "value from the environment" when run::
467 467
468 export ENV_VARIABLE 468 export ENV_VARIABLE
469 ENV_VARIABLE = "value from the environment" 469 ENV_VARIABLE = "value from the environment"
@@ -481,7 +481,7 @@ It does not matter whether ``export ENV_VARIABLE`` appears before or
481after assignments to ``ENV_VARIABLE``. 481after assignments to ``ENV_VARIABLE``.
482 482
483It is also possible to combine ``export`` with setting a value for the 483It is also possible to combine ``export`` with setting a value for the
484variable. Here is an example: :: 484variable. Here is an example::
485 485
486 export ENV_VARIABLE = "variable-value" 486 export ENV_VARIABLE = "variable-value"
487 487
@@ -518,7 +518,7 @@ variable.
518 to satisfy conditions. Thus, if you have a variable that is 518 to satisfy conditions. Thus, if you have a variable that is
519 conditional on "arm", and "arm" is in ``OVERRIDES``, then the 519 conditional on "arm", and "arm" is in ``OVERRIDES``, then the
520 "arm"-specific version of the variable is used rather than the 520 "arm"-specific version of the variable is used rather than the
521 non-conditional version. Here is an example: :: 521 non-conditional version. Here is an example::
522 522
523 OVERRIDES = "architecture:os:machine" 523 OVERRIDES = "architecture:os:machine"
524 TEST = "default" 524 TEST = "default"
@@ -535,7 +535,7 @@ variable.
535 an OpenEmbedded metadata-based Linux kernel recipe file. The 535 an OpenEmbedded metadata-based Linux kernel recipe file. The
536 following lines from the recipe file first set the kernel branch 536 following lines from the recipe file first set the kernel branch
537 variable ``KBRANCH`` to a default value, then conditionally override 537 variable ``KBRANCH`` to a default value, then conditionally override
538 that value based on the architecture of the build: :: 538 that value based on the architecture of the build::
539 539
540 KBRANCH = "standard/base" 540 KBRANCH = "standard/base"
541 KBRANCH_qemuarm = "standard/arm-versatile-926ejs" 541 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
@@ -547,7 +547,7 @@ variable.
547 547
548- *Appending and Prepending:* BitBake also supports append and prepend 548- *Appending and Prepending:* BitBake also supports append and prepend
549 operations to variable values based on whether a specific item is 549 operations to variable values based on whether a specific item is
550 listed in ``OVERRIDES``. Here is an example: :: 550 listed in ``OVERRIDES``. Here is an example::
551 551
552 DEPENDS = "glibc ncurses" 552 DEPENDS = "glibc ncurses"
553 OVERRIDES = "machine:local" 553 OVERRIDES = "machine:local"
@@ -557,14 +557,14 @@ variable.
557 557
558 Again, using an OpenEmbedded metadata-based kernel recipe file as an 558 Again, using an OpenEmbedded metadata-based kernel recipe file as an
559 example, the following lines will conditionally append to the 559 example, the following lines will conditionally append to the
560 ``KERNEL_FEATURES`` variable based on the architecture: :: 560 ``KERNEL_FEATURES`` variable based on the architecture::
561 561
562 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" 562 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
563 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" 563 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
564 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" 564 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
565 565
566- *Setting a Variable for a Single Task:* BitBake supports setting a 566- *Setting a Variable for a Single Task:* BitBake supports setting a
567 variable just for the duration of a single task. Here is an example: :: 567 variable just for the duration of a single task. Here is an example::
568 568
569 FOO_task-configure = "val 1" 569 FOO_task-configure = "val 1"
570 FOO_task-compile = "val 2" 570 FOO_task-compile = "val 2"
@@ -580,7 +580,7 @@ variable.
580 ``do_compile`` task. 580 ``do_compile`` task.
581 581
582 You can also use this syntax with other combinations (e.g. 582 You can also use this syntax with other combinations (e.g.
583 "``_prepend``") as shown in the following example: :: 583 "``_prepend``") as shown in the following example::
584 584
585 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " 585 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} "
586 586
@@ -588,7 +588,7 @@ Key Expansion
588------------- 588-------------
589 589
590Key expansion happens when the BitBake datastore is finalized. To better 590Key expansion happens when the BitBake datastore is finalized. To better
591understand this, consider the following example: :: 591understand this, consider the following example::
592 592
593 A${B} = "X" 593 A${B} = "X"
594 B = "2" 594 B = "2"
@@ -614,7 +614,7 @@ There is often confusion concerning the order in which overrides and
614various "append" operators take effect. Recall that an append or prepend 614various "append" operators take effect. Recall that an append or prepend
615operation using "_append" and "_prepend" does not result in an immediate 615operation using "_append" and "_prepend" does not result in an immediate
616assignment as would "+=", ".=", "=+", or "=.". Consider the following 616assignment as would "+=", ".=", "=+", or "=.". Consider the following
617example: :: 617example::
618 618
619 OVERRIDES = "foo" 619 OVERRIDES = "foo"
620 A = "Z" 620 A = "Z"
@@ -631,7 +631,7 @@ Applying overrides, however, changes things. Since "foo" is listed in
631version, which is equal to "X". So effectively, ``A_foo`` replaces 631version, which is equal to "X". So effectively, ``A_foo`` replaces
632``A``. 632``A``.
633 633
634This next example changes the order of the override and the append: :: 634This next example changes the order of the override and the append::
635 635
636 OVERRIDES = "foo" 636 OVERRIDES = "foo"
637 A = "Z" 637 A = "Z"
@@ -644,7 +644,7 @@ appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces
644are not appended. 644are not appended.
645 645
646This next example has the order of the appends and overrides reversed 646This next example has the order of the appends and overrides reversed
647back as in the first example: :: 647back as in the first example::
648 648
649 OVERRIDES = "foo" 649 OVERRIDES = "foo"
650 A = "Y" 650 A = "Y"
@@ -658,7 +658,7 @@ leaving the variable set to "ZX". Finally, applying the override for
658"foo" results in the conditional variable ``A`` becoming "ZX" (i.e. 658"foo" results in the conditional variable ``A`` becoming "ZX" (i.e.
659``A`` is replaced with ``A_foo``). 659``A`` is replaced with ``A_foo``).
660 660
661This final example mixes in some varying operators: :: 661This final example mixes in some varying operators::
662 662
663 A = "1" 663 A = "1"
664 A_append = "2" 664 A_append = "2"
@@ -720,7 +720,7 @@ file and then have your recipe inherit that class file.
720 720
721As an example, your recipes could use the following directive to inherit 721As an example, your recipes could use the following directive to inherit
722an ``autotools.bbclass`` file. The class file would contain common 722an ``autotools.bbclass`` file. The class file would contain common
723functionality for using Autotools that could be shared across recipes: :: 723functionality for using Autotools that could be shared across recipes::
724 724
725 inherit autotools 725 inherit autotools
726 726
@@ -734,7 +734,7 @@ In this case, BitBake would search for the directory
734 734
735If you want to use the directive to inherit multiple classes, separate 735If you want to use the directive to inherit multiple classes, separate
736them with spaces. The following example shows how to inherit both the 736them with spaces. The following example shows how to inherit both the
737``buildhistory`` and ``rm_work`` classes: :: 737``buildhistory`` and ``rm_work`` classes::
738 738
739 inherit buildhistory rm_work 739 inherit buildhistory rm_work
740 740
@@ -742,19 +742,19 @@ An advantage with the inherit directive as compared to both the
742:ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` 742:ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
743directives is that you can inherit class files conditionally. You can 743directives is that you can inherit class files conditionally. You can
744accomplish this by using a variable expression after the ``inherit`` 744accomplish this by using a variable expression after the ``inherit``
745statement. Here is an example: :: 745statement. Here is an example::
746 746
747 inherit ${VARNAME} 747 inherit ${VARNAME}
748 748
749If ``VARNAME`` is 749If ``VARNAME`` is
750going to be set, it needs to be set before the ``inherit`` statement is 750going to be set, it needs to be set before the ``inherit`` statement is
751parsed. One way to achieve a conditional inherit in this case is to use 751parsed. One way to achieve a conditional inherit in this case is to use
752overrides: :: 752overrides::
753 753
754 VARIABLE = "" 754 VARIABLE = ""
755 VARIABLE_someoverride = "myclass" 755 VARIABLE_someoverride = "myclass"
756 756
757Another method is by using anonymous Python. Here is an example: :: 757Another method is by using anonymous Python. Here is an example::
758 758
759 python () { 759 python () {
760 if condition == value: 760 if condition == value:
@@ -764,7 +764,7 @@ Another method is by using anonymous Python. Here is an example: ::
764 } 764 }
765 765
766Alternatively, you could use an in-line Python expression in the 766Alternatively, you could use an in-line Python expression in the
767following form: :: 767following form::
768 768
769 inherit ${@'classname' if condition else ''} 769 inherit ${@'classname' if condition else ''}
770 inherit ${@functionname(params)} 770 inherit ${@functionname(params)}
@@ -790,7 +790,7 @@ encapsulated functionality or configuration that does not suit a
790``.bbclass`` file. 790``.bbclass`` file.
791 791
792As an example, suppose you needed a recipe to include some self-test 792As an example, suppose you needed a recipe to include some self-test
793definitions: :: 793definitions::
794 794
795 include test_defs.inc 795 include test_defs.inc
796 796
@@ -831,7 +831,7 @@ include file named ``foo.inc`` that contains the common definitions
831needed to build "foo". You need to be sure ``foo.inc`` is located in the 831needed to build "foo". You need to be sure ``foo.inc`` is located in the
832same directory as your two recipe files as well. Once these conditions 832same directory as your two recipe files as well. Once these conditions
833are set up, you can share the functionality using a ``require`` 833are set up, you can share the functionality using a ``require``
834directive from within each recipe: :: 834directive from within each recipe::
835 835
836 require foo.inc 836 require foo.inc
837 837
@@ -844,7 +844,7 @@ class. BitBake only supports this directive when used within a
844configuration file. 844configuration file.
845 845
846As an example, suppose you needed to inherit a class file called 846As an example, suppose you needed to inherit a class file called
847``abc.bbclass`` from a configuration file as follows: :: 847``abc.bbclass`` from a configuration file as follows::
848 848
849 INHERIT += "abc" 849 INHERIT += "abc"
850 850
@@ -862,7 +862,7 @@ subdirectory in one of the directories specified in ``BBPATH``.
862If you want to use the directive to inherit multiple classes, you can 862If you want to use the directive to inherit multiple classes, you can
863provide them on the same line in the ``local.conf`` file. Use spaces to 863provide them on the same line in the ``local.conf`` file. Use spaces to
864separate the classes. The following example shows how to inherit both 864separate the classes. The following example shows how to inherit both
865the ``autotools`` and ``pkgconfig`` classes: :: 865the ``autotools`` and ``pkgconfig`` classes::
866 866
867 INHERIT += "autotools pkgconfig" 867 INHERIT += "autotools pkgconfig"
868 868
@@ -895,7 +895,7 @@ Shell Functions
895 895
896Functions written in shell script and executed either directly as 896Functions written in shell script and executed either directly as
897functions, tasks, or both. They can also be called by other shell 897functions, tasks, or both. They can also be called by other shell
898functions. Here is an example shell function definition: :: 898functions. Here is an example shell function definition::
899 899
900 some_function () { 900 some_function () {
901 echo "Hello World" 901 echo "Hello World"
@@ -912,7 +912,7 @@ can also be applied to shell functions. Most commonly, this application
912would be used in a ``.bbappend`` file to modify functions in the main 912would be used in a ``.bbappend`` file to modify functions in the main
913recipe. It can also be used to modify functions inherited from classes. 913recipe. It can also be used to modify functions inherited from classes.
914 914
915As an example, consider the following: :: 915As an example, consider the following::
916 916
917 do_foo() { 917 do_foo() {
918 bbplain first 918 bbplain first
@@ -931,7 +931,7 @@ As an example, consider the following: ::
931 bbplain fourth 931 bbplain fourth
932 } 932 }
933 933
934Running ``do_foo`` prints the following: :: 934Running ``do_foo`` prints the following::
935 935
936 recipename do_foo: first 936 recipename do_foo: first
937 recipename do_foo: second 937 recipename do_foo: second
@@ -952,7 +952,7 @@ BitBake-Style Python Functions
952These functions are written in Python and executed by BitBake or other 952These functions are written in Python and executed by BitBake or other
953Python functions using ``bb.build.exec_func()``. 953Python functions using ``bb.build.exec_func()``.
954 954
955An example BitBake function is: :: 955An example BitBake function is::
956 956
957 python some_python_function () { 957 python some_python_function () {
958 d.setVar("TEXT", "Hello World") 958 d.setVar("TEXT", "Hello World")
@@ -975,7 +975,7 @@ import these modules. Also in these types of functions, the datastore
975Similar to shell functions, you can also apply overrides and 975Similar to shell functions, you can also apply overrides and
976override-style operators to BitBake-style Python functions. 976override-style operators to BitBake-style Python functions.
977 977
978As an example, consider the following: :: 978As an example, consider the following::
979 979
980 python do_foo_prepend() { 980 python do_foo_prepend() {
981 bb.plain("first") 981 bb.plain("first")
@@ -989,7 +989,7 @@ As an example, consider the following: ::
989 bb.plain("third") 989 bb.plain("third")
990 } 990 }
991 991
992Running ``do_foo`` prints the following: :: 992Running ``do_foo`` prints the following::
993 993
994 recipename do_foo: first 994 recipename do_foo: first
995 recipename do_foo: second 995 recipename do_foo: second
@@ -1004,7 +1004,7 @@ Python Functions
1004These functions are written in Python and are executed by other Python 1004These functions are written in Python and are executed by other Python
1005code. Examples of Python functions are utility functions that you intend 1005code. Examples of Python functions are utility functions that you intend
1006to call from in-line Python or from within other Python functions. Here 1006to call from in-line Python or from within other Python functions. Here
1007is an example: :: 1007is an example::
1008 1008
1009 def get_depends(d): 1009 def get_depends(d):
1010 if d.getVar('SOMECONDITION'): 1010 if d.getVar('SOMECONDITION'):
@@ -1056,7 +1056,7 @@ functions and regular Python functions defined with "def":
1056- Regular Python functions are called with the usual Python syntax. 1056- Regular Python functions are called with the usual Python syntax.
1057 BitBake-style Python functions are usually tasks and are called 1057 BitBake-style Python functions are usually tasks and are called
1058 directly by BitBake, but can also be called manually from Python code 1058 directly by BitBake, but can also be called manually from Python code
1059 by using the ``bb.build.exec_func()`` function. Here is an example: :: 1059 by using the ``bb.build.exec_func()`` function. Here is an example::
1060 1060
1061 bb.build.exec_func("my_bitbake_style_function", d) 1061 bb.build.exec_func("my_bitbake_style_function", d)
1062 1062
@@ -1094,7 +1094,7 @@ Sometimes it is useful to set variables or perform other operations
1094programmatically during parsing. To do this, you can define special 1094programmatically during parsing. To do this, you can define special
1095Python functions, called anonymous Python functions, that run at the end 1095Python functions, called anonymous Python functions, that run at the end
1096of parsing. For example, the following conditionally sets a variable 1096of parsing. For example, the following conditionally sets a variable
1097based on the value of another variable: :: 1097based on the value of another variable::
1098 1098
1099 python () { 1099 python () {
1100 if d.getVar('SOMEVAR') == 'value': 1100 if d.getVar('SOMEVAR') == 'value':
@@ -1107,7 +1107,7 @@ the name "__anonymous", rather than no name.
1107Anonymous Python functions always run at the end of parsing, regardless 1107Anonymous Python functions always run at the end of parsing, regardless
1108of where they are defined. If a recipe contains many anonymous 1108of where they are defined. If a recipe contains many anonymous
1109functions, they run in the same order as they are defined within the 1109functions, they run in the same order as they are defined within the
1110recipe. As an example, consider the following snippet: :: 1110recipe. As an example, consider the following snippet::
1111 1111
1112 python () { 1112 python () {
1113 d.setVar('FOO', 'foo 2') 1113 d.setVar('FOO', 'foo 2')
@@ -1122,7 +1122,7 @@ recipe. As an example, consider the following snippet: ::
1122 BAR = "bar 1" 1122 BAR = "bar 1"
1123 1123
1124The previous example is conceptually 1124The previous example is conceptually
1125equivalent to the following snippet: :: 1125equivalent to the following snippet::
1126 1126
1127 FOO = "foo 1" 1127 FOO = "foo 1"
1128 BAR = "bar 1" 1128 BAR = "bar 1"
@@ -1136,7 +1136,7 @@ available to tasks, which always run after parsing.
1136 1136
1137Overrides and override-style operators such as "``_append``" are applied 1137Overrides and override-style operators such as "``_append``" are applied
1138before anonymous functions run. In the following example, ``FOO`` ends 1138before anonymous functions run. In the following example, ``FOO`` ends
1139up with the value "foo from anonymous": :: 1139up with the value "foo from anonymous"::
1140 1140
1141 FOO = "foo" 1141 FOO = "foo"
1142 FOO_append = " from outside" 1142 FOO_append = " from outside"
@@ -1173,24 +1173,24 @@ version of the function.
1173 1173
1174To make use of this technique, you need the following things in place: 1174To make use of this technique, you need the following things in place:
1175 1175
1176- The class needs to define the function as follows: :: 1176- The class needs to define the function as follows::
1177 1177
1178 classname_functionname 1178 classname_functionname
1179 1179
1180 For example, if you have a class file 1180 For example, if you have a class file
1181 ``bar.bbclass`` and a function named ``do_foo``, the class must 1181 ``bar.bbclass`` and a function named ``do_foo``, the class must
1182 define the function as follows: :: 1182 define the function as follows::
1183 1183
1184 bar_do_foo 1184 bar_do_foo
1185 1185
1186- The class needs to contain the ``EXPORT_FUNCTIONS`` statement as 1186- The class needs to contain the ``EXPORT_FUNCTIONS`` statement as
1187 follows: :: 1187 follows::
1188 1188
1189 EXPORT_FUNCTIONS functionname 1189 EXPORT_FUNCTIONS functionname
1190 1190
1191 For example, continuing with 1191 For example, continuing with
1192 the same example, the statement in the ``bar.bbclass`` would be as 1192 the same example, the statement in the ``bar.bbclass`` would be as
1193 follows: :: 1193 follows::
1194 1194
1195 EXPORT_FUNCTIONS do_foo 1195 EXPORT_FUNCTIONS do_foo
1196 1196
@@ -1199,7 +1199,7 @@ To make use of this technique, you need the following things in place:
1199 class version of the function, it should call ``bar_do_foo``. 1199 class version of the function, it should call ``bar_do_foo``.
1200 Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was 1200 Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was
1201 used as above, the recipe's function could conditionally call the 1201 used as above, the recipe's function could conditionally call the
1202 class version of the function as follows: :: 1202 class version of the function as follows::
1203 1203
1204 do_foo() { 1204 do_foo() {
1205 if [ somecondition ] ; then 1205 if [ somecondition ] ; then
@@ -1233,7 +1233,7 @@ Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual-
1233that have been promoted to tasks by using the ``addtask`` command. The 1233that have been promoted to tasks by using the ``addtask`` command. The
1234``addtask`` command can also optionally describe dependencies between 1234``addtask`` command can also optionally describe dependencies between
1235the task and other tasks. Here is an example that shows how to define a 1235the task and other tasks. Here is an example that shows how to define a
1236task and declare some dependencies: :: 1236task and declare some dependencies::
1237 1237
1238 python do_printdate () { 1238 python do_printdate () {
1239 import time 1239 import time
@@ -1264,12 +1264,12 @@ Additionally, the ``do_printdate`` task becomes dependent upon the
1264 rerun for experimentation purposes, you can make BitBake always 1264 rerun for experimentation purposes, you can make BitBake always
1265 consider the task "out-of-date" by using the 1265 consider the task "out-of-date" by using the
1266 :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` 1266 :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>`
1267 variable flag, as follows: :: 1267 variable flag, as follows::
1268 1268
1269 do_printdate[nostamp] = "1" 1269 do_printdate[nostamp] = "1"
1270 1270
1271 You can also explicitly run the task and provide the 1271 You can also explicitly run the task and provide the
1272 -f option as follows: :: 1272 -f option as follows::
1273 1273
1274 $ bitbake recipe -c printdate -f 1274 $ bitbake recipe -c printdate -f
1275 1275
@@ -1278,7 +1278,7 @@ Additionally, the ``do_printdate`` task becomes dependent upon the
1278 name. 1278 name.
1279 1279
1280You might wonder about the practical effects of using ``addtask`` 1280You might wonder about the practical effects of using ``addtask``
1281without specifying any dependencies as is done in the following example: :: 1281without specifying any dependencies as is done in the following example::
1282 1282
1283 addtask printdate 1283 addtask printdate
1284 1284
@@ -1286,7 +1286,7 @@ In this example, assuming dependencies have not been
1286added through some other means, the only way to run the task is by 1286added through some other means, the only way to run the task is by
1287explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You 1287explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You
1288can use the ``do_listtasks`` task to list all tasks defined in a recipe 1288can use the ``do_listtasks`` task to list all tasks defined in a recipe
1289as shown in the following example: :: 1289as shown in the following example::
1290 1290
1291 $ bitbake recipe -c listtasks 1291 $ bitbake recipe -c listtasks
1292 1292
@@ -1312,7 +1312,7 @@ Deleting a Task
1312 1312
1313As well as being able to add tasks, you can delete them. Simply use the 1313As well as being able to add tasks, you can delete them. Simply use the
1314``deltask`` command to delete a task. For example, to delete the example 1314``deltask`` command to delete a task. For example, to delete the example
1315task used in the previous sections, you would use: :: 1315task used in the previous sections, you would use::
1316 1316
1317 deltask printdate 1317 deltask printdate
1318 1318
@@ -1328,7 +1328,7 @@ to run before ``do_a``.
1328 1328
1329If you want dependencies such as these to remain intact, use the 1329If you want dependencies such as these to remain intact, use the
1330``[noexec]`` varflag to disable the task instead of using the 1330``[noexec]`` varflag to disable the task instead of using the
1331``deltask`` command to delete it: :: 1331``deltask`` command to delete it::
1332 1332
1333 do_b[noexec] = "1" 1333 do_b[noexec] = "1"
1334 1334
@@ -1356,7 +1356,7 @@ environment, you must take these two steps:
1356 example, assume you want to prevent the build system from accessing 1356 example, assume you want to prevent the build system from accessing
1357 your ``$HOME/.ccache`` directory. The following command "whitelists" 1357 your ``$HOME/.ccache`` directory. The following command "whitelists"
1358 the environment variable ``CCACHE_DIR`` causing BitBake to allow that 1358 the environment variable ``CCACHE_DIR`` causing BitBake to allow that
1359 variable into the datastore: :: 1359 variable into the datastore::
1360 1360
1361 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" 1361 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1362 1362
@@ -1366,7 +1366,7 @@ environment, you must take these two steps:
1366 available in the datastore. To export it to the task environment of 1366 available in the datastore. To export it to the task environment of
1367 every running task, use a command similar to the following in your 1367 every running task, use a command similar to the following in your
1368 local configuration file ``local.conf`` or your distribution 1368 local configuration file ``local.conf`` or your distribution
1369 configuration file: :: 1369 configuration file::
1370 1370
1371 export CCACHE_DIR 1371 export CCACHE_DIR
1372 1372
@@ -1385,7 +1385,7 @@ environment into a special variable named :term:`BB_ORIGENV`.
1385The ``BB_ORIGENV`` variable returns a datastore object that can be 1385The ``BB_ORIGENV`` variable returns a datastore object that can be
1386queried using the standard datastore operators such as 1386queried using the standard datastore operators such as
1387``getVar(, False)``. The datastore object is useful, for example, to 1387``getVar(, False)``. The datastore object is useful, for example, to
1388find the original ``DISPLAY`` variable. Here is an example: :: 1388find the original ``DISPLAY`` variable. Here is an example::
1389 1389
1390 origenv = d.getVar("BB_ORIGENV", False) 1390 origenv = d.getVar("BB_ORIGENV", False)
1391 bar = origenv.getVar("BAR", False) 1391 bar = origenv.getVar("BAR", False)
@@ -1398,7 +1398,7 @@ Variable Flags
1398 1398
1399Variable flags (varflags) help control a task's functionality and 1399Variable flags (varflags) help control a task's functionality and
1400dependencies. BitBake reads and writes varflags to the datastore using 1400dependencies. BitBake reads and writes varflags to the datastore using
1401the following command forms: :: 1401the following command forms::
1402 1402
1403 variable = d.getVarFlags("variable") 1403 variable = d.getVarFlags("variable")
1404 self.d.setVarFlags("FOO", {"func": True}) 1404 self.d.setVarFlags("FOO", {"func": True})
@@ -1537,7 +1537,7 @@ intent is to make it easy to do things like email notification on build
1537failures. 1537failures.
1538 1538
1539Following is an example event handler that prints the name of the event 1539Following is an example event handler that prints the name of the event
1540and the content of the ``FILE`` variable: :: 1540and the content of the ``FILE`` variable::
1541 1541
1542 addhandler myclass_eventhandler 1542 addhandler myclass_eventhandler
1543 python myclass_eventhandler() { 1543 python myclass_eventhandler() {
@@ -1676,7 +1676,7 @@ incarnations are buildable. These features are enabled through the
1676 also specify conditional metadata (using the 1676 also specify conditional metadata (using the
1677 :term:`OVERRIDES` mechanism) for a single 1677 :term:`OVERRIDES` mechanism) for a single
1678 version, or an optionally named range of versions. Here is an 1678 version, or an optionally named range of versions. Here is an
1679 example: :: 1679 example::
1680 1680
1681 BBVERSIONS = "1.0 2.0 git" 1681 BBVERSIONS = "1.0 2.0 git"
1682 SRC_URI_git = "git://someurl/somepath.git" 1682 SRC_URI_git = "git://someurl/somepath.git"
@@ -1719,7 +1719,7 @@ Dependencies Internal to the ``.bb`` File
1719BitBake uses the ``addtask`` directive to manage dependencies that are 1719BitBake uses the ``addtask`` directive to manage dependencies that are
1720internal to a given recipe file. You can use the ``addtask`` directive 1720internal to a given recipe file. You can use the ``addtask`` directive
1721to indicate when a task is dependent on other tasks or when other tasks 1721to indicate when a task is dependent on other tasks or when other tasks
1722depend on that recipe. Here is an example: :: 1722depend on that recipe. Here is an example::
1723 1723
1724 addtask printdate after do_fetch before do_build 1724 addtask printdate after do_fetch before do_build
1725 1725
@@ -1743,7 +1743,7 @@ task depends on the completion of the ``do_printdate`` task.
1743 1743
1744 - The directive ``addtask mytask after do_configure`` by itself 1744 - The directive ``addtask mytask after do_configure`` by itself
1745 never causes ``do_mytask`` to run. ``do_mytask`` can still be run 1745 never causes ``do_mytask`` to run. ``do_mytask`` can still be run
1746 manually as follows: :: 1746 manually as follows::
1747 1747
1748 $ bitbake recipe -c mytask 1748 $ bitbake recipe -c mytask
1749 1749
@@ -1757,7 +1757,7 @@ Build Dependencies
1757BitBake uses the :term:`DEPENDS` variable to manage 1757BitBake uses the :term:`DEPENDS` variable to manage
1758build time dependencies. The ``[deptask]`` varflag for tasks signifies 1758build time dependencies. The ``[deptask]`` varflag for tasks signifies
1759the task of each item listed in ``DEPENDS`` that must complete before 1759the task of each item listed in ``DEPENDS`` that must complete before
1760that task can be executed. Here is an example: :: 1760that task can be executed. Here is an example::
1761 1761
1762 do_configure[deptask] = "do_populate_sysroot" 1762 do_configure[deptask] = "do_populate_sysroot"
1763 1763
@@ -1799,7 +1799,7 @@ dependencies are discovered and added.
1799 1799
1800The ``[recrdeptask]`` flag is most commonly used in high-level recipes 1800The ``[recrdeptask]`` flag is most commonly used in high-level recipes
1801that need to wait for some task to finish "globally". For example, 1801that need to wait for some task to finish "globally". For example,
1802``image.bbclass`` has the following: :: 1802``image.bbclass`` has the following::
1803 1803
1804 do_rootfs[recrdeptask] += "do_packagedata" 1804 do_rootfs[recrdeptask] += "do_packagedata"
1805 1805
@@ -1808,7 +1808,7 @@ the current recipe and all recipes reachable (by way of dependencies)
1808from the image recipe must run before the ``do_rootfs`` task can run. 1808from the image recipe must run before the ``do_rootfs`` task can run.
1809 1809
1810BitBake allows a task to recursively depend on itself by 1810BitBake allows a task to recursively depend on itself by
1811referencing itself in the task list: :: 1811referencing itself in the task list::
1812 1812
1813 do_a[recrdeptask] = "do_a do_b" 1813 do_a[recrdeptask] = "do_a do_b"
1814 1814
@@ -1825,7 +1825,7 @@ Inter-Task Dependencies
1825BitBake uses the ``[depends]`` flag in a more generic form to manage 1825BitBake uses the ``[depends]`` flag in a more generic form to manage
1826inter-task dependencies. This more generic form allows for 1826inter-task dependencies. This more generic form allows for
1827inter-dependency checks for specific tasks rather than checks for the 1827inter-dependency checks for specific tasks rather than checks for the
1828data in ``DEPENDS``. Here is an example: :: 1828data in ``DEPENDS``. Here is an example::
1829 1829
1830 do_patch[depends] = "quilt-native:do_populate_sysroot" 1830 do_patch[depends] = "quilt-native:do_populate_sysroot"
1831 1831
@@ -1920,7 +1920,7 @@ To help understand how BitBake does this, the section assumes an
1920OpenEmbedded metadata-based example. 1920OpenEmbedded metadata-based example.
1921 1921
1922These checksums are stored in :term:`STAMP`. You can 1922These checksums are stored in :term:`STAMP`. You can
1923examine the checksums using the following BitBake command: :: 1923examine the checksums using the following BitBake command::
1924 1924
1925 $ bitbake-dumpsigs 1925 $ bitbake-dumpsigs
1926 1926