1.. SPDX-License-Identifier: CC-BY-2.5 2 3==================== 4Syntax and Operators 5==================== 6 7| 8 9BitBake files have their own syntax. The syntax has similarities to 10several other languages but also has some unique features. This section 11describes the available syntax and operators as well as provides 12examples. 13 14Basic Syntax 15============ 16 17This section provides some basic syntax examples. 18 19Basic Variable Setting 20---------------------- 21 22The following example sets ``VARIABLE`` to "value". This assignment 23occurs immediately as the statement is parsed. It is a "hard" 24assignment. :: 25 26 VARIABLE = "value" 27 28As expected, if you include leading or 29trailing spaces as part of an assignment, the spaces are retained:: 30 31 VARIABLE = " value" 32 VARIABLE = "value " 33 34Setting ``VARIABLE`` to "" sets 35it to an empty string, while setting the variable to " " sets it to a 36blank space (i.e. these are not the same values). :: 37 38 VARIABLE = "" 39 VARIABLE = " " 40 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 43double quote character:: 44 45 VARIABLE = 'I have a " in my value' 46 47.. note:: 48 49 Unlike in Bourne shells, single quotes work identically to double 50 quotes in all other ways. They do not suppress variable expansions. 51 52Modifying Existing Variables 53---------------------------- 54 55Sometimes you need to modify existing variables. Following are some 56cases where you might find you want to modify an existing variable: 57 58- Customize a recipe that uses the variable. 59 60- Change a variable's default value used in a ``*.bbclass`` file. 61 62- Change the variable in a ``*.bbappend`` file to override the variable 63 in the original recipe. 64 65- Change the variable in a configuration file so that the value 66 overrides an existing configuration. 67 68Changing a variable value can sometimes depend on how the value was 69originally assigned and also on the desired intent of the change. In 70particular, when you append a value to a variable that has a default 71value, the resulting value might not be what you expect. In this case, 72the value you provide might replace the value rather than append to the 73default value. 74 75If after you have changed a variable's value and something unexplained 76occurs, you can use BitBake to check the actual value of the suspect 77variable. You can make these checks for both configuration and recipe 78level changes: 79 80- For configuration changes, use the following:: 81 82 $ bitbake -e 83 84 This 85 command displays variable values after the configuration files (i.e. 86 ``local.conf``, ``bblayers.conf``, ``bitbake.conf`` and so forth) 87 have been parsed. 88 89 .. note:: 90 91 Variables that are exported to the environment are preceded by the 92 string "export" in the command's output. 93 94- To find changes to a given variable in a specific recipe, use the 95 following:: 96 97 $ bitbake recipename -e | grep VARIABLENAME=\" 98 99 This command checks to see if the variable actually makes 100 it into a specific recipe. 101 102Line Joining 103------------ 104 105Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`, 106BitBake joins any line ending in 107a backslash character ("\\") with the following line before parsing 108statements. The most common use for the "\\" character is to split 109variable assignments over multiple lines, as in the following example:: 110 111 FOO = "bar \ 112 baz \ 113 qaz" 114 115Both the "\\" character and the newline 116character that follow it are removed when joining lines. Thus, no 117newline characters end up in the value of ``FOO``. 118 119Consider this additional example where the two assignments both assign 120"barbaz" to ``FOO``:: 121 122 FOO = "barbaz" 123 FOO = "bar\ 124 baz" 125 126.. note:: 127 128 BitBake does not interpret escape sequences like "\\n" in variable 129 values. For these to have an effect, the value must be passed to some 130 utility that interprets escape sequences, such as 131 ``printf`` or ``echo -n``. 132 133Variable Expansion 134------------------ 135 136Variables can reference the contents of other variables using a syntax 137that is similar to variable expansion in Bourne shells. The following 138assignments result in A containing "aval" and B evaluating to 139"preavalpost". :: 140 141 A = "aval" 142 B = "pre${A}post" 143 144.. note:: 145 146 Unlike in Bourne shells, the curly braces are mandatory: Only ``${FOO}`` and not 147 ``$FOO`` is recognized as an expansion of ``FOO``. 148 149The "=" operator does not immediately expand variable references in the 150right-hand side. Instead, expansion is deferred until the variable 151assigned to is actually used. The result depends on the current values 152of the referenced variables. The following example should clarify this 153behavior:: 154 155 A = "${B} baz" 156 B = "${C} bar" 157 C = "foo" 158 *At this point, ${A} equals "foo bar baz"* 159 C = "qux" 160 *At this point, ${A} equals "qux bar baz"* 161 B = "norf" 162 *At this point, ${A} equals "norf baz"* 163 164Contrast this behavior with the 165:ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable 166expansion (:=)` operator. 167 168If the variable expansion syntax is used on a variable that does not 169exist, the string is kept as is. For example, given the following 170assignment, ``BAR`` expands to the literal string "${FOO}" as long as 171``FOO`` does not exist. :: 172 173 BAR = "${FOO}" 174 175Setting a default value (?=) 176---------------------------- 177 178You can use the "?=" operator to achieve a "softer" assignment for a 179variable. This type of assignment allows you to define a variable if it 180is undefined when the statement is parsed, but to leave the value alone 181if the variable has a value. Here is an example:: 182 183 A ?= "aval" 184 185If ``A`` is 186set at the time this statement is parsed, the variable retains its 187value. However, if ``A`` is not set, the variable is set to "aval". 188 189.. note:: 190 191 This assignment is immediate. Consequently, if multiple "?=" 192 assignments to a single variable exist, the first of those ends up 193 getting used. 194 195Setting a weak default value (??=) 196---------------------------------- 197 198The weak default value of a variable is the value which that variable 199will expand to if no value has been assigned to it via any of the other 200assignment operators. The "??=" operator takes effect immediately, replacing 201any previously defined weak default value. Here is an example:: 202 203 W ??= "x" 204 A := "${W}" # Immediate variable expansion 205 W ??= "y" 206 B := "${W}" # Immediate variable expansion 207 W ??= "z" 208 C = "${W}" 209 W ?= "i" 210 211After parsing we will have:: 212 213 A = "x" 214 B = "y" 215 C = "i" 216 W = "i" 217 218Appending and prepending non-override style will not substitute the weak 219default value, which means that after parsing:: 220 221 W ??= "x" 222 W += "y" 223 224we will have:: 225 226 W = " y" 227 228On the other hand, override-style appends/prepends/removes are applied after 229any active weak default value has been substituted:: 230 231 W ??= "x" 232 W:append = "y" 233 234After parsing we will have:: 235 236 W = "xy" 237 238Immediate variable expansion (:=) 239--------------------------------- 240 241The ":=" operator results in a variable's contents being expanded 242immediately, rather than when the variable is actually used:: 243 244 T = "123" 245 A := "test ${T}" 246 T = "456" 247 B := "${T} ${C}" 248 C = "cval" 249 C := "${C}append" 250 251In this example, ``A`` contains "test 123", even though the final value 252of :term:`T` is "456". The variable :term:`B` will end up containing "456 253cvalappend". This is because references to undefined variables are 254preserved as is during (immediate)expansion. This is in contrast to GNU 255Make, where undefined variables expand to nothing. The variable ``C`` 256contains "cvalappend" since ``${C}`` immediately expands to "cval". 257 258.. _appending-and-prepending: 259 260Appending (+=) and prepending (=+) With Spaces 261---------------------------------------------- 262 263Appending and prepending values is common and can be accomplished using 264the "+=" and "=+" operators. These operators insert a space between the 265current value and prepended or appended value. 266 267These operators take immediate effect during parsing. Here are some 268examples:: 269 270 B = "bval" 271 B += "additionaldata" 272 C = "cval" 273 C =+ "test" 274 275The variable :term:`B` contains "bval additionaldata" and ``C`` contains "test 276cval". 277 278.. _appending-and-prepending-without-spaces: 279 280Appending (.=) and Prepending (=.) Without Spaces 281------------------------------------------------- 282 283If you want to append or prepend values without an inserted space, use 284the ".=" and "=." operators. 285 286These operators take immediate effect during parsing. Here are some 287examples:: 288 289 B = "bval" 290 B .= "additionaldata" 291 C = "cval" 292 C =. "test" 293 294The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains 295"testcval". 296 297Appending and Prepending (Override Style Syntax) 298------------------------------------------------ 299 300You can also append and prepend a variable's value using an override 301style syntax. When you use this syntax, no spaces are inserted. 302 303These operators differ from the ":=", ".=", "=.", "+=", and "=+" 304operators in that their effects are applied at variable expansion time 305rather than being immediately applied. Here are some examples:: 306 307 B = "bval" 308 B:append = " additional data" 309 C = "cval" 310 C:prepend = "additional data " 311 D = "dval" 312 D:append = "additional data" 313 314The variable :term:`B` 315becomes "bval additional data" and ``C`` becomes "additional data cval". 316The variable ``D`` becomes "dvaladditional data". 317 318.. note:: 319 320 You must control all spacing when you use the override syntax. 321 322It is also possible to append and prepend to shell functions and 323BitBake-style Python functions. See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:shell functions`" and ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions`" 324sections for examples. 325 326.. _removing-override-style-syntax: 327 328Removal (Override Style Syntax) 329------------------------------- 330 331You can remove values from lists using the removal override style 332syntax. Specifying a value for removal causes all occurrences of that 333value to be removed from the variable. 334 335When you use this syntax, BitBake expects one or more strings. 336Surrounding spaces and spacing are preserved. Here is an example:: 337 338 FOO = "123 456 789 123456 123 456 123 456" 339 FOO:remove = "123" 340 FOO:remove = "456" 341 FOO2 = " abc def ghi abcdef abc def abc def def" 342 FOO2:remove = "\ 343 def \ 344 abc \ 345 ghi \ 346 " 347 348The variable ``FOO`` becomes 349" 789 123456 " and ``FOO2`` becomes " abcdef ". 350 351Like ":append" and ":prepend", ":remove" is applied at variable 352expansion time. 353 354Override Style Operation Advantages 355----------------------------------- 356 357An advantage of the override style operations ":append", ":prepend", and 358":remove" as compared to the "+=" and "=+" operators is that the 359override style operators provide guaranteed operations. For example, 360consider a class ``foo.bbclass`` that needs to add the value "val" to 361the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows:: 362 363 inherit foo 364 FOO = "initial" 365 366If ``foo.bbclass`` uses the "+=" operator, 367as follows, then the final value of ``FOO`` will be "initial", which is 368not what is desired:: 369 370 FOO += "val" 371 372If, on the other hand, ``foo.bbclass`` 373uses the ":append" operator, then the final value of ``FOO`` will be 374"initial val", as intended:: 375 376 FOO:append = " val" 377 378.. note:: 379 380 It is never necessary to use "+=" together with ":append". The following 381 sequence of assignments appends "barbaz" to FOO:: 382 383 FOO:append = "bar" 384 FOO:append = "baz" 385 386 387 The only effect of changing the second assignment in the previous 388 example to use "+=" would be to add a space before "baz" in the 389 appended value (due to how the "+=" operator works). 390 391Another advantage of the override style operations is that you can 392combine them with other overrides as described in the 393":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" section. 394 395Variable Flag Syntax 396-------------------- 397 398Variable flags are BitBake's implementation of variable properties or 399attributes. It is a way of tagging extra information onto a variable. 400You can find more out about variable flags in general in the 401":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section. 402 403You can define, append, and prepend values to variable flags. All the 404standard syntax operations previously mentioned work for variable flags 405except for override style syntax (i.e. ":prepend", ":append", and 406":remove"). 407 408Here are some examples showing how to set variable flags:: 409 410 FOO[a] = "abc" 411 FOO[b] = "123" 412 FOO[a] += "456" 413 414The variable ``FOO`` has two flags: 415``[a]`` and ``[b]``. The flags are immediately set to "abc" and "123", 416respectively. The ``[a]`` flag becomes "abc 456". 417 418No need exists to pre-define variable flags. You can simply start using 419them. One extremely common application is to attach some brief 420documentation to a BitBake variable as follows:: 421 422 CACHE[doc] = "The directory holding the cache of the metadata." 423 424Inline Python Variable Expansion 425-------------------------------- 426 427You can use inline Python variable expansion to set variables. Here is 428an example:: 429 430 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" 431 432This example results in the ``DATE`` variable being set to the current date. 433 434Probably the most common use of this feature is to extract the value of 435variables from BitBake's internal data dictionary, ``d``. The following 436lines select the values of a package name and its version number, 437respectively:: 438 439 PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" 440 PV = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" 441 442.. note:: 443 444 Inline Python expressions work just like variable expansions insofar as the 445 "=" and ":=" operators are concerned. Given the following assignment, foo() 446 is called each time FOO is expanded:: 447 448 FOO = "${@foo()}" 449 450 Contrast this with the following immediate assignment, where foo() is only 451 called once, while the assignment is parsed:: 452 453 FOO := "${@foo()}" 454 455For a different way to set variables with Python code during parsing, 456see the 457":ref:`bitbake-user-manual/bitbake-user-manual-metadata:anonymous python functions`" section. 458 459Unsetting variables 460------------------- 461 462It is possible to completely remove a variable or a variable flag from 463BitBake's internal data dictionary by using the "unset" keyword. Here is 464an example:: 465 466 unset DATE 467 unset do_fetch[noexec] 468 469These two statements remove the ``DATE`` and the ``do_fetch[noexec]`` flag. 470 471Providing Pathnames 472------------------- 473 474When specifying pathnames for use with BitBake, do not use the tilde 475("~") character as a shortcut for your home directory. Doing so might 476cause BitBake to not recognize the path since BitBake does not expand 477this character in the same way a shell would. 478 479Instead, provide a fuller path as the following example illustrates:: 480 481 BBLAYERS ?= " \ 482 /home/scott-lenovo/LayerA \ 483 " 484 485Exporting Variables to the Environment 486====================================== 487 488You can export variables to the environment of running tasks by using 489the ``export`` keyword. For example, in the following example, the 490``do_foo`` task prints "value from the environment" when run:: 491 492 export ENV_VARIABLE 493 ENV_VARIABLE = "value from the environment" 494 495 do_foo() { 496 bbplain "$ENV_VARIABLE" 497 } 498 499.. note:: 500 501 BitBake does not expand ``$ENV_VARIABLE`` in this case because it lacks the 502 obligatory ``{}`` . Rather, ``$ENV_VARIABLE`` is expanded by the shell. 503 504It does not matter whether ``export ENV_VARIABLE`` appears before or 505after assignments to ``ENV_VARIABLE``. 506 507It is also possible to combine ``export`` with setting a value for the 508variable. Here is an example:: 509 510 export ENV_VARIABLE = "variable-value" 511 512In the output of ``bitbake -e``, variables that are exported to the 513environment are preceded by "export". 514 515Among the variables commonly exported to the environment are ``CC`` and 516``CFLAGS``, which are picked up by many build systems. 517 518Conditional Syntax (Overrides) 519============================== 520 521BitBake uses :term:`OVERRIDES` to control what 522variables are overridden after BitBake parses recipes and configuration 523files. This section describes how you can use :term:`OVERRIDES` as 524conditional metadata, talks about key expansion in relationship to 525:term:`OVERRIDES`, and provides some examples to help with understanding. 526 527Conditional Metadata 528-------------------- 529 530You can use :term:`OVERRIDES` to conditionally select a specific version of 531a variable and to conditionally append or prepend the value of a 532variable. 533 534.. note:: 535 536 Overrides can only use lower-case characters, digits and dashes. 537 In particular, colons are not permitted in override names as they are used to 538 separate overrides from each other and from the variable name. 539 540- *Selecting a Variable:* The :term:`OVERRIDES` variable is a 541 colon-character-separated list that contains items for which you want 542 to satisfy conditions. Thus, if you have a variable that is 543 conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the 544 "arm"-specific version of the variable is used rather than the 545 non-conditional version. Here is an example:: 546 547 OVERRIDES = "architecture:os:machine" 548 TEST = "default" 549 TEST:os = "osspecific" 550 TEST:nooverride = "othercondvalue" 551 552 In this example, the :term:`OVERRIDES` 553 variable lists three overrides: "architecture", "os", and "machine". 554 The variable ``TEST`` by itself has a default value of "default". You 555 select the os-specific version of the ``TEST`` variable by appending 556 the "os" override to the variable (i.e. ``TEST:os``). 557 558 To better understand this, consider a practical example that assumes 559 an OpenEmbedded metadata-based Linux kernel recipe file. The 560 following lines from the recipe file first set the kernel branch 561 variable ``KBRANCH`` to a default value, then conditionally override 562 that value based on the architecture of the build:: 563 564 KBRANCH = "standard/base" 565 KBRANCH:qemuarm = "standard/arm-versatile-926ejs" 566 KBRANCH:qemumips = "standard/mti-malta32" 567 KBRANCH:qemuppc = "standard/qemuppc" 568 KBRANCH:qemux86 = "standard/common-pc/base" 569 KBRANCH:qemux86-64 = "standard/common-pc-64/base" 570 KBRANCH:qemumips64 = "standard/mti-malta64" 571 572- *Appending and Prepending:* BitBake also supports append and prepend 573 operations to variable values based on whether a specific item is 574 listed in :term:`OVERRIDES`. Here is an example:: 575 576 DEPENDS = "glibc ncurses" 577 OVERRIDES = "machine:local" 578 DEPENDS:append:machine = "libmad" 579 580 In this example, :term:`DEPENDS` becomes "glibc ncurses libmad". 581 582 Again, using an OpenEmbedded metadata-based kernel recipe file as an 583 example, the following lines will conditionally append to the 584 ``KERNEL_FEATURES`` variable based on the architecture:: 585 586 KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" 587 KERNEL_FEATURES:append:qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" 588 KERNEL_FEATURES:append:qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" 589 590- *Setting a Variable for a Single Task:* BitBake supports setting a 591 variable just for the duration of a single task. Here is an example:: 592 593 FOO:task-configure = "val 1" 594 FOO:task-compile = "val 2" 595 596 In the 597 previous example, ``FOO`` has the value "val 1" while the 598 ``do_configure`` task is executed, and the value "val 2" while the 599 ``do_compile`` task is executed. 600 601 Internally, this is implemented by prepending the task (e.g. 602 "task-compile:") to the value of 603 :term:`OVERRIDES` for the local datastore of the 604 ``do_compile`` task. 605 606 You can also use this syntax with other combinations (e.g. 607 "``:prepend``") as shown in the following example:: 608 609 EXTRA_OEMAKE:prepend:task-compile = "${PARALLEL_MAKE} " 610 611.. note:: 612 613 Before BitBake 1.52 (Honister 3.4), the syntax for :term:`OVERRIDES` 614 used ``_`` instead of ``:``, so you will still find a lot of documentation 615 using ``_append``, ``_prepend``, and ``_remove``, for example. 616 617 For details, see the 618 :yocto_docs:`Overrides Syntax Changes </migration-guides/migration-3.4.html#override-syntax-changes>` 619 section in the Yocto Project manual migration notes. 620 621Key Expansion 622------------- 623 624Key expansion happens when the BitBake datastore is finalized. To better 625understand this, consider the following example:: 626 627 A${B} = "X" 628 B = "2" 629 A2 = "Y" 630 631In this case, after all the parsing is complete, BitBake expands 632``${B}`` into "2". This expansion causes ``A2``, which was set to "Y" 633before the expansion, to become "X". 634 635.. _variable-interaction-worked-examples: 636 637Examples 638-------- 639 640Despite the previous explanations that show the different forms of 641variable definitions, it can be hard to work out exactly what happens 642when variable operators, conditional overrides, and unconditional 643overrides are combined. This section presents some common scenarios 644along with explanations for variable interactions that typically confuse 645users. 646 647There is often confusion concerning the order in which overrides and 648various "append" operators take effect. Recall that an append or prepend 649operation using ":append" and ":prepend" does not result in an immediate 650assignment as would "+=", ".=", "=+", or "=.". Consider the following 651example:: 652 653 OVERRIDES = "foo" 654 A = "Z" 655 A:foo:append = "X" 656 657For this case, 658``A`` is unconditionally set to "Z" and "X" is unconditionally and 659immediately appended to the variable ``A:foo``. Because overrides have 660not been applied yet, ``A:foo`` is set to "X" due to the append and 661``A`` simply equals "Z". 662 663Applying overrides, however, changes things. Since "foo" is listed in 664:term:`OVERRIDES`, the conditional variable ``A`` is replaced with the "foo" 665version, which is equal to "X". So effectively, ``A:foo`` replaces 666``A``. 667 668This next example changes the order of the override and the append:: 669 670 OVERRIDES = "foo" 671 A = "Z" 672 A:append:foo = "X" 673 674For this case, before 675overrides are handled, ``A`` is set to "Z" and ``A:append:foo`` is set 676to "X". Once the override for "foo" is applied, however, ``A`` gets 677appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces 678are not appended. 679 680This next example has the order of the appends and overrides reversed 681back as in the first example:: 682 683 OVERRIDES = "foo" 684 A = "Y" 685 A:foo:append = "Z" 686 A:foo:append = "X" 687 688For this case, before any overrides are resolved, 689``A`` is set to "Y" using an immediate assignment. After this immediate 690assignment, ``A:foo`` is set to "Z", and then further appended with "X" 691leaving the variable set to "ZX". Finally, applying the override for 692"foo" results in the conditional variable ``A`` becoming "ZX" (i.e. 693``A`` is replaced with ``A:foo``). 694 695This final example mixes in some varying operators:: 696 697 A = "1" 698 A:append = "2" 699 A:append = "3" 700 A += "4" 701 A .= "5" 702 703For this case, the type of append 704operators are affecting the order of assignments as BitBake passes 705through the code multiple times. Initially, ``A`` is set to "1 45" 706because of the three statements that use immediate operators. After 707these assignments are made, BitBake applies the ":append" operations. 708Those operations result in ``A`` becoming "1 4523". 709 710Sharing Functionality 711===================== 712 713BitBake allows for metadata sharing through include files (``.inc``) and 714class files (``.bbclass``). For example, suppose you have a piece of 715common functionality such as a task definition that you want to share 716between more than one recipe. In this case, creating a ``.bbclass`` file 717that contains the common functionality and then using the ``inherit`` 718directive in your recipes to inherit the class would be a common way to 719share the task. 720 721This section presents the mechanisms BitBake provides to allow you to 722share functionality between recipes. Specifically, the mechanisms 723include ``include``, ``inherit``, :term:`INHERIT`, and ``require`` 724directives. 725 726Locating Include and Class Files 727-------------------------------- 728 729BitBake uses the :term:`BBPATH` variable to locate 730needed include and class files. Additionally, BitBake searches the 731current directory for ``include`` and ``require`` directives. 732 733.. note:: 734 735 The BBPATH variable is analogous to the environment variable PATH . 736 737In order for include and class files to be found by BitBake, they need 738to be located in a "classes" subdirectory that can be found in 739:term:`BBPATH`. 740 741``inherit`` Directive 742--------------------- 743 744When writing a recipe or class file, you can use the ``inherit`` 745directive to inherit the functionality of a class (``.bbclass``). 746BitBake only supports this directive when used within recipe and class 747files (i.e. ``.bb`` and ``.bbclass``). 748 749The ``inherit`` directive is a rudimentary means of specifying 750functionality contained in class files that your recipes require. For 751example, you can easily abstract out the tasks involved in building a 752package that uses Autoconf and Automake and put those tasks into a class 753file and then have your recipe inherit that class file. 754 755As an example, your recipes could use the following directive to inherit 756an ``autotools.bbclass`` file. The class file would contain common 757functionality for using Autotools that could be shared across recipes:: 758 759 inherit autotools 760 761In this case, BitBake would search for the directory 762``classes/autotools.bbclass`` in :term:`BBPATH`. 763 764.. note:: 765 766 You can override any values and functions of the inherited class 767 within your recipe by doing so after the "inherit" statement. 768 769If you want to use the directive to inherit multiple classes, separate 770them with spaces. The following example shows how to inherit both the 771``buildhistory`` and ``rm_work`` classes:: 772 773 inherit buildhistory rm_work 774 775An advantage with the inherit directive as compared to both the 776:ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` 777directives is that you can inherit class files conditionally. You can 778accomplish this by using a variable expression after the ``inherit`` 779statement. Here is an example:: 780 781 inherit ${VARNAME} 782 783If ``VARNAME`` is 784going to be set, it needs to be set before the ``inherit`` statement is 785parsed. One way to achieve a conditional inherit in this case is to use 786overrides:: 787 788 VARIABLE = "" 789 VARIABLE:someoverride = "myclass" 790 791Another method is by using anonymous Python. Here is an example:: 792 793 python () { 794 if condition == value: 795 d.setVar('VARIABLE', 'myclass') 796 else: 797 d.setVar('VARIABLE', '') 798 } 799 800Alternatively, you could use an in-line Python expression in the 801following form:: 802 803 inherit ${@'classname' if condition else ''} 804 inherit ${@functionname(params)} 805 806In all cases, if the expression evaluates to an 807empty string, the statement does not trigger a syntax error because it 808becomes a no-op. 809 810``include`` Directive 811--------------------- 812 813BitBake understands the ``include`` directive. This directive causes 814BitBake to parse whatever file you specify, and to insert that file at 815that location. The directive is much like its equivalent in Make except 816that if the path specified on the include line is a relative path, 817BitBake locates the first file it can find within :term:`BBPATH`. 818 819The include directive is a more generic method of including 820functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` 821directive, which is restricted to class (i.e. ``.bbclass``) files. The 822include directive is applicable for any other kind of shared or 823encapsulated functionality or configuration that does not suit a 824``.bbclass`` file. 825 826As an example, suppose you needed a recipe to include some self-test 827definitions:: 828 829 include test_defs.inc 830 831.. note:: 832 833 The include directive does not produce an error when the file cannot be 834 found. Consequently, it is recommended that if the file you are including is 835 expected to exist, you should use :ref:`require <require-inclusion>` instead 836 of include . Doing so makes sure that an error is produced if the file cannot 837 be found. 838 839.. _require-inclusion: 840 841``require`` Directive 842--------------------- 843 844BitBake understands the ``require`` directive. This directive behaves 845just like the ``include`` directive with the exception that BitBake 846raises a parsing error if the file to be included cannot be found. Thus, 847any file you require is inserted into the file that is being parsed at 848the location of the directive. 849 850The require directive, like the include directive previously described, 851is a more generic method of including functionality as compared to the 852:ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` directive, which is restricted to class 853(i.e. ``.bbclass``) files. The require directive is applicable for any 854other kind of shared or encapsulated functionality or configuration that 855does not suit a ``.bbclass`` file. 856 857Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if 858the path specified on the require line is a relative path, BitBake 859locates the first file it can find within :term:`BBPATH`. 860 861As an example, suppose you have two versions of a recipe (e.g. 862``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some 863identical functionality that could be shared. You could create an 864include file named ``foo.inc`` that contains the common definitions 865needed to build "foo". You need to be sure ``foo.inc`` is located in the 866same directory as your two recipe files as well. Once these conditions 867are set up, you can share the functionality using a ``require`` 868directive from within each recipe:: 869 870 require foo.inc 871 872``INHERIT`` Configuration Directive 873----------------------------------- 874 875When creating a configuration file (``.conf``), you can use the 876:term:`INHERIT` configuration directive to inherit a 877class. BitBake only supports this directive when used within a 878configuration file. 879 880As an example, suppose you needed to inherit a class file called 881``abc.bbclass`` from a configuration file as follows:: 882 883 INHERIT += "abc" 884 885This configuration directive causes the named class to be inherited at 886the point of the directive during parsing. As with the ``inherit`` 887directive, the ``.bbclass`` file must be located in a "classes" 888subdirectory in one of the directories specified in :term:`BBPATH`. 889 890.. note:: 891 892 Because .conf files are parsed first during BitBake's execution, using 893 INHERIT to inherit a class effectively inherits the class globally (i.e. for 894 all recipes). 895 896If you want to use the directive to inherit multiple classes, you can 897provide them on the same line in the ``local.conf`` file. Use spaces to 898separate the classes. The following example shows how to inherit both 899the ``autotools`` and ``pkgconfig`` classes:: 900 901 INHERIT += "autotools pkgconfig" 902 903Functions 904========= 905 906As with most languages, functions are the building blocks that are used 907to build up operations into tasks. BitBake supports these types of 908functions: 909 910- *Shell Functions:* Functions written in shell script and executed 911 either directly as functions, tasks, or both. They can also be called 912 by other shell functions. 913 914- *BitBake-Style Python Functions:* Functions written in Python and 915 executed by BitBake or other Python functions using 916 ``bb.build.exec_func()``. 917 918- *Python Functions:* Functions written in Python and executed by 919 Python. 920 921- *Anonymous Python Functions:* Python functions executed automatically 922 during parsing. 923 924Regardless of the type of function, you can only define them in class 925(``.bbclass``) and recipe (``.bb`` or ``.inc``) files. 926 927Shell Functions 928--------------- 929 930Functions written in shell script are executed either directly as 931functions, tasks, or both. They can also be called by other shell 932functions. Here is an example shell function definition:: 933 934 some_function () { 935 echo "Hello World" 936 } 937 938When you create these types of functions in 939your recipe or class files, you need to follow the shell programming 940rules. The scripts are executed by ``/bin/sh``, which may not be a bash 941shell but might be something such as ``dash``. You should not use 942Bash-specific script (bashisms). 943 944Overrides and override-style operators like ``:append`` and ``:prepend`` 945can also be applied to shell functions. Most commonly, this application 946would be used in a ``.bbappend`` file to modify functions in the main 947recipe. It can also be used to modify functions inherited from classes. 948 949As an example, consider the following:: 950 951 do_foo() { 952 bbplain first 953 fn 954 } 955 956 fn:prepend() { 957 bbplain second 958 } 959 960 fn() { 961 bbplain third 962 } 963 964 do_foo:append() { 965 bbplain fourth 966 } 967 968Running ``do_foo`` prints the following:: 969 970 recipename do_foo: first 971 recipename do_foo: second 972 recipename do_foo: third 973 recipename do_foo: fourth 974 975.. note:: 976 977 Overrides and override-style operators can be applied to any shell 978 function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. 979 980You can use the ``bitbake -e recipename`` command to view the final 981assembled function after all overrides have been applied. 982 983BitBake-Style Python Functions 984------------------------------ 985 986These functions are written in Python and executed by BitBake or other 987Python functions using ``bb.build.exec_func()``. 988 989An example BitBake function is:: 990 991 python some_python_function () { 992 d.setVar("TEXT", "Hello World") 993 print d.getVar("TEXT") 994 } 995 996Because the 997Python "bb" and "os" modules are already imported, you do not need to 998import these modules. Also in these types of functions, the datastore 999("d") is a global variable and is always automatically available. 1000 1001.. note:: 1002 1003 Variable expressions (e.g. ``${X}`` ) are no longer expanded within Python 1004 functions. This behavior is intentional in order to allow you to freely set 1005 variable values to expandable expressions without having them expanded 1006 prematurely. If you do wish to expand a variable within a Python function, 1007 use ``d.getVar("X")`` . Or, for more complicated expressions, use ``d.expand()``. 1008 1009Similar to shell functions, you can also apply overrides and 1010override-style operators to BitBake-style Python functions. 1011 1012As an example, consider the following:: 1013 1014 python do_foo:prepend() { 1015 bb.plain("first") 1016 } 1017 1018 python do_foo() { 1019 bb.plain("second") 1020 } 1021 1022 python do_foo:append() { 1023 bb.plain("third") 1024 } 1025 1026Running ``do_foo`` prints the following:: 1027 1028 recipename do_foo: first 1029 recipename do_foo: second 1030 recipename do_foo: third 1031 1032You can use the ``bitbake -e recipename`` command to view 1033the final assembled function after all overrides have been applied. 1034 1035Python Functions 1036---------------- 1037 1038These functions are written in Python and are executed by other Python 1039code. Examples of Python functions are utility functions that you intend 1040to call from in-line Python or from within other Python functions. Here 1041is an example:: 1042 1043 def get_depends(d): 1044 if d.getVar('SOMECONDITION'): 1045 return "dependencywithcond" 1046 else: 1047 return "dependency" 1048 1049 SOMECONDITION = "1" 1050 DEPENDS = "${@get_depends(d)}" 1051 1052This would result in :term:`DEPENDS` containing ``dependencywithcond``. 1053 1054Here are some things to know about Python functions: 1055 1056- Python functions can take parameters. 1057 1058- The BitBake datastore is not automatically available. Consequently, 1059 you must pass it in as a parameter to the function. 1060 1061- The "bb" and "os" Python modules are automatically available. You do 1062 not need to import them. 1063 1064BitBake-Style Python Functions Versus Python Functions 1065------------------------------------------------------ 1066 1067Following are some important differences between BitBake-style Python 1068functions and regular Python functions defined with "def": 1069 1070- Only BitBake-style Python functions can be :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. 1071 1072- Overrides and override-style operators can only be applied to 1073 BitBake-style Python functions. 1074 1075- Only regular Python functions can take arguments and return values. 1076 1077- :ref:`Variable flags <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>` such as 1078 ``[dirs]``, ``[cleandirs]``, and ``[lockfiles]`` can be used on BitBake-style 1079 Python functions, but not on regular Python functions. 1080 1081- BitBake-style Python functions generate a separate 1082 ``${``\ :term:`T`\ ``}/run.``\ function-name\ ``.``\ pid 1083 script that is executed to run the function, and also generate a log 1084 file in ``${T}/log.``\ function-name\ ``.``\ pid if they are executed 1085 as tasks. 1086 1087 Regular Python functions execute "inline" and do not generate any 1088 files in ``${T}``. 1089 1090- Regular Python functions are called with the usual Python syntax. 1091 BitBake-style Python functions are usually tasks and are called 1092 directly by BitBake, but can also be called manually from Python code 1093 by using the ``bb.build.exec_func()`` function. Here is an example:: 1094 1095 bb.build.exec_func("my_bitbake_style_function", d) 1096 1097 .. note:: 1098 1099 ``bb.build.exec_func()`` can also be used to run shell functions from Python 1100 code. If you want to run a shell function before a Python function within 1101 the same task, then you can use a parent helper Python function that 1102 starts by running the shell function with ``bb.build.exec_func()`` and then 1103 runs the Python code. 1104 1105 To detect errors from functions executed with 1106 ``bb.build.exec_func()``, you can catch the ``bb.build.FuncFailed`` 1107 exception. 1108 1109 .. note:: 1110 1111 Functions in metadata (recipes and classes) should not themselves raise 1112 ``bb.build.FuncFailed``. Rather, ``bb.build.FuncFailed`` should be viewed as a 1113 general indicator that the called function failed by raising an 1114 exception. For example, an exception raised by ``bb.fatal()`` will be caught 1115 inside ``bb.build.exec_func()``, and a ``bb.build.FuncFailed`` will be raised in 1116 response. 1117 1118Due to their simplicity, you should prefer regular Python functions over 1119BitBake-style Python functions unless you need a feature specific to 1120BitBake-style Python functions. Regular Python functions in metadata are 1121a more recent invention than BitBake-style Python functions, and older 1122code tends to use ``bb.build.exec_func()`` more often. 1123 1124Anonymous Python Functions 1125-------------------------- 1126 1127Sometimes it is useful to set variables or perform other operations 1128programmatically during parsing. To do this, you can define special 1129Python functions, called anonymous Python functions, that run at the end 1130of parsing. For example, the following conditionally sets a variable 1131based on the value of another variable:: 1132 1133 python () { 1134 if d.getVar('SOMEVAR') == 'value': 1135 d.setVar('ANOTHERVAR', 'value2') 1136 } 1137 1138An equivalent way to mark a function as an anonymous function is to give it 1139the name "__anonymous", rather than no name. 1140 1141Anonymous Python functions always run at the end of parsing, regardless 1142of where they are defined. If a recipe contains many anonymous 1143functions, they run in the same order as they are defined within the 1144recipe. As an example, consider the following snippet:: 1145 1146 python () { 1147 d.setVar('FOO', 'foo 2') 1148 } 1149 1150 FOO = "foo 1" 1151 1152 python () { 1153 d.appendVar('BAR',' bar 2') 1154 } 1155 1156 BAR = "bar 1" 1157 1158The previous example is conceptually 1159equivalent to the following snippet:: 1160 1161 FOO = "foo 1" 1162 BAR = "bar 1" 1163 FOO = "foo 2" 1164 BAR += "bar 2" 1165 1166``FOO`` ends up with the value "foo 2", and 1167``BAR`` with the value "bar 1 bar 2". Just as in the second snippet, the 1168values set for the variables within the anonymous functions become 1169available to tasks, which always run after parsing. 1170 1171Overrides and override-style operators such as "``:append``" are applied 1172before anonymous functions run. In the following example, ``FOO`` ends 1173up with the value "foo from anonymous":: 1174 1175 FOO = "foo" 1176 FOO:append = " from outside" 1177 1178 python () { 1179 d.setVar("FOO", "foo from anonymous") 1180 } 1181 1182For methods 1183you can use with anonymous Python functions, see the 1184":ref:`bitbake-user-manual/bitbake-user-manual-metadata:functions you can call from within python`" 1185section. For a different method to run Python code during parsing, see 1186the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inline python variable expansion`" section. 1187 1188Flexible Inheritance for Class Functions 1189---------------------------------------- 1190 1191Through coding techniques and the use of ``EXPORT_FUNCTIONS``, BitBake 1192supports exporting a function from a class such that the class function 1193appears as the default implementation of the function, but can still be 1194called if a recipe inheriting the class needs to define its own version 1195of the function. 1196 1197To understand the benefits of this feature, consider the basic scenario 1198where a class defines a task function and your recipe inherits the 1199class. In this basic scenario, your recipe inherits the task function as 1200defined in the class. If desired, your recipe can add to the start and 1201end of the function by using the ":prepend" or ":append" operations 1202respectively, or it can redefine the function completely. However, if it 1203redefines the function, there is no means for it to call the class 1204version of the function. ``EXPORT_FUNCTIONS`` provides a mechanism that 1205enables the recipe's version of the function to call the original 1206version of the function. 1207 1208To make use of this technique, you need the following things in place: 1209 1210- The class needs to define the function as follows:: 1211 1212 classname_functionname 1213 1214 For example, if you have a class file 1215 ``bar.bbclass`` and a function named ``do_foo``, the class must 1216 define the function as follows:: 1217 1218 bar_do_foo 1219 1220- The class needs to contain the ``EXPORT_FUNCTIONS`` statement as 1221 follows:: 1222 1223 EXPORT_FUNCTIONS functionname 1224 1225 For example, continuing with 1226 the same example, the statement in the ``bar.bbclass`` would be as 1227 follows:: 1228 1229 EXPORT_FUNCTIONS do_foo 1230 1231- You need to call the function appropriately from within your recipe. 1232 Continuing with the same example, if your recipe needs to call the 1233 class version of the function, it should call ``bar_do_foo``. 1234 Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was 1235 used as above, the recipe's function could conditionally call the 1236 class version of the function as follows:: 1237 1238 do_foo() { 1239 if [ somecondition ] ; then 1240 bar_do_foo 1241 else 1242 # Do something else 1243 fi 1244 } 1245 1246 To call your modified version of the function as defined in your recipe, 1247 call it as ``do_foo``. 1248 1249With these conditions met, your single recipe can freely choose between 1250the original function as defined in the class file and the modified 1251function in your recipe. If you do not set up these conditions, you are 1252limited to using one function or the other. 1253 1254Tasks 1255===== 1256 1257Tasks are BitBake execution units that make up the steps that BitBake 1258can run for a given recipe. Tasks are only supported in recipes and 1259classes (i.e. in ``.bb`` files and files included or inherited from 1260``.bb`` files). By convention, tasks have names that start with "do\_". 1261 1262Promoting a Function to a Task 1263------------------------------ 1264 1265Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual-metadata:shell functions>` or 1266:ref:`BitBake-style Python functions <bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions>` 1267that have been promoted to tasks by using the ``addtask`` command. The 1268``addtask`` command can also optionally describe dependencies between 1269the task and other tasks. Here is an example that shows how to define a 1270task and declare some dependencies:: 1271 1272 python do_printdate () { 1273 import time 1274 print time.strftime('%Y%m%d', time.gmtime()) 1275 } 1276 addtask printdate after do_fetch before do_build 1277 1278The first argument to ``addtask`` is the name 1279of the function to promote to a task. If the name does not start with 1280"do\_", "do\_" is implicitly added, which enforces the convention that all 1281task names start with "do\_". 1282 1283In the previous example, the ``do_printdate`` task becomes a dependency 1284of the ``do_build`` task, which is the default task (i.e. the task run 1285by the ``bitbake`` command unless another task is specified explicitly). 1286Additionally, the ``do_printdate`` task becomes dependent upon the 1287``do_fetch`` task. Running the ``do_build`` task results in the 1288``do_printdate`` task running first. 1289 1290.. note:: 1291 1292 If you try out the previous example, you might see that the 1293 ``do_printdate`` 1294 task is only run the first time you build the recipe with the 1295 ``bitbake`` 1296 command. This is because BitBake considers the task "up-to-date" 1297 after that initial run. If you want to force the task to always be 1298 rerun for experimentation purposes, you can make BitBake always 1299 consider the task "out-of-date" by using the 1300 :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` 1301 variable flag, as follows:: 1302 1303 do_printdate[nostamp] = "1" 1304 1305 You can also explicitly run the task and provide the 1306 -f option as follows:: 1307 1308 $ bitbake recipe -c printdate -f 1309 1310 When manually selecting a task to run with the bitbake ``recipe 1311 -c task`` command, you can omit the "do\_" prefix as part of the task 1312 name. 1313 1314You might wonder about the practical effects of using ``addtask`` 1315without specifying any dependencies as is done in the following example:: 1316 1317 addtask printdate 1318 1319In this example, assuming dependencies have not been 1320added through some other means, the only way to run the task is by 1321explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You 1322can use the ``do_listtasks`` task to list all tasks defined in a recipe 1323as shown in the following example:: 1324 1325 $ bitbake recipe -c listtasks 1326 1327For more information on task dependencies, see the 1328":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" section. 1329 1330See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information 1331on variable flags you can use with tasks. 1332 1333.. note:: 1334 1335 While it's infrequent, it's possible to define multiple tasks as 1336 dependencies when calling ``addtask``. For example, here's a snippet 1337 from the OpenEmbedded class file ``package_tar.bbclass``:: 1338 1339 addtask package_write_tar before do_build after do_packagedata do_package 1340 1341 Note how the ``package_write_tar`` task has to wait until both of 1342 ``do_packagedata`` and ``do_package`` complete. 1343 1344Deleting a Task 1345--------------- 1346 1347As well as being able to add tasks, you can delete them. Simply use the 1348``deltask`` command to delete a task. For example, to delete the example 1349task used in the previous sections, you would use:: 1350 1351 deltask printdate 1352 1353If you delete a task using the ``deltask`` command and the task has 1354dependencies, the dependencies are not reconnected. For example, suppose 1355you have three tasks named ``do_a``, ``do_b``, and ``do_c``. 1356Furthermore, ``do_c`` is dependent on ``do_b``, which in turn is 1357dependent on ``do_a``. Given this scenario, if you use ``deltask`` to 1358delete ``do_b``, the implicit dependency relationship between ``do_c`` 1359and ``do_a`` through ``do_b`` no longer exists, and ``do_c`` 1360dependencies are not updated to include ``do_a``. Thus, ``do_c`` is free 1361to run before ``do_a``. 1362 1363If you want dependencies such as these to remain intact, use the 1364``[noexec]`` varflag to disable the task instead of using the 1365``deltask`` command to delete it:: 1366 1367 do_b[noexec] = "1" 1368 1369Passing Information Into the Build Task Environment 1370--------------------------------------------------- 1371 1372When running a task, BitBake tightly controls the shell execution 1373environment of the build tasks to make sure unwanted contamination from 1374the build machine cannot influence the build. 1375 1376.. note:: 1377 1378 By default, BitBake cleans the environment to include only those 1379 things exported or listed in its passthrough list to ensure that the 1380 build environment is reproducible and consistent. You can prevent this 1381 "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable. 1382 1383Consequently, if you do want something to get passed into the build task 1384environment, you must take these two steps: 1385 1386#. Tell BitBake to load what you want from the environment into the 1387 datastore. You can do so through the 1388 :term:`BB_ENV_PASSTHROUGH` and 1389 :term:`BB_ENV_PASSTHROUGH_ADDITIONS` variables. For 1390 example, assume you want to prevent the build system from accessing 1391 your ``$HOME/.ccache`` directory. The following command adds the 1392 the environment variable ``CCACHE_DIR`` to BitBake's passthrough 1393 list to allow that variable into the datastore:: 1394 1395 export BB_ENV_PASSTHROUGH_ADDITIONS="$BB_ENV_PASSTHROUGH_ADDITIONS CCACHE_DIR" 1396 1397#. Tell BitBake to export what you have loaded into the datastore to the 1398 task environment of every running task. Loading something from the 1399 environment into the datastore (previous step) only makes it 1400 available in the datastore. To export it to the task environment of 1401 every running task, use a command similar to the following in your 1402 local configuration file ``local.conf`` or your distribution 1403 configuration file:: 1404 1405 export CCACHE_DIR 1406 1407 .. note:: 1408 1409 A side effect of the previous steps is that BitBake records the 1410 variable as a dependency of the build process in things like the 1411 setscene checksums. If doing so results in unnecessary rebuilds of 1412 tasks, you can also flag the variable so that the setscene code 1413 ignores the dependency when it creates checksums. 1414 1415Sometimes, it is useful to be able to obtain information from the 1416original execution environment. BitBake saves a copy of the original 1417environment into a special variable named :term:`BB_ORIGENV`. 1418 1419The :term:`BB_ORIGENV` variable returns a datastore object that can be 1420queried using the standard datastore operators such as 1421``getVar(, False)``. The datastore object is useful, for example, to 1422find the original ``DISPLAY`` variable. Here is an example:: 1423 1424 origenv = d.getVar("BB_ORIGENV", False) 1425 bar = origenv.getVar("BAR", False) 1426 1427The previous example returns ``BAR`` from the original execution 1428environment. 1429 1430Variable Flags 1431============== 1432 1433Variable flags (varflags) help control a task's functionality and 1434dependencies. BitBake reads and writes varflags to the datastore using 1435the following command forms:: 1436 1437 variable = d.getVarFlags("variable") 1438 self.d.setVarFlags("FOO", {"func": True}) 1439 1440When working with varflags, the same syntax, with the exception of 1441overrides, applies. In other words, you can set, append, and prepend 1442varflags just like variables. See the 1443":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flag syntax`" section for details. 1444 1445BitBake has a defined set of varflags available for recipes and classes. 1446Tasks support a number of these flags which control various 1447functionality of the task: 1448 1449- ``[cleandirs]``: Empty directories that should be created before 1450 the task runs. Directories that already exist are removed and 1451 recreated to empty them. 1452 1453- ``[depends]``: Controls inter-task dependencies. See the 1454 :term:`DEPENDS` variable and the 1455 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inter-task 1456 dependencies`" section for more information. 1457 1458- ``[deptask]``: Controls task build-time dependencies. See the 1459 :term:`DEPENDS` variable and the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:build dependencies`" section for more information. 1460 1461- ``[dirs]``: Directories that should be created before the task 1462 runs. Directories that already exist are left as is. The last 1463 directory listed is used as the current working directory for the 1464 task. 1465 1466- ``[lockfiles]``: Specifies one or more lockfiles to lock while the 1467 task executes. Only one task may hold a lockfile, and any task that 1468 attempts to lock an already locked file will block until the lock is 1469 released. You can use this variable flag to accomplish mutual 1470 exclusion. 1471 1472- ``[noexec]``: When set to "1", marks the task as being empty, with 1473 no execution required. You can use the ``[noexec]`` flag to set up 1474 tasks as dependency placeholders, or to disable tasks defined 1475 elsewhere that are not needed in a particular recipe. 1476 1477- ``[nostamp]``: When set to "1", tells BitBake to not generate a 1478 stamp file for a task, which implies the task should always be 1479 executed. 1480 1481 .. caution:: 1482 1483 Any task that depends (possibly indirectly) on a ``[nostamp]`` task will 1484 always be executed as well. This can cause unnecessary rebuilding if you 1485 are not careful. 1486 1487- ``[number_threads]``: Limits tasks to a specific number of 1488 simultaneous threads during execution. This varflag is useful when 1489 your build host has a large number of cores but certain tasks need to 1490 be rate-limited due to various kinds of resource constraints (e.g. to 1491 avoid network throttling). ``number_threads`` works similarly to the 1492 :term:`BB_NUMBER_THREADS` variable but is task-specific. 1493 1494 Set the value globally. For example, the following makes sure the 1495 ``do_fetch`` task uses no more than two simultaneous execution 1496 threads: do_fetch[number_threads] = "2" 1497 1498 .. warning:: 1499 1500 - Setting the varflag in individual recipes rather than globally 1501 can result in unpredictable behavior. 1502 1503 - Setting the varflag to a value greater than the value used in 1504 the :term:`BB_NUMBER_THREADS` variable causes ``number_threads`` to 1505 have no effect. 1506 1507- ``[postfuncs]``: List of functions to call after the completion of 1508 the task. 1509 1510- ``[prefuncs]``: List of functions to call before the task executes. 1511 1512- ``[rdepends]``: Controls inter-task runtime dependencies. See the 1513 :term:`RDEPENDS` variable, the 1514 :term:`RRECOMMENDS` variable, and the 1515 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inter-task dependencies`" section for 1516 more information. 1517 1518- ``[rdeptask]``: Controls task runtime dependencies. See the 1519 :term:`RDEPENDS` variable, the 1520 :term:`RRECOMMENDS` variable, and the 1521 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:runtime dependencies`" section for more 1522 information. 1523 1524- ``[recideptask]``: When set in conjunction with ``recrdeptask``, 1525 specifies a task that should be inspected for additional 1526 dependencies. 1527 1528- ``[recrdeptask]``: Controls task recursive runtime dependencies. 1529 See the :term:`RDEPENDS` variable, the 1530 :term:`RRECOMMENDS` variable, and the 1531 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:recursive dependencies`" section for 1532 more information. 1533 1534- ``[stamp-extra-info]``: Extra stamp information to append to the 1535 task's stamp. As an example, OpenEmbedded uses this flag to allow 1536 machine-specific tasks. 1537 1538- ``[umask]``: The umask to run the task under. 1539 1540Several varflags are useful for controlling how signatures are 1541calculated for variables. For more information on this process, see the 1542":ref:`bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)`" section. 1543 1544- ``[vardeps]``: Specifies a space-separated list of additional 1545 variables to add to a variable's dependencies for the purposes of 1546 calculating its signature. Adding variables to this list is useful, 1547 for example, when a function refers to a variable in a manner that 1548 does not allow BitBake to automatically determine that the variable 1549 is referred to. 1550 1551- ``[vardepsexclude]``: Specifies a space-separated list of variables 1552 that should be excluded from a variable's dependencies for the 1553 purposes of calculating its signature. 1554 1555- ``[vardepvalue]``: If set, instructs BitBake to ignore the actual 1556 value of the variable and instead use the specified value when 1557 calculating the variable's signature. 1558 1559- ``[vardepvalueexclude]``: Specifies a pipe-separated list of 1560 strings to exclude from the variable's value when calculating the 1561 variable's signature. 1562 1563Events 1564====== 1565 1566BitBake allows installation of event handlers within recipe and class 1567files. Events are triggered at certain points during operation, such as 1568the beginning of operation against a given recipe (i.e. ``*.bb``), the 1569start of a given task, a task failure, a task success, and so forth. The 1570intent is to make it easy to do things like email notification on build 1571failures. 1572 1573Following is an example event handler that prints the name of the event 1574and the content of the :term:`FILE` variable:: 1575 1576 addhandler myclass_eventhandler 1577 python myclass_eventhandler() { 1578 from bb.event import getName 1579 print("The name of the Event is %s" % getName(e)) 1580 print("The file we run for is %s" % d.getVar('FILE')) 1581 } 1582 myclass_eventhandler[eventmask] = "bb.event.BuildStarted 1583 bb.event.BuildCompleted" 1584 1585In the previous example, an eventmask has been 1586set so that the handler only sees the "BuildStarted" and 1587"BuildCompleted" events. This event handler gets called every time an 1588event matching the eventmask is triggered. A global variable "e" is 1589defined, which represents the current event. With the ``getName(e)`` 1590method, you can get the name of the triggered event. The global 1591datastore is available as "d". In legacy code, you might see "e.data" 1592used to get the datastore. However, realize that "e.data" is deprecated 1593and you should use "d" going forward. 1594 1595The context of the datastore is appropriate to the event in question. 1596For example, "BuildStarted" and "BuildCompleted" events run before any 1597tasks are executed so would be in the global configuration datastore 1598namespace. No recipe-specific metadata exists in that namespace. The 1599"BuildStarted" and "BuildCompleted" events also run in the main 1600cooker/server process rather than any worker context. Thus, any changes 1601made to the datastore would be seen by other cooker/server events within 1602the current build but not seen outside of that build or in any worker 1603context. Task events run in the actual tasks in question consequently 1604have recipe-specific and task-specific contents. These events run in the 1605worker context and are discarded at the end of task execution. 1606 1607During a standard build, the following common events might occur. The 1608following events are the most common kinds of events that most metadata 1609might have an interest in viewing: 1610 1611- ``bb.event.ConfigParsed()``: Fired when the base configuration; which 1612 consists of ``bitbake.conf``, ``base.bbclass`` and any global 1613 :term:`INHERIT` statements; has been parsed. You can see multiple such 1614 events when each of the workers parse the base configuration or if 1615 the server changes configuration and reparses. Any given datastore 1616 only has one such event executed against it, however. If 1617 :term:`BB_INVALIDCONF` is set in the datastore by the event 1618 handler, the configuration is reparsed and a new event triggered, 1619 allowing the metadata to update configuration. 1620 1621- ``bb.event.HeartbeatEvent()``: Fires at regular time intervals of one 1622 second. You can configure the interval time using the 1623 ``BB_HEARTBEAT_EVENT`` variable. The event's "time" attribute is the 1624 ``time.time()`` value when the event is triggered. This event is 1625 useful for activities such as system state monitoring. 1626 1627- ``bb.event.ParseStarted()``: Fired when BitBake is about to start 1628 parsing recipes. This event's "total" attribute represents the number 1629 of recipes BitBake plans to parse. 1630 1631- ``bb.event.ParseProgress()``: Fired as parsing progresses. This 1632 event's "current" attribute is the number of recipes parsed as well 1633 as the "total" attribute. 1634 1635- ``bb.event.ParseCompleted()``: Fired when parsing is complete. This 1636 event's "cached", "parsed", "skipped", "virtuals", "masked", and 1637 "errors" attributes provide statistics for the parsing results. 1638 1639- ``bb.event.BuildStarted()``: Fired when a new build starts. BitBake 1640 fires multiple "BuildStarted" events (one per configuration) when 1641 multiple configuration (multiconfig) is enabled. 1642 1643- ``bb.build.TaskStarted()``: Fired when a task starts. This event's 1644 "taskfile" attribute points to the recipe from which the task 1645 originates. The "taskname" attribute, which is the task's name, 1646 includes the ``do_`` prefix, and the "logfile" attribute point to 1647 where the task's output is stored. Finally, the "time" attribute is 1648 the task's execution start time. 1649 1650- ``bb.build.TaskInvalid()``: Fired if BitBake tries to execute a task 1651 that does not exist. 1652 1653- ``bb.build.TaskFailedSilent()``: Fired for setscene tasks that fail 1654 and should not be presented to the user verbosely. 1655 1656- ``bb.build.TaskFailed()``: Fired for normal tasks that fail. 1657 1658- ``bb.build.TaskSucceeded()``: Fired when a task successfully 1659 completes. 1660 1661- ``bb.event.BuildCompleted()``: Fired when a build finishes. 1662 1663- ``bb.cooker.CookerExit()``: Fired when the BitBake server/cooker 1664 shuts down. This event is usually only seen by the UIs as a sign they 1665 should also shutdown. 1666 1667This next list of example events occur based on specific requests to the 1668server. These events are often used to communicate larger pieces of 1669information from the BitBake server to other parts of BitBake such as 1670user interfaces: 1671 1672- ``bb.event.TreeDataPreparationStarted()`` 1673- ``bb.event.TreeDataPreparationProgress()`` 1674- ``bb.event.TreeDataPreparationCompleted()`` 1675- ``bb.event.DepTreeGenerated()`` 1676- ``bb.event.CoreBaseFilesFound()`` 1677- ``bb.event.ConfigFilePathFound()`` 1678- ``bb.event.FilesMatchingFound()`` 1679- ``bb.event.ConfigFilesFound()`` 1680- ``bb.event.TargetsTreeGenerated()`` 1681 1682.. _variants-class-extension-mechanism: 1683 1684Variants --- Class Extension Mechanism 1685====================================== 1686 1687BitBake supports multiple incarnations of a recipe file via the 1688:term:`BBCLASSEXTEND` variable. 1689 1690The :term:`BBCLASSEXTEND` variable is a space separated list of classes used 1691to "extend" the recipe for each variant. Here is an example that results in a 1692second incarnation of the current recipe being available. This second 1693incarnation will have the "native" class inherited. :: 1694 1695 BBCLASSEXTEND = "native" 1696 1697.. note:: 1698 1699 The mechanism for this class extension is extremely specific to the 1700 implementation. Usually, the recipe's :term:`PROVIDES` , :term:`PN` , and 1701 :term:`DEPENDS` variables would need to be modified by the extension 1702 class. For specific examples, see the OE-Core native , nativesdk , and 1703 multilib classes. 1704 1705Dependencies 1706============ 1707 1708To allow for efficient parallel processing, BitBake handles dependencies 1709at the task level. Dependencies can exist both between tasks within a 1710single recipe and between tasks in different recipes. Following are 1711examples of each: 1712 1713- For tasks within a single recipe, a recipe's ``do_configure`` task 1714 might need to complete before its ``do_compile`` task can run. 1715 1716- For tasks in different recipes, one recipe's ``do_configure`` task 1717 might require another recipe's ``do_populate_sysroot`` task to finish 1718 first such that the libraries and headers provided by the other 1719 recipe are available. 1720 1721This section describes several ways to declare dependencies. Remember, 1722even though dependencies are declared in different ways, they are all 1723simply dependencies between tasks. 1724 1725.. _dependencies-internal-to-the-bb-file: 1726 1727Dependencies Internal to the ``.bb`` File 1728----------------------------------------- 1729 1730BitBake uses the ``addtask`` directive to manage dependencies that are 1731internal to a given recipe file. You can use the ``addtask`` directive 1732to indicate when a task is dependent on other tasks or when other tasks 1733depend on that recipe. Here is an example:: 1734 1735 addtask printdate after do_fetch before do_build 1736 1737In this example, the ``do_printdate`` task 1738depends on the completion of the ``do_fetch`` task, and the ``do_build`` 1739task depends on the completion of the ``do_printdate`` task. 1740 1741.. note:: 1742 1743 For a task to run, it must be a direct or indirect dependency of some 1744 other task that is scheduled to run. 1745 1746 For illustration, here are some examples: 1747 1748 - The directive ``addtask mytask before do_configure`` causes 1749 ``do_mytask`` to run before ``do_configure`` runs. Be aware that 1750 ``do_mytask`` still only runs if its :ref:`input 1751 checksum <bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)>` has changed since the last time it was 1752 run. Changes to the input checksum of ``do_mytask`` also 1753 indirectly cause ``do_configure`` to run. 1754 1755 - The directive ``addtask mytask after do_configure`` by itself 1756 never causes ``do_mytask`` to run. ``do_mytask`` can still be run 1757 manually as follows:: 1758 1759 $ bitbake recipe -c mytask 1760 1761 Declaring ``do_mytask`` as a dependency of some other task that is 1762 scheduled to run also causes it to run. Regardless, the task runs after 1763 ``do_configure``. 1764 1765Build Dependencies 1766------------------ 1767 1768BitBake uses the :term:`DEPENDS` variable to manage 1769build time dependencies. The ``[deptask]`` varflag for tasks signifies 1770the task of each item listed in :term:`DEPENDS` that must complete before 1771that task can be executed. Here is an example:: 1772 1773 do_configure[deptask] = "do_populate_sysroot" 1774 1775In this example, the ``do_populate_sysroot`` task 1776of each item in :term:`DEPENDS` must complete before ``do_configure`` can 1777execute. 1778 1779Runtime Dependencies 1780-------------------- 1781 1782BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` 1783variables to manage runtime dependencies. 1784 1785The :term:`PACKAGES` variable lists runtime packages. Each of those packages 1786can have :term:`RDEPENDS` and :term:`RRECOMMENDS` runtime dependencies. The 1787``[rdeptask]`` flag for tasks is used to signify the task of each item 1788runtime dependency which must have completed before that task can be 1789executed. :: 1790 1791 do_package_qa[rdeptask] = "do_packagedata" 1792 1793In the previous 1794example, the ``do_packagedata`` task of each item in :term:`RDEPENDS` must 1795have completed before ``do_package_qa`` can execute. 1796Although :term:`RDEPENDS` contains entries from the 1797runtime dependency namespace, BitBake knows how to map them back 1798to the build-time dependency namespace, in which the tasks are defined. 1799 1800Recursive Dependencies 1801---------------------- 1802 1803BitBake uses the ``[recrdeptask]`` flag to manage recursive task 1804dependencies. BitBake looks through the build-time and runtime 1805dependencies of the current recipe, looks through the task's inter-task 1806dependencies, and then adds dependencies for the listed task. Once 1807BitBake has accomplished this, it recursively works through the 1808dependencies of those tasks. Iterative passes continue until all 1809dependencies are discovered and added. 1810 1811The ``[recrdeptask]`` flag is most commonly used in high-level recipes 1812that need to wait for some task to finish "globally". For example, 1813``image.bbclass`` has the following:: 1814 1815 do_rootfs[recrdeptask] += "do_packagedata" 1816 1817This statement says that the ``do_packagedata`` task of 1818the current recipe and all recipes reachable (by way of dependencies) 1819from the image recipe must run before the ``do_rootfs`` task can run. 1820 1821BitBake allows a task to recursively depend on itself by 1822referencing itself in the task list:: 1823 1824 do_a[recrdeptask] = "do_a do_b" 1825 1826In the same way as before, this means that the ``do_a`` 1827and ``do_b`` tasks of the current recipe and all 1828recipes reachable (by way of dependencies) from the recipe 1829must run before the ``do_a`` task can run. In this 1830case BitBake will ignore the current recipe's ``do_a`` 1831task circular dependency on itself. 1832 1833Inter-Task Dependencies 1834----------------------- 1835 1836BitBake uses the ``[depends]`` flag in a more generic form to manage 1837inter-task dependencies. This more generic form allows for 1838inter-dependency checks for specific tasks rather than checks for the 1839data in :term:`DEPENDS`. Here is an example:: 1840 1841 do_patch[depends] = "quilt-native:do_populate_sysroot" 1842 1843In this example, the ``do_populate_sysroot`` task of the target ``quilt-native`` 1844must have completed before the ``do_patch`` task can execute. 1845 1846The ``[rdepends]`` flag works in a similar way but takes targets in the 1847runtime namespace instead of the build-time dependency namespace. 1848 1849Functions You Can Call From Within Python 1850========================================= 1851 1852BitBake provides many functions you can call from within Python 1853functions. This section lists the most commonly used functions, and 1854mentions where to find others. 1855 1856Functions for Accessing Datastore Variables 1857------------------------------------------- 1858 1859It is often necessary to access variables in the BitBake datastore using 1860Python functions. The BitBake datastore has an API that allows you this 1861access. Here is a list of available operations: 1862 1863.. list-table:: 1864 :widths: auto 1865 :header-rows: 1 1866 1867 * - *Operation* 1868 - *Description* 1869 * - ``d.getVar("X", expand)`` 1870 - Returns the value of variable "X". Using "expand=True" expands the 1871 value. Returns "None" if the variable "X" does not exist. 1872 * - ``d.setVar("X", "value")`` 1873 - Sets the variable "X" to "value" 1874 * - ``d.appendVar("X", "value")`` 1875 - Adds "value" to the end of the variable "X". Acts like ``d.setVar("X", 1876 "value")`` if the variable "X" does not exist. 1877 * - ``d.prependVar("X", "value")`` 1878 - Adds "value" to the start of the variable "X". Acts like 1879 ``d.setVar("X","value")`` if the variable "X" does not exist. 1880 * - ``d.delVar("X")`` 1881 - Deletes the variable "X" from the datastore. Does nothing if the variable 1882 "X" does not exist. 1883 * - ``d.renameVar("X", "Y")`` 1884 - Renames the variable "X" to "Y". Does nothing if the variable "X" does 1885 not exist. 1886 * - ``d.getVarFlag("X", flag, expand)`` 1887 - Returns the value of variable "X". Using "expand=True" expands the 1888 value. Returns "None" if either the variable "X" or the named flag does 1889 not exist. 1890 * - ``d.setVarFlag("X", flag, "value")`` 1891 - Sets the named flag for variable "X" to "value". 1892 * - ``d.appendVarFlag("X", flag, "value")`` 1893 - Appends "value" to the named flag on the variable "X". Acts like 1894 ``d.setVarFlag("X", flag, "value")`` if the named flag does not exist. 1895 * - ``d.prependVarFlag("X", flag, "value")`` 1896 - Prepends "value" to the named flag on the variable "X". Acts like 1897 ``d.setVarFlag("X", flag, "value")`` if the named flag does not exist. 1898 * - ``d.delVarFlag("X", flag)`` 1899 - Deletes the named flag on the variable "X" from the datastore. 1900 * - ``d.setVarFlags("X", flagsdict)`` 1901 - Sets the flags specified in the ``flagsdict()`` 1902 parameter. ``setVarFlags`` does not clear previous flags. Think of this 1903 operation as ``addVarFlags``. 1904 * - ``d.getVarFlags("X")`` 1905 - Returns a ``flagsdict`` of the flags for the variable "X". Returns "None" 1906 if the variable "X" does not exist. 1907 * - ``d.delVarFlags("X")`` 1908 - Deletes all the flags for the variable "X". Does nothing if the variable 1909 "X" does not exist. 1910 * - ``d.expand(expression)`` 1911 - Expands variable references in the specified string 1912 expression. References to variables that do not exist are left as is. For 1913 example, ``d.expand("foo ${X}")`` expands to the literal string "foo 1914 ${X}" if the variable "X" does not exist. 1915 1916Other Functions 1917--------------- 1918 1919You can find many other functions that can be called from Python by 1920looking at the source code of the ``bb`` module, which is in 1921``bitbake/lib/bb``. For example, ``bitbake/lib/bb/utils.py`` includes 1922the commonly used functions ``bb.utils.contains()`` and 1923``bb.utils.mkdirhier()``, which come with docstrings. 1924 1925Task Checksums and Setscene 1926=========================== 1927 1928BitBake uses checksums (or signatures) along with the setscene to 1929determine if a task needs to be run. This section describes the process. 1930To help understand how BitBake does this, the section assumes an 1931OpenEmbedded metadata-based example. 1932 1933These checksums are stored in :term:`STAMP`. You can 1934examine the checksums using the following BitBake command:: 1935 1936 $ bitbake-dumpsigs 1937 1938This command returns the signature data in a readable 1939format that allows you to examine the inputs used when the OpenEmbedded 1940build system generates signatures. For example, using 1941``bitbake-dumpsigs`` allows you to examine the ``do_compile`` task's 1942"sigdata" for a C application (e.g. ``bash``). Running the command also 1943reveals that the "CC" variable is part of the inputs that are hashed. 1944Any changes to this variable would invalidate the stamp and cause the 1945``do_compile`` task to run. 1946 1947The following list describes related variables: 1948 1949- :term:`BB_HASHCHECK_FUNCTION`: 1950 Specifies the name of the function to call during the "setscene" part 1951 of the task's execution in order to validate the list of task hashes. 1952 1953- :term:`BB_SETSCENE_DEPVALID`: 1954 Specifies a function BitBake calls that determines whether BitBake 1955 requires a setscene dependency to be met. 1956 1957- :term:`BB_TASKHASH`: Within an executing task, 1958 this variable holds the hash of the task as returned by the currently 1959 enabled signature generator. 1960 1961- :term:`STAMP`: The base path to create stamp files. 1962 1963- :term:`STAMPCLEAN`: Again, the base path to 1964 create stamp files but can use wildcards for matching a range of 1965 files for clean operations. 1966 1967Wildcard Support in Variables 1968============================= 1969 1970Support for wildcard use in variables varies depending on the context in 1971which it is used. For example, some variables and filenames allow 1972limited use of wildcards through the "``%``" and "``*``" characters. 1973Other variables or names support Python's 1974`glob <https://docs.python.org/3/library/glob.html>`_ syntax, 1975`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`_ 1976syntax, or 1977`Regular Expression (re) <https://docs.python.org/3/library/re.html>`_ 1978syntax. 1979 1980For variables that have wildcard suport, the documentation describes 1981which form of wildcard, its use, and its limitations. 1982