diff options
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml')
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml | 2862 |
1 files changed, 0 insertions, 2862 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml deleted file mode 100644 index 0ca5321618..0000000000 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +++ /dev/null @@ -1,2862 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id="bitbake-user-manual-metadata"> - <title>Syntax and Operators</title> - - <para> - BitBake files have their own syntax. - The syntax has similarities to several - other languages but also has some unique features. - This section describes the available syntax and operators - as well as provides examples. - </para> - - <section id='basic-syntax'> - <title>Basic Syntax</title> - - <para> - This section provides some basic syntax examples. - </para> - - <section id='basic-variable-setting'> - <title>Basic Variable Setting</title> - - <para> - The following example sets <filename>VARIABLE</filename> to - "value". - This assignment occurs immediately as the statement is parsed. - It is a "hard" assignment. - <literallayout class='monospaced'> - VARIABLE = "value" - </literallayout> - As expected, if you include leading or trailing spaces as part of - an assignment, the spaces are retained: - <literallayout class='monospaced'> - VARIABLE = " value" - VARIABLE = "value " - </literallayout> - Setting <filename>VARIABLE</filename> to "" sets it to an empty string, - while setting the variable to " " sets it to a blank space - (i.e. these are not the same values). - <literallayout class='monospaced'> - VARIABLE = "" - VARIABLE = " " - </literallayout> - </para> - - <para> - You can use single quotes instead of double quotes - when setting a variable's value. - Doing so allows you to use values that contain the double - quote character: - <literallayout class='monospaced'> - VARIABLE = 'I have a " in my value' - </literallayout> - <note> - Unlike in Bourne shells, single quotes work identically - to double quotes in all other ways. - They do not suppress variable expansions. - </note> - </para> - </section> - - <section id='modifying-existing-variables'> - <title>Modifying Existing Variables</title> - - <para> - Sometimes you need to modify existing variables. - Following are some cases where you might find you want to - modify an existing variable: - <itemizedlist> - <listitem><para> - Customize a recipe that uses the variable. - </para></listitem> - <listitem><para> - Change a variable's default value used in a - <filename>*.bbclass</filename> file. - </para></listitem> - <listitem><para> - Change the variable in a <filename>*.bbappend</filename> - file to override the variable in the original recipe. - </para></listitem> - <listitem><para> - Change the variable in a configuration file so that the - value overrides an existing configuration. - </para></listitem> - </itemizedlist> - </para> - - <para> - Changing a variable value can sometimes depend on how the - value was originally assigned and also on the desired - intent of the change. - In particular, when you append a value to a variable that - has a default value, the resulting value might not be what - you expect. - In this case, the value you provide might replace the value - rather than append to the default value. - </para> - - <para> - If after you have changed a variable's value and something - unexplained occurs, you can use BitBake to check the actual - value of the suspect variable. - You can make these checks for both configuration and recipe - level changes: - <itemizedlist> - <listitem><para> - For configuration changes, use the following: - <literallayout class='monospaced'> - $ bitbake -e - </literallayout> - This command displays variable values after the - configuration files (i.e. <filename>local.conf</filename>, - <filename>bblayers.conf</filename>, - <filename>bitbake.conf</filename> and so forth) have - been parsed. - <note> - Variables that are exported to the environment are - preceded by the string "export" in the command's - output. - </note> - </para></listitem> - <listitem><para> - For recipe changes, use the following: - <literallayout class='monospaced'> - $ bitbake <replaceable>recipe</replaceable> -e | grep VARIABLE=" - </literallayout> - This command checks to see if the variable actually - makes it into a specific recipe. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='line-joining'> - <title>Line Joining</title> - - <para> - Outside of - <link linkend='functions'>functions</link>, BitBake joins - any line ending in a backslash character ("\") - with the following line before parsing statements. - The most common use for the "\" character is to split variable - assignments over multiple lines, as in the following example: - <literallayout class='monospaced'> - FOO = "bar \ - baz \ - qaz" - </literallayout> - Both the "\" character and the newline character - that follow it are removed when joining lines. - Thus, no newline characters end up in the value of - <filename>FOO</filename>. - </para> - - <para> - Consider this additional example where the two - assignments both assign "barbaz" to - <filename>FOO</filename>: - <literallayout class='monospaced'> - FOO = "barbaz" - - FOO = "bar\ - baz" - </literallayout> - <note> - BitBake does not interpret escape sequences like - "\n" in variable values. - For these to have an effect, the value must be passed - to some utility that interprets escape sequences, - such as <filename>printf</filename> or - <filename>echo -n</filename>. - </note> - </para> - </section> - - <section id='variable-expansion'> - <title>Variable Expansion</title> - - <para> - Variables can reference the contents of other variables - using a syntax that is similar to variable expansion in - Bourne shells. - The following assignments - result in A containing "aval" and B evaluating to "preavalpost". - <literallayout class='monospaced'> - A = "aval" - B = "pre${A}post" - </literallayout> - <note> - Unlike in Bourne shells, the curly braces are mandatory: - Only <filename>${FOO}</filename> and not - <filename>$FOO</filename> is recognized as an expansion of - <filename>FOO</filename>. - </note> - The "=" operator does not immediately expand variable - references in the right-hand side. - Instead, expansion is deferred until the variable assigned to - is actually used. - The result depends on the current values of the referenced - variables. - The following example should clarify this behavior: - <literallayout class='monospaced'> - A = "${B} baz" - B = "${C} bar" - C = "foo" - *At this point, ${A} equals "foo bar baz"* - C = "qux" - *At this point, ${A} equals "qux bar baz"* - B = "norf" - *At this point, ${A} equals "norf baz"* - </literallayout> - Contrast this behavior with the - <link linkend='immediate-variable-expansion'>immediate variable expansion</link> - operator (i.e. ":="). - </para> - - <para> - If the variable expansion syntax is used on a variable that - does not exist, the string is kept as is. - For example, given the following assignment, - <filename>BAR</filename> expands to the literal string - "${FOO}" as long as <filename>FOO</filename> does not exist. - <literallayout class='monospaced'> - BAR = "${FOO}" - </literallayout> - </para> - </section> - - <section id='setting-a-default-value'> - <title>Setting a default value (?=)</title> - - <para> - You can use the "?=" operator to achieve a "softer" assignment - for a variable. - This type of assignment allows you to define a variable if it - is undefined when the statement is parsed, but to leave the - value alone if the variable has a value. - Here is an example: - <literallayout class='monospaced'> - A ?= "aval" - </literallayout> - If <filename>A</filename> is set at the time this statement is parsed, - the variable retains its value. - However, if <filename>A</filename> is not set, - the variable is set to "aval". - <note> - This assignment is immediate. - Consequently, if multiple "?=" assignments - to a single variable exist, the first of those ends up getting - used. - </note> - </para> - </section> - - <section id='setting-a-weak-default-value'> - <title>Setting a weak default value (??=)</title> - - <para> - It is possible to use a "weaker" assignment than in the - previous section by using the "??=" operator. - This assignment behaves identical to "?=" except that the - assignment is made at the end of the parsing process rather - than immediately. - Consequently, when multiple "??=" assignments exist, the last - one is used. - Also, any "=" or "?=" assignment will override the value set with - "??=". - Here is an example: - <literallayout class='monospaced'> - A ??= "somevalue" - A ??= "someothervalue" - </literallayout> - If <filename>A</filename> is set before the above statements are parsed, - the variable retains its value. - If <filename>A</filename> is not set, - the variable is set to "someothervalue". - </para> - - <para> - Again, this assignment is a "lazy" or "weak" assignment - because it does not occur until the end - of the parsing process. - </para> - </section> - - <section id='immediate-variable-expansion'> - <title>Immediate variable expansion (:=)</title> - - <para> - The ":=" operator results in a variable's - contents being expanded immediately, - rather than when the variable is actually used: - <literallayout class='monospaced'> - T = "123" - A := "test ${T}" - T = "456" - B := "${T} ${C}" - C = "cval" - C := "${C}append" - </literallayout> - In this example, <filename>A</filename> contains - "test 123", even though the final value of <filename>T</filename> - is "456". - The variable <filename>B</filename> will end up containing "456 cvalappend". - This is because references to undefined variables are preserved as is - during (immediate)expansion. This is in contrast to GNU Make, where undefined - variables expand to nothing. - The variable <filename>C</filename> - contains "cvalappend" since <filename>${C}</filename> immediately - expands to "cval". - </para> - </section> - - <section id='appending-and-prepending'> - <title>Appending (+=) and prepending (=+) With Spaces</title> - - <para> - Appending and prepending values is common and can be accomplished - using the "+=" and "=+" operators. - These operators insert a space between the current - value and prepended or appended value. - </para> - - <para> - These operators take immediate effect during parsing. - Here are some examples: - <literallayout class='monospaced'> - B = "bval" - B += "additionaldata" - C = "cval" - C =+ "test" - </literallayout> - The variable <filename>B</filename> contains - "bval additionaldata" and <filename>C</filename> - contains "test cval". - </para> - </section> - - <section id='appending-and-prepending-without-spaces'> - <title>Appending (.=) and Prepending (=.) Without Spaces</title> - - <para> - If you want to append or prepend values without an - inserted space, use the ".=" and "=." operators. - </para> - - <para> - These operators take immediate effect during parsing. - Here are some examples: - <literallayout class='monospaced'> - B = "bval" - B .= "additionaldata" - C = "cval" - C =. "test" - </literallayout> - The variable <filename>B</filename> contains - "bvaladditionaldata" and - <filename>C</filename> contains "testcval". - </para> - </section> - - <section id='appending-and-prepending-override-style-syntax'> - <title>Appending and Prepending (Override Style Syntax)</title> - - <para> - You can also append and prepend a variable's value - using an override style syntax. - When you use this syntax, no spaces are inserted. - </para> - - <para> - These operators differ from the ":=", ".=", "=.", "+=", and "=+" - operators in that their effects are applied at variable - expansion time rather than being immediately applied. - Here are some examples: - <literallayout class='monospaced'> - B = "bval" - B_append = " additional data" - C = "cval" - C_prepend = "additional data " - D = "dval" - D_append = "additional data" - </literallayout> - The variable <filename>B</filename> becomes - "bval additional data" and <filename>C</filename> becomes - "additional data cval". - The variable <filename>D</filename> becomes - "dvaladditional data". - <note> - You must control all spacing when you use the - override syntax. - </note> - </para> - - <para> - It is also possible to append and prepend to shell - functions and BitBake-style Python functions. - See the - "<link linkend='shell-functions'>Shell Functions</link>" and - "<link linkend='bitbake-style-python-functions'>BitBake-Style Python Functions</link> - sections for examples. - </para> - </section> - - <section id='removing-override-style-syntax'> - <title>Removal (Override Style Syntax)</title> - - <para> - You can remove values from lists using the removal - override style syntax. - Specifying a value for removal causes all occurrences of that - value to be removed from the variable. - </para> - - <para> - When you use this syntax, BitBake expects one or more strings. - Surrounding spaces and spacing are preserved. - Here is an example: - <literallayout class='monospaced'> - FOO = "123 456 789 123456 123 456 123 456" - FOO_remove = "123" - FOO_remove = "456" - FOO2 = " abc def ghi abcdef abc def abc def def" - FOO2_remove = " \ - def \ - abc \ - ghi \ - " - </literallayout> - The variable <filename>FOO</filename> becomes - " 789 123456 " - and <filename>FOO2</filename> becomes - " abcdef ". - </para> - - <para> - Like "_append" and "_prepend", "_remove" - is applied at variable expansion time. - </para> - </section> - - <section id='override-style-operation-advantages'> - <title>Override Style Operation Advantages</title> - - <para> - An advantage of the override style operations - "_append", "_prepend", and "_remove" as compared to the - "+=" and "=+" operators is that the override style - operators provide guaranteed operations. - For example, consider a class <filename>foo.bbclass</filename> - that needs to add the value "val" to the variable - <filename>FOO</filename>, and a recipe that uses - <filename>foo.bbclass</filename> as follows: - <literallayout class='monospaced'> - inherit foo - - FOO = "initial" - </literallayout> - If <filename>foo.bbclass</filename> uses the "+=" operator, - as follows, then the final value of <filename>FOO</filename> - will be "initial", which is not what is desired: - <literallayout class='monospaced'> - FOO += "val" - </literallayout> - If, on the other hand, <filename>foo.bbclass</filename> - uses the "_append" operator, then the final value of - <filename>FOO</filename> will be "initial val", as intended: - <literallayout class='monospaced'> - FOO_append = " val" - </literallayout> - <note> - It is never necessary to use "+=" together with "_append". - The following sequence of assignments appends "barbaz" to - <filename>FOO</filename>: - <literallayout class='monospaced'> - FOO_append = "bar" - FOO_append = "baz" - </literallayout> - The only effect of changing the second assignment in the - previous example to use "+=" would be to add a space before - "baz" in the appended value (due to how the "+=" operator - works). - </note> - Another advantage of the override style operations is that - you can combine them with other overrides as described in the - "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>" - section. - </para> - </section> - - <section id='variable-flag-syntax'> - <title>Variable Flag Syntax</title> - - <para> - Variable flags are BitBake's implementation of variable properties - or attributes. - It is a way of tagging extra information onto a variable. - You can find more out about variable flags in general in the - "<link linkend='variable-flags'>Variable Flags</link>" - section. - </para> - - <para> - You can define, append, and prepend values to variable flags. - All the standard syntax operations previously mentioned work - for variable flags except for override style syntax - (i.e. "_prepend", "_append", and "_remove"). - </para> - - <para> - Here are some examples showing how to set variable flags: - <literallayout class='monospaced'> - FOO[a] = "abc" - FOO[b] = "123" - FOO[a] += "456" - </literallayout> - The variable <filename>FOO</filename> has two flags: - <filename>[a]</filename> and <filename>[b]</filename>. - The flags are immediately set to "abc" and "123", respectively. - The <filename>[a]</filename> flag becomes "abc 456". - </para> - - <para> - No need exists to pre-define variable flags. - You can simply start using them. - One extremely common application - is to attach some brief documentation to a BitBake variable as - follows: - <literallayout class='monospaced'> - CACHE[doc] = "The directory holding the cache of the metadata." - </literallayout> - </para> - </section> - - <section id='inline-python-variable-expansion'> - <title>Inline Python Variable Expansion</title> - - <para> - You can use inline Python variable expansion to - set variables. - Here is an example: - <literallayout class='monospaced'> - DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" - </literallayout> - This example results in the <filename>DATE</filename> - variable being set to the current date. - </para> - - <para> - Probably the most common use of this feature is to extract - the value of variables from BitBake's internal data dictionary, - <filename>d</filename>. - The following lines select the values of a package name - and its version number, respectively: - <literallayout class='monospaced'> - PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" - PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" - </literallayout> - <note> - Inline Python expressions work just like variable expansions - insofar as the "=" and ":=" operators are concerned. - Given the following assignment, <filename>foo()</filename> - is called each time <filename>FOO</filename> is expanded: - <literallayout class='monospaced'> - FOO = "${@foo()}" - </literallayout> - Contrast this with the following immediate assignment, where - <filename>foo()</filename> is only called once, while the - assignment is parsed: - <literallayout class='monospaced'> - FOO := "${@foo()}" - </literallayout> - </note> - For a different way to set variables with Python code during - parsing, see the - "<link linkend='anonymous-python-functions'>Anonymous Python Functions</link>" - section. - </para> - </section> - - <section id='unsetting-variables'> - <title>Unsetting variables</title> - - <para> - It is possible to completely remove a variable or a variable flag - from BitBake's internal data dictionary by using the "unset" keyword. - Here is an example: - <literallayout class='monospaced'> - unset DATE - unset do_fetch[noexec] - </literallayout> - These two statements remove the <filename>DATE</filename> and the - <filename>do_fetch[noexec]</filename> flag. - </para> - - </section> - - <section id='providing-pathnames'> - <title>Providing Pathnames</title> - - <para> - When specifying pathnames for use with BitBake, - do not use the tilde ("~") character as a shortcut - for your home directory. - Doing so might cause BitBake to not recognize the - path since BitBake does not expand this character in - the same way a shell would. - </para> - - <para> - Instead, provide a fuller path as the following - example illustrates: - <literallayout class='monospaced'> - BBLAYERS ?= " \ - /home/scott-lenovo/LayerA \ - " - </literallayout> - </para> - </section> - </section> - - <section id='exporting-variables-to-the-environment'> - <title>Exporting Variables to the Environment</title> - - <para> - You can export variables to the environment of running - tasks by using the <filename>export</filename> keyword. - For example, in the following example, the - <filename>do_foo</filename> task prints "value from - the environment" when run: - <literallayout class='monospaced'> - export ENV_VARIABLE - ENV_VARIABLE = "value from the environment" - - do_foo() { - bbplain "$ENV_VARIABLE" - } - </literallayout> - <note> - BitBake does not expand <filename>$ENV_VARIABLE</filename> - in this case because it lacks the obligatory - <filename>{}</filename>. - Rather, <filename>$ENV_VARIABLE</filename> is expanded - by the shell. - </note> - It does not matter whether - <filename>export ENV_VARIABLE</filename> appears before or - after assignments to <filename>ENV_VARIABLE</filename>. - </para> - - <para> - It is also possible to combine <filename>export</filename> - with setting a value for the variable. - Here is an example: - <literallayout class='monospaced'> - export ENV_VARIABLE = "<replaceable>variable-value</replaceable>" - </literallayout> - In the output of <filename>bitbake -e</filename>, variables - that are exported to the environment are preceded by "export". - </para> - - <para> - Among the variables commonly exported to the environment - are <filename>CC</filename> and <filename>CFLAGS</filename>, - which are picked up by many build systems. - </para> - </section> - - <section id='conditional-syntax-overrides'> - <title>Conditional Syntax (Overrides)</title> - - <para> - BitBake uses - <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> - to control what variables are overridden after BitBake - parses recipes and configuration files. - This section describes how you can use - <filename>OVERRIDES</filename> as conditional metadata, - talks about key expansion in relationship to - <filename>OVERRIDES</filename>, and provides some examples - to help with understanding. - </para> - - <section id='conditional-metadata'> - <title>Conditional Metadata</title> - - <para> - You can use <filename>OVERRIDES</filename> to conditionally select - a specific version of a variable and to conditionally - append or prepend the value of a variable. - <note> - Overrides can only use lower-case characters. - Additionally, underscores are not permitted in override names - as they are used to separate overrides from each other and - from the variable name. - </note> - <itemizedlist> - <listitem><para><emphasis>Selecting a Variable:</emphasis> - The <filename>OVERRIDES</filename> variable is - a colon-character-separated list that contains items - for which you want to satisfy conditions. - Thus, if you have a variable that is conditional on “arm”, and “arm” - is in <filename>OVERRIDES</filename>, then the “arm”-specific - version of the variable is used rather than the non-conditional - version. - Here is an example: - <literallayout class='monospaced'> - OVERRIDES = "architecture:os:machine" - TEST = "default" - TEST_os = "osspecific" - TEST_nooverride = "othercondvalue" - </literallayout> - In this example, the <filename>OVERRIDES</filename> - variable lists three overrides: - "architecture", "os", and "machine". - The variable <filename>TEST</filename> by itself has a default - value of "default". - You select the os-specific version of the <filename>TEST</filename> - variable by appending the "os" override to the variable - (i.e.<filename>TEST_os</filename>). - </para> - - <para> - To better understand this, consider a practical example - that assumes an OpenEmbedded metadata-based Linux - kernel recipe file. - The following lines from the recipe file first set - the kernel branch variable <filename>KBRANCH</filename> - to a default value, then conditionally override that - value based on the architecture of the build: - <literallayout class='monospaced'> - KBRANCH = "standard/base" - KBRANCH_qemuarm = "standard/arm-versatile-926ejs" - KBRANCH_qemumips = "standard/mti-malta32" - KBRANCH_qemuppc = "standard/qemuppc" - KBRANCH_qemux86 = "standard/common-pc/base" - KBRANCH_qemux86-64 = "standard/common-pc-64/base" - KBRANCH_qemumips64 = "standard/mti-malta64" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Appending and Prepending:</emphasis> - BitBake also supports append and prepend operations to - variable values based on whether a specific item is - listed in <filename>OVERRIDES</filename>. - Here is an example: - <literallayout class='monospaced'> - DEPENDS = "glibc ncurses" - OVERRIDES = "machine:local" - DEPENDS_append_machine = " libmad" - </literallayout> - In this example, <filename>DEPENDS</filename> becomes - "glibc ncurses libmad". - </para> - - <para> - Again, using an OpenEmbedded metadata-based - kernel recipe file as an example, the - following lines will conditionally append to the - <filename>KERNEL_FEATURES</filename> variable based - on the architecture: - <literallayout class='monospaced'> - KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" - KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" - KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Setting a Variable for a Single Task:</emphasis> - BitBake supports setting a variable just for the - duration of a single task. - Here is an example: - <literallayout class='monospaced'> - FOO_task-configure = "val 1" - FOO_task-compile = "val 2" - </literallayout> - In the previous example, <filename>FOO</filename> - has the value "val 1" while the - <filename>do_configure</filename> task is executed, - and the value "val 2" while the - <filename>do_compile</filename> task is executed. - </para> - - <para>Internally, this is implemented by prepending - the task (e.g. "task-compile:") to the value of - <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> - for the local datastore of the <filename>do_compile</filename> - task.</para> - - <para>You can also use this syntax with other combinations - (e.g. "<filename>_prepend</filename>") as shown in the - following example: - <literallayout class='monospaced'> - EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " - </literallayout> - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='key-expansion'> - <title>Key Expansion</title> - - <para> - Key expansion happens when the BitBake datastore is finalized. - To better understand this, consider the following example: - <literallayout class='monospaced'> - A${B} = "X" - B = "2" - A2 = "Y" - </literallayout> - In this case, after all the parsing is complete, - BitBake expands <filename>${B}</filename> into "2". - This expansion causes <filename>A2</filename>, which was - set to "Y" before the expansion, to become "X". - </para> - </section> - - <section id='variable-interaction-worked-examples'> - <title>Examples</title> - - <para> - Despite the previous explanations that show the different forms of - variable definitions, it can be hard to work - out exactly what happens when variable operators, conditional - overrides, and unconditional overrides are combined. - This section presents some common scenarios along - with explanations for variable interactions that - typically confuse users. - </para> - - <para> - There is often confusion concerning the order in which - overrides and various "append" operators take effect. - Recall that an append or prepend operation using "_append" - and "_prepend" does not result in an immediate assignment - as would "+=", ".=", "=+", or "=.". - Consider the following example: - <literallayout class='monospaced'> - OVERRIDES = "foo" - A = "Z" - A_foo_append = "X" - </literallayout> - For this case, <filename>A</filename> is - unconditionally set to "Z" and "X" is - unconditionally and immediately appended to the variable - <filename>A_foo</filename>. - Because overrides have not been applied yet, - <filename>A_foo</filename> is set to "X" due to the append - and <filename>A</filename> simply equals "Z". - </para> - - <para> - Applying overrides, however, changes things. - Since "foo" is listed in <filename>OVERRIDES</filename>, - the conditional variable <filename>A</filename> is replaced - with the "foo" version, which is equal to "X". - So effectively, <filename>A_foo</filename> replaces <filename>A</filename>. - </para> - - <para> - This next example changes the order of the override and - the append: - <literallayout class='monospaced'> - OVERRIDES = "foo" - A = "Z" - A_append_foo = "X" - </literallayout> - For this case, before overrides are handled, - <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename> - is set to "X". - Once the override for "foo" is applied, however, - <filename>A</filename> gets appended with "X". - Consequently, <filename>A</filename> becomes "ZX". - Notice that spaces are not appended. - </para> - - <para> - This next example has the order of the appends and overrides reversed - back as in the first example: - <literallayout class='monospaced'> - OVERRIDES = "foo" - A = "Y" - A_foo_append = "Z" - A_foo_append = "X" - </literallayout> - For this case, before any overrides are resolved, - <filename>A</filename> is set to "Y" using an immediate assignment. - After this immediate assignment, <filename>A_foo</filename> is set - to "Z", and then further appended with - "X" leaving the variable set to "ZX". - Finally, applying the override for "foo" results in the conditional - variable <filename>A</filename> becoming "ZX" (i.e. - <filename>A</filename> is replaced with <filename>A_foo</filename>). - </para> - - <para> - This final example mixes in some varying operators: - <literallayout class='monospaced'> - A = "1" - A_append = "2" - A_append = "3" - A += "4" - A .= "5" - </literallayout> - For this case, the type of append operators are affecting the - order of assignments as BitBake passes through the code - multiple times. - Initially, <filename>A</filename> is set to "1 45" because - of the three statements that use immediate operators. - After these assignments are made, BitBake applies the - "_append" operations. - Those operations result in <filename>A</filename> becoming "1 4523". - </para> - </section> - </section> - - <section id='sharing-functionality'> - <title>Sharing Functionality</title> - - <para> - BitBake allows for metadata sharing through include files - (<filename>.inc</filename>) and class files - (<filename>.bbclass</filename>). - For example, suppose you have a piece of common functionality - such as a task definition that you want to share between - more than one recipe. - In this case, creating a <filename>.bbclass</filename> - file that contains the common functionality and then using - the <filename>inherit</filename> directive in your recipes to - inherit the class would be a common way to share the task. - </para> - - <para> - This section presents the mechanisms BitBake provides to - allow you to share functionality between recipes. - Specifically, the mechanisms include <filename>include</filename>, - <filename>inherit</filename>, <filename>INHERIT</filename>, and - <filename>require</filename> directives. - </para> - - <section id='locating-include-and-class-files'> - <title>Locating Include and Class Files</title> - - <para> - BitBake uses the - <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link> - variable to locate needed include and class files. - Additionally, BitBake searches the current directory for - <filename>include</filename> and <filename>require</filename> - directives. - <note> - The <filename>BBPATH</filename> variable is analogous to - the environment variable <filename>PATH</filename>. - </note> - </para> - - <para> - In order for include and class files to be found by BitBake, - they need to be located in a "classes" subdirectory that can - be found in <filename>BBPATH</filename>. - </para> - </section> - - <section id='inherit-directive'> - <title><filename>inherit</filename> Directive</title> - - <para> - When writing a recipe or class file, you can use the - <filename>inherit</filename> directive to inherit the - functionality of a class (<filename>.bbclass</filename>). - BitBake only supports this directive when used within recipe - and class files (i.e. <filename>.bb</filename> and - <filename>.bbclass</filename>). - </para> - - <para> - The <filename>inherit</filename> directive is a rudimentary - means of specifying functionality contained in class files - that your recipes require. - For example, you can easily abstract out the tasks involved in - building a package that uses Autoconf and Automake and put - those tasks into a class file and then have your recipe - inherit that class file. - </para> - - <para> - As an example, your recipes could use the following directive - to inherit an <filename>autotools.bbclass</filename> file. - The class file would contain common functionality for using - Autotools that could be shared across recipes: - <literallayout class='monospaced'> - inherit autotools - </literallayout> - In this case, BitBake would search for the directory - <filename>classes/autotools.bbclass</filename> - in <filename>BBPATH</filename>. - <note> - You can override any values and functions of the - inherited class within your recipe by doing so - after the "inherit" statement. - </note> - If you want to use the directive to inherit - multiple classes, separate them with spaces. - The following example shows how to inherit both the - <filename>buildhistory</filename> and <filename>rm_work</filename> - classes: - <literallayout class='monospaced'> - inherit buildhistory rm_work - </literallayout> - </para> - - <para> - An advantage with the inherit directive as compared to both - the - <link linkend='include-directive'>include</link> and - <link linkend='require-inclusion'>require</link> directives - is that you can inherit class files conditionally. - You can accomplish this by using a variable expression - after the <filename>inherit</filename> statement. - Here is an example: - <literallayout class='monospaced'> - inherit ${VARNAME} - </literallayout> - If <filename>VARNAME</filename> is going to be set, it needs - to be set before the <filename>inherit</filename> statement - is parsed. - One way to achieve a conditional inherit in this case is to use - overrides: - <literallayout class='monospaced'> - VARIABLE = "" - VARIABLE_someoverride = "myclass" - </literallayout> - </para> - - <para> - Another method is by using anonymous Python. - Here is an example: - <literallayout class='monospaced'> - python () { - if condition == value: - d.setVar('VARIABLE', 'myclass') - else: - d.setVar('VARIABLE', '') - } - </literallayout> - </para> - - <para> - Alternatively, you could use an in-line Python expression - in the following form: - <literallayout class='monospaced'> - inherit ${@'classname' if condition else ''} - inherit ${@functionname(params)} - </literallayout> - In all cases, if the expression evaluates to an empty - string, the statement does not trigger a syntax error - because it becomes a no-op. - </para> - </section> - - <section id='include-directive'> - <title><filename>include</filename> Directive</title> - - <para> - BitBake understands the <filename>include</filename> - directive. - This directive causes BitBake to parse whatever file you specify, - and to insert that file at that location. - The directive is much like its equivalent in Make except - that if the path specified on the include line is a relative - path, BitBake locates the first file it can find - within <filename>BBPATH</filename>. - </para> - - <para> - The include directive is a more generic method of including - functionality as compared to the - <link linkend='inherit-directive'>inherit</link> directive, - which is restricted to class (i.e. <filename>.bbclass</filename>) - files. - The include directive is applicable for any other kind of - shared or encapsulated functionality or configuration that - does not suit a <filename>.bbclass</filename> file. - </para> - - <para> - As an example, suppose you needed a recipe to include some - self-test definitions: - <literallayout class='monospaced'> - include test_defs.inc - </literallayout> - <note> - The <filename>include</filename> directive does not - produce an error when the file cannot be found. - Consequently, it is recommended that if the file you - are including is expected to exist, you should use - <link linkend='require-inclusion'><filename>require</filename></link> - instead of <filename>include</filename>. - Doing so makes sure that an error is produced if the - file cannot be found. - </note> - </para> - </section> - - <section id='require-inclusion'> - <title><filename>require</filename> Directive</title> - - <para> - BitBake understands the <filename>require</filename> - directive. - This directive behaves just like the - <filename>include</filename> directive with the exception that - BitBake raises a parsing error if the file to be included cannot - be found. - Thus, any file you require is inserted into the file that is - being parsed at the location of the directive. - </para> - - <para> - The require directive, like the include directive previously - described, is a more generic method of including - functionality as compared to the - <link linkend='inherit-directive'>inherit</link> directive, - which is restricted to class (i.e. <filename>.bbclass</filename>) - files. - The require directive is applicable for any other kind of - shared or encapsulated functionality or configuration that - does not suit a <filename>.bbclass</filename> file. - </para> - - <para> - Similar to how BitBake handles - <link linkend='include-directive'><filename>include</filename></link>, - if the path specified - on the require line is a relative path, BitBake locates - the first file it can find within <filename>BBPATH</filename>. - </para> - - <para> - As an example, suppose you have two versions of a recipe - (e.g. <filename>foo_1.2.2.bb</filename> and - <filename>foo_2.0.0.bb</filename>) where - each version contains some identical functionality that could be - shared. - You could create an include file named <filename>foo.inc</filename> - that contains the common definitions needed to build "foo". - You need to be sure <filename>foo.inc</filename> is located in the - same directory as your two recipe files as well. - Once these conditions are set up, you can share the functionality - using a <filename>require</filename> directive from within each - recipe: - <literallayout class='monospaced'> - require foo.inc - </literallayout> - </para> - </section> - - <section id='inherit-configuration-directive'> - <title><filename>INHERIT</filename> Configuration Directive</title> - - <para> - When creating a configuration file (<filename>.conf</filename>), - you can use the - <link linkend='var-bb-INHERIT'><filename>INHERIT</filename></link> - configuration directive to inherit a class. - BitBake only supports this directive when used within - a configuration file. - </para> - - <para> - As an example, suppose you needed to inherit a class - file called <filename>abc.bbclass</filename> from a - configuration file as follows: - <literallayout class='monospaced'> - INHERIT += "abc" - </literallayout> - This configuration directive causes the named - class to be inherited at the point of the directive - during parsing. - As with the <filename>inherit</filename> directive, the - <filename>.bbclass</filename> file must be located in a - "classes" subdirectory in one of the directories specified - in <filename>BBPATH</filename>. - <note> - Because <filename>.conf</filename> files are parsed - first during BitBake's execution, using - <filename>INHERIT</filename> to inherit a class effectively - inherits the class globally (i.e. for all recipes). - </note> - If you want to use the directive to inherit - multiple classes, you can provide them on the same line in the - <filename>local.conf</filename> file. - Use spaces to separate the classes. - The following example shows how to inherit both the - <filename>autotools</filename> and <filename>pkgconfig</filename> - classes: - <literallayout class='monospaced'> - INHERIT += "autotools pkgconfig" - </literallayout> - </para> - </section> - </section> - - <section id='functions'> - <title>Functions</title> - - <para> - As with most languages, functions are the building blocks that - are used to build up operations into tasks. - BitBake supports these types of functions: - <itemizedlist> - <listitem><para><emphasis>Shell Functions:</emphasis> - Functions written in shell script and executed either - directly as functions, tasks, or both. - They can also be called by other shell functions. - </para></listitem> - <listitem><para><emphasis>BitBake-Style Python Functions:</emphasis> - Functions written in Python and executed by BitBake or other - Python functions using <filename>bb.build.exec_func()</filename>. - </para></listitem> - <listitem><para><emphasis>Python Functions:</emphasis> - Functions written in Python and executed by Python. - </para></listitem> - <listitem><para><emphasis>Anonymous Python Functions:</emphasis> - Python functions executed automatically during - parsing. - </para></listitem> - </itemizedlist> - Regardless of the type of function, you can only - define them in class (<filename>.bbclass</filename>) - and recipe (<filename>.bb</filename> or <filename>.inc</filename>) - files. - </para> - - <section id='shell-functions'> - <title>Shell Functions</title> - - <para> - Functions written in shell script and executed either - directly as functions, tasks, or both. - They can also be called by other shell functions. - Here is an example shell function definition: - <literallayout class='monospaced'> - some_function () { - echo "Hello World" - } - </literallayout> - When you create these types of functions in your recipe - or class files, you need to follow the shell programming - rules. - The scripts are executed by <filename>/bin/sh</filename>, - which may not be a bash shell but might be something - such as <filename>dash</filename>. - You should not use Bash-specific script (bashisms). - </para> - - <para> - Overrides and override-style operators like - <filename>_append</filename> and - <filename>_prepend</filename> can also be applied to - shell functions. - Most commonly, this application would be used in a - <filename>.bbappend</filename> file to modify functions in - the main recipe. - It can also be used to modify functions inherited from - classes. - </para> - - <para> - As an example, consider the following: - <literallayout class='monospaced'> - do_foo() { - bbplain first - fn - } - - fn_prepend() { - bbplain second - } - - fn() { - bbplain third - } - - do_foo_append() { - bbplain fourth - } - </literallayout> - Running <filename>do_foo</filename> - prints the following: - <literallayout class='monospaced'> - recipename do_foo: first - recipename do_foo: second - recipename do_foo: third - recipename do_foo: fourth - </literallayout> - <note> - Overrides and override-style operators can - be applied to any shell function, not just - <link linkend='tasks'>tasks</link>. - </note> - You can use the <filename>bitbake -e</filename> <replaceable>recipename</replaceable> - command to view the final assembled function - after all overrides have been applied. - </para> - </section> - - <section id='bitbake-style-python-functions'> - <title>BitBake-Style Python Functions</title> - - <para> - These functions are written in Python and executed by - BitBake or other Python functions using - <filename>bb.build.exec_func()</filename>. - </para> - - <para> - An example BitBake function is: - <literallayout class='monospaced'> - python some_python_function () { - d.setVar("TEXT", "Hello World") - print d.getVar("TEXT") - } - </literallayout> - Because the Python "bb" and "os" modules are already - imported, you do not need to import these modules. - Also in these types of functions, the datastore ("d") - is a global variable and is always automatically - available. - <note> - Variable expressions (e.g. <filename>${X}</filename>) - are no longer expanded within Python functions. - This behavior is intentional in order to allow you - to freely set variable values to expandable expressions - without having them expanded prematurely. - If you do wish to expand a variable within a Python - function, use <filename>d.getVar("X")</filename>. - Or, for more complicated expressions, use - <filename>d.expand()</filename>. - </note> - </para> - - <para> - Similar to shell functions, you can also apply overrides - and override-style operators to BitBake-style Python - functions. - </para> - - <para> - As an example, consider the following: - <literallayout class='monospaced'> - python do_foo_prepend() { - bb.plain("first") - } - - python do_foo() { - bb.plain("second") - } - - python do_foo_append() { - bb.plain("third") - } - </literallayout> - Running <filename>do_foo</filename> prints - the following: - <literallayout class='monospaced'> - recipename do_foo: first - recipename do_foo: second - recipename do_foo: third - </literallayout> - You can use the <filename>bitbake -e</filename> <replaceable>recipename</replaceable> - command to view the final assembled function - after all overrides have been applied. - </para> - </section> - - <section id='python-functions'> - <title>Python Functions</title> - - <para> - These functions are written in Python and are executed by - other Python code. - Examples of Python functions are utility functions - that you intend to call from in-line Python or - from within other Python functions. - Here is an example: - <literallayout class='monospaced'> - def get_depends(d): - if d.getVar('SOMECONDITION'): - return "dependencywithcond" - else: - return "dependency" - SOMECONDITION = "1" - DEPENDS = "${@get_depends(d)}" - </literallayout> - This would result in <filename>DEPENDS</filename> - containing <filename>dependencywithcond</filename>. - </para> - - <para> - Here are some things to know about Python functions: - <itemizedlist> - <listitem><para>Python functions can take parameters. - </para></listitem> - <listitem><para>The BitBake datastore is not - automatically available. - Consequently, you must pass it in as a - parameter to the function. - </para></listitem> - <listitem><para>The "bb" and "os" Python modules are - automatically available. - You do not need to import them. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='bitbake-style-python-functions-versus-python-functions'> - <title>BitBake-Style Python Functions Versus Python Functions</title> - - <para> - Following are some important differences between - BitBake-style Python functions and regular Python - functions defined with "def": - <itemizedlist> - <listitem><para> - Only BitBake-style Python functions can be - <link linkend='tasks'>tasks</link>. - </para></listitem> - <listitem><para> - Overrides and override-style operators can only - be applied to BitBake-style Python functions. - </para></listitem> - <listitem><para> - Only regular Python functions can take arguments - and return values. - </para></listitem> - <listitem><para> - <link linkend='variable-flags'>Variable flags</link> - such as <filename>[dirs]</filename>, - <filename>[cleandirs]</filename>, and - <filename>[lockfiles]</filename> can be used - on BitBake-style Python functions, but not on - regular Python functions. - </para></listitem> - <listitem><para> - BitBake-style Python functions generate a separate - <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}/run.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable> - script that is executed to run the function, and also - generate a log file in - <filename>${T}/log.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable> - if they are executed as tasks.</para> - - <para> - Regular Python functions execute "inline" and do not - generate any files in <filename>${T}</filename>. - </para></listitem> - <listitem><para> - Regular Python functions are called with the usual - Python syntax. - BitBake-style Python functions are usually tasks and - are called directly by BitBake, but can also be called - manually from Python code by using the - <filename>bb.build.exec_func()</filename> function. - Here is an example: - <literallayout class='monospaced'> - bb.build.exec_func("my_bitbake_style_function", d) - </literallayout> - <note> - <filename>bb.build.exec_func()</filename> can also - be used to run shell functions from Python code. - If you want to run a shell function before a Python - function within the same task, then you can use a - parent helper Python function that starts by running - the shell function with - <filename>bb.build.exec_func()</filename> and then - runs the Python code. - </note></para> - - <para>To detect errors from functions executed with - <filename>bb.build.exec_func()</filename>, you - can catch the <filename>bb.build.FuncFailed</filename> - exception. - <note> - Functions in metadata (recipes and classes) should - not themselves raise - <filename>bb.build.FuncFailed</filename>. - Rather, <filename>bb.build.FuncFailed</filename> - should be viewed as a general indicator that the - called function failed by raising an exception. - For example, an exception raised by - <filename>bb.fatal()</filename> will be caught inside - <filename>bb.build.exec_func()</filename>, and a - <filename>bb.build.FuncFailed</filename> will be raised - in response. - </note> - </para></listitem> - </itemizedlist> - </para> - - <para> - Due to their simplicity, you should prefer regular Python functions - over BitBake-style Python functions unless you need a feature specific - to BitBake-style Python functions. - Regular Python functions in metadata are a more recent invention than - BitBake-style Python functions, and older code tends to use - <filename>bb.build.exec_func()</filename> more often. - </para> - </section> - - <section id='anonymous-python-functions'> - <title>Anonymous Python Functions</title> - - <para> - Sometimes it is useful to set variables or perform - other operations programmatically during parsing. - To do this, you can define special Python functions, - called anonymous Python functions, that run at the - end of parsing. - For example, the following conditionally sets a variable - based on the value of another variable: - <literallayout class='monospaced'> - python () { - if d.getVar('SOMEVAR') == 'value': - d.setVar('ANOTHERVAR', 'value2') - } - </literallayout> - An equivalent way to mark a function as an anonymous - function is to give it the name "__anonymous", rather - than no name. - </para> - - <para> - Anonymous Python functions always run at the end - of parsing, regardless of where they are defined. - If a recipe contains many anonymous functions, they - run in the same order as they are defined within the - recipe. - As an example, consider the following snippet: - <literallayout class='monospaced'> - python () { - d.setVar('FOO', 'foo 2') - } - - FOO = "foo 1" - - python () { - d.appendVar('BAR', ' bar 2') - } - - BAR = "bar 1" - </literallayout> - The previous example is conceptually equivalent to the - following snippet: - <literallayout class='monospaced'> - FOO = "foo 1" - BAR = "bar 1" - FOO = "foo 2" - BAR += "bar 2" - </literallayout> - <filename>FOO</filename> ends up with the value "foo 2", - and <filename>BAR</filename> with the value "bar 1 bar 2". - Just as in the second snippet, the values set for the - variables within the anonymous functions become available - to tasks, which always run after parsing. - </para> - - <para> - Overrides and override-style operators such as - "<filename>_append</filename>" are applied before - anonymous functions run. - In the following example, <filename>FOO</filename> ends - up with the value "foo from anonymous": - <literallayout class='monospaced'> - FOO = "foo" - FOO_append = " from outside" - - python () { - d.setVar("FOO", "foo from anonymous") - } - </literallayout> - For methods you can use with anonymous Python functions, - see the - "<link linkend='functions-you-can-call-from-within-python'>Functions You Can Call From Within Python</link>" - section. - For a different method to run Python code during parsing, - see the - "<link linkend='inline-python-variable-expansion'>Inline Python Variable Expansion</link>" - section. - </para> - </section> - - <section id='flexible-inheritance-for-class-functions'> - <title>Flexible Inheritance for Class Functions</title> - - <para> - Through coding techniques and the use of - <filename>EXPORT_FUNCTIONS</filename>, BitBake supports - exporting a function from a class such that the - class function appears as the default implementation - of the function, but can still be called if a recipe - inheriting the class needs to define its own version of - the function. - </para> - - <para> - To understand the benefits of this feature, consider - the basic scenario where a class defines a task function - and your recipe inherits the class. - In this basic scenario, your recipe inherits the task - function as defined in the class. - If desired, your recipe can add to the start and end of the - function by using the "_prepend" or "_append" operations - respectively, or it can redefine the function completely. - However, if it redefines the function, there is - no means for it to call the class version of the function. - <filename>EXPORT_FUNCTIONS</filename> provides a mechanism - that enables the recipe's version of the function to call - the original version of the function. - </para> - - <para> - To make use of this technique, you need the following - things in place: - <itemizedlist> - <listitem><para> - The class needs to define the function as follows: - <literallayout class='monospaced'> - <replaceable>classname</replaceable><filename>_</filename><replaceable>functionname</replaceable> - </literallayout> - For example, if you have a class file - <filename>bar.bbclass</filename> and a function named - <filename>do_foo</filename>, the class must define the function - as follows: - <literallayout class='monospaced'> - bar_do_foo - </literallayout> - </para></listitem> - <listitem><para> - The class needs to contain the <filename>EXPORT_FUNCTIONS</filename> - statement as follows: - <literallayout class='monospaced'> - EXPORT_FUNCTIONS <replaceable>functionname</replaceable> - </literallayout> - For example, continuing with the same example, the - statement in the <filename>bar.bbclass</filename> would be - as follows: - <literallayout class='monospaced'> - EXPORT_FUNCTIONS do_foo - </literallayout> - </para></listitem> - <listitem><para> - You need to call the function appropriately from within your - recipe. - Continuing with the same example, if your recipe - needs to call the class version of the function, - it should call <filename>bar_do_foo</filename>. - Assuming <filename>do_foo</filename> was a shell function - and <filename>EXPORT_FUNCTIONS</filename> was used as above, - the recipe's function could conditionally call the - class version of the function as follows: - <literallayout class='monospaced'> - do_foo() { - if [ somecondition ] ; then - bar_do_foo - else - # Do something else - fi - } - </literallayout> - To call your modified version of the function as defined - in your recipe, call it as <filename>do_foo</filename>. - </para></listitem> - </itemizedlist> - With these conditions met, your single recipe - can freely choose between the original function - as defined in the class file and the modified function in your recipe. - If you do not set up these conditions, you are limited to using one function - or the other. - </para> - </section> - </section> - - <section id='tasks'> - <title>Tasks</title> - - <para> - Tasks are BitBake execution units that make up the - steps that BitBake can run for a given recipe. - Tasks are only supported in recipes and classes - (i.e. in <filename>.bb</filename> files and files - included or inherited from <filename>.bb</filename> - files). - By convention, tasks have names that start with "do_". - </para> - - <section id='promoting-a-function-to-a-task'> - <title>Promoting a Function to a Task</title> - - <para> - Tasks are either - <link linkend='shell-functions'>shell functions</link> or - <link linkend='bitbake-style-python-functions'>BitBake-style Python functions</link> - that have been promoted to tasks by using the - <filename>addtask</filename> command. - The <filename>addtask</filename> command can also - optionally describe dependencies between the - task and other tasks. - Here is an example that shows how to define a task - and declare some dependencies: - <literallayout class='monospaced'> - python do_printdate () { - import time - print time.strftime('%Y%m%d', time.gmtime()) - } - addtask printdate after do_fetch before do_build - </literallayout> - The first argument to <filename>addtask</filename> - is the name of the function to promote to - a task. - If the name does not start with "do_", "do_" is - implicitly added, which enforces the convention that - all task names start with "do_". - </para> - - <para> - In the previous example, the - <filename>do_printdate</filename> task becomes a - dependency of the <filename>do_build</filename> - task, which is the default task (i.e. the task run by - the <filename>bitbake</filename> command unless - another task is specified explicitly). - Additionally, the <filename>do_printdate</filename> - task becomes dependent upon the - <filename>do_fetch</filename> task. - Running the <filename>do_build</filename> task - results in the <filename>do_printdate</filename> - task running first. - <note> - If you try out the previous example, you might see that - the <filename>do_printdate</filename> task is only run - the first time you build the recipe with - the <filename>bitbake</filename> command. - This is because BitBake considers the task "up-to-date" - after that initial run. - If you want to force the task to always be rerun for - experimentation purposes, you can make BitBake always - consider the task "out-of-date" by using the - <filename>[</filename><link linkend='variable-flags'><filename>nostamp</filename></link><filename>]</filename> - variable flag, as follows: - <literallayout class='monospaced'> - do_printdate[nostamp] = "1" - </literallayout> - You can also explicitly run the task and provide the - <filename>-f</filename> option as follows: - <literallayout class='monospaced'> - $ bitbake <replaceable>recipe</replaceable> -c printdate -f - </literallayout> - When manually selecting a task to run with the - <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c</filename> <replaceable>task</replaceable> - command, you can omit the "do_" prefix as part of the - task name. - </note> - </para> - - <para> - You might wonder about the practical effects of using - <filename>addtask</filename> without specifying any - dependencies as is done in the following example: - <literallayout class='monospaced'> - addtask printdate - </literallayout> - In this example, assuming dependencies have not been - added through some other means, the only way to run - the task is by explicitly selecting it with - <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c printdate</filename>. - You can use the - <filename>do_listtasks</filename> task to list all tasks - defined in a recipe as shown in the following example: - <literallayout class='monospaced'> - $ bitbake <replaceable>recipe</replaceable> -c listtasks - </literallayout> - For more information on task dependencies, see the - "<link linkend='dependencies'>Dependencies</link>" - section. - </para> - - <para> - See the - "<link linkend='variable-flags'>Variable Flags</link>" - section for information on variable flags you can use with - tasks. - </para> - </section> - - <section id='deleting-a-task'> - <title>Deleting a Task</title> - - <para> - As well as being able to add tasks, you can delete them. - Simply use the <filename>deltask</filename> command to - delete a task. - For example, to delete the example task used in the previous - sections, you would use: - <literallayout class='monospaced'> - deltask printdate - </literallayout> - If you delete a task using the <filename>deltask</filename> - command and the task has dependencies, the dependencies are - not reconnected. - For example, suppose you have three tasks named - <filename>do_a</filename>, <filename>do_b</filename>, and - <filename>do_c</filename>. - Furthermore, <filename>do_c</filename> is dependent on - <filename>do_b</filename>, which in turn is dependent on - <filename>do_a</filename>. - Given this scenario, if you use <filename>deltask</filename> - to delete <filename>do_b</filename>, the implicit dependency - relationship between <filename>do_c</filename> and - <filename>do_a</filename> through <filename>do_b</filename> - no longer exists, and <filename>do_c</filename> dependencies - are not updated to include <filename>do_a</filename>. - Thus, <filename>do_c</filename> is free to run before - <filename>do_a</filename>. - </para> - - <para> - If you want dependencies such as these to remain intact, use - the <filename>[noexec]</filename> varflag to disable the task - instead of using the <filename>deltask</filename> command to - delete it: - <literallayout class='monospaced'> - do_b[noexec] = "1" - </literallayout> - </para> - </section> - - <section id='passing-information-into-the-build-task-environment'> - <title>Passing Information Into the Build Task Environment</title> - - <para> - When running a task, BitBake tightly controls the shell execution - environment of the build tasks to make - sure unwanted contamination from the build machine cannot - influence the build. - <note> - By default, BitBake cleans the environment to include only those - things exported or listed in its whitelist to ensure that the build - environment is reproducible and consistent. - You can prevent this "cleaning" by setting the - <link linkend='var-bb-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link> - variable. - </note> - Consequently, if you do want something to get passed into the - build task environment, you must take these two steps: - <orderedlist> - <listitem><para> - Tell BitBake to load what you want from the environment - into the datastore. - You can do so through the - <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link> - and - <link linkend='var-bb-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link> - variables. - For example, assume you want to prevent the build system from - accessing your <filename>$HOME/.ccache</filename> - directory. - The following command "whitelists" the environment variable - <filename>CCACHE_DIR</filename> causing BitBake to allow that - variable into the datastore: - <literallayout class='monospaced'> - export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" - </literallayout></para></listitem> - <listitem><para> - Tell BitBake to export what you have loaded into the - datastore to the task environment of every running task. - Loading something from the environment into the datastore - (previous step) only makes it available in the datastore. - To export it to the task environment of every running task, - use a command similar to the following in your local configuration - file <filename>local.conf</filename> or your - distribution configuration file: - <literallayout class='monospaced'> - export CCACHE_DIR - </literallayout> - <note> - A side effect of the previous steps is that BitBake - records the variable as a dependency of the build process - in things like the setscene checksums. - If doing so results in unnecessary rebuilds of tasks, you can - whitelist the variable so that the setscene code - ignores the dependency when it creates checksums. - </note></para></listitem> - </orderedlist> - </para> - - <para> - Sometimes, it is useful to be able to obtain information - from the original execution environment. - BitBake saves a copy of the original environment into - a special variable named - <link linkend='var-bb-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>. - </para> - - <para> - The <filename>BB_ORIGENV</filename> variable returns a datastore - object that can be queried using the standard datastore operators - such as <filename>getVar(, False)</filename>. - The datastore object is useful, for example, to find the original - <filename>DISPLAY</filename> variable. - Here is an example: - <literallayout class='monospaced'> - origenv = d.getVar("BB_ORIGENV", False) - bar = origenv.getVar("BAR", False) - </literallayout> - The previous example returns <filename>BAR</filename> from the original - execution environment. - </para> - </section> - </section> - - <section id='variable-flags'> - <title>Variable Flags</title> - - <para> - Variable flags (varflags) help control a task's functionality - and dependencies. - BitBake reads and writes varflags to the datastore using the following - command forms: - <literallayout class='monospaced'> - <replaceable>variable</replaceable> = d.getVarFlags("<replaceable>variable</replaceable>") - self.d.setVarFlags("FOO", {"func": True}) - </literallayout> - </para> - - <para> - When working with varflags, the same syntax, with the exception of - overrides, applies. - In other words, you can set, append, and prepend varflags just like - variables. - See the - "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>" - section for details. - </para> - - <para> - BitBake has a defined set of varflags available for recipes and - classes. - Tasks support a number of these flags which control various - functionality of the task: - <itemizedlist> - <listitem><para><emphasis><filename>[cleandirs]</filename>:</emphasis> - Empty directories that should be created before the - task runs. - Directories that already exist are removed and recreated - to empty them. - </para></listitem> - <listitem><para><emphasis><filename>[depends]</filename>:</emphasis> - Controls inter-task dependencies. - See the - <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> - variable and the - "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" - section for more information. - </para></listitem> - <listitem><para><emphasis><filename>[deptask]</filename>:</emphasis> - Controls task build-time dependencies. - See the - <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> - variable and the - "<link linkend='build-dependencies'>Build Dependencies</link>" - section for more information. - </para></listitem> - <listitem><para><emphasis><filename>[dirs]</filename>:</emphasis> - Directories that should be created before the task runs. - Directories that already exist are left as is. - The last directory listed is used as the - current working directory for the task. - </para></listitem> - <listitem><para><emphasis><filename>[lockfiles]</filename>:</emphasis> - Specifies one or more lockfiles to lock while the task - executes. - Only one task may hold a lockfile, and any task that - attempts to lock an already locked file will block until - the lock is released. - You can use this variable flag to accomplish mutual - exclusion. - </para></listitem> - <listitem><para><emphasis><filename>[noexec]</filename>:</emphasis> - When set to "1", marks the task as being empty, with - no execution required. - You can use the <filename>[noexec]</filename> flag to set up - tasks as dependency placeholders, or to disable tasks defined - elsewhere that are not needed in a particular recipe. - </para></listitem> - <listitem><para><emphasis><filename>[nostamp]</filename>:</emphasis> - When set to "1", tells BitBake to not generate a stamp - file for a task, which implies the task should always - be executed. - <note><title>Caution</title> - Any task that depends (possibly indirectly) on a - <filename>[nostamp]</filename> task will always be - executed as well. - This can cause unnecessary rebuilding if you are - not careful. - </note> - </para></listitem> - <listitem><para><emphasis><filename>[number_threads]</filename>:</emphasis> - Limits tasks to a specific number of simultaneous threads - during execution. - This varflag is useful when your build host has a large number - of cores but certain tasks need to be rate-limited due to various - kinds of resource constraints (e.g. to avoid network throttling). - <filename>number_threads</filename> works similarly to the - <link linkend='var-bb-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> - variable but is task-specific.</para> - - <para>Set the value globally. - For example, the following makes sure the - <filename>do_fetch</filename> task uses no more than two - simultaneous execution threads: - <literallayout class='monospaced'> - do_fetch[number_threads] = "2" - </literallayout> - <note><title>Warnings</title> - <itemizedlist> - <listitem><para> - Setting the varflag in individual recipes rather - than globally can result in unpredictable behavior. - </para></listitem> - <listitem><para> - Setting the varflag to a value greater than the - value used in the <filename>BB_NUMBER_THREADS</filename> - variable causes <filename>number_threads</filename> - to have no effect. - </para></listitem> - </itemizedlist> - </note> - </para></listitem> - <listitem><para><emphasis><filename>[postfuncs]</filename>:</emphasis> - List of functions to call after the completion of the task. - </para></listitem> - <listitem><para><emphasis><filename>[prefuncs]</filename>:</emphasis> - List of functions to call before the task executes. - </para></listitem> - <listitem><para><emphasis><filename>[rdepends]</filename>:</emphasis> - Controls inter-task runtime dependencies. - See the - <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> - variable, the - <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> - variable, and the - "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" - section for more information. - </para></listitem> - <listitem><para><emphasis><filename>[rdeptask]</filename>:</emphasis> - Controls task runtime dependencies. - See the - <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> - variable, the - <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> - variable, and the - "<link linkend='runtime-dependencies'>Runtime Dependencies</link>" - section for more information. - </para></listitem> - <listitem><para><emphasis><filename>[recideptask]</filename>:</emphasis> - When set in conjunction with - <filename>recrdeptask</filename>, specifies a task that - should be inspected for additional dependencies. - </para></listitem> - <listitem><para><emphasis><filename>[recrdeptask]</filename>:</emphasis> - Controls task recursive runtime dependencies. - See the - <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> - variable, the - <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> - variable, and the - "<link linkend='recursive-dependencies'>Recursive Dependencies</link>" - section for more information. - </para></listitem> - <listitem><para><emphasis><filename>[stamp-extra-info]</filename>:</emphasis> - Extra stamp information to append to the task's stamp. - As an example, OpenEmbedded uses this flag to allow - machine-specific tasks. - </para></listitem> - <listitem><para><emphasis><filename>[umask]</filename>:</emphasis> - The umask to run the task under. - </para></listitem> - </itemizedlist> - </para> - - <para> - Several varflags are useful for controlling how signatures are - calculated for variables. - For more information on this process, see the - "<link linkend='checksums'>Checksums (Signatures)</link>" - section. - <itemizedlist> - <listitem><para><emphasis><filename>[vardeps]</filename>:</emphasis> - Specifies a space-separated list of additional - variables to add to a variable's dependencies - for the purposes of calculating its signature. - Adding variables to this list is useful, for example, when - a function refers to a variable in a manner that - does not allow BitBake to automatically determine - that the variable is referred to. - </para></listitem> - <listitem><para><emphasis><filename>[vardepsexclude]</filename>:</emphasis> - Specifies a space-separated list of variables - that should be excluded from a variable's dependencies - for the purposes of calculating its signature. - </para></listitem> - <listitem><para><emphasis><filename>[vardepvalue]</filename>:</emphasis> - If set, instructs BitBake to ignore the actual - value of the variable and instead use the specified - value when calculating the variable's signature. - </para></listitem> - <listitem><para><emphasis><filename>[vardepvalueexclude]</filename>:</emphasis> - Specifies a pipe-separated list of strings to exclude - from the variable's value when calculating the - variable's signature. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='events'> - <title>Events</title> - - <para> - BitBake allows installation of event handlers within recipe - and class files. - Events are triggered at certain points during operation, such - as the beginning of operation against a given recipe - (i.e. <filename>*.bb</filename>), the start of a given task, - a task failure, a task success, and so forth. - The intent is to make it easy to do things like email - notification on build failures. - </para> - - <para> - Following is an example event handler that prints the name - of the event and the content of the - <filename>FILE</filename> variable: - <literallayout class='monospaced'> - addhandler myclass_eventhandler - python myclass_eventhandler() { - from bb.event import getName - print("The name of the Event is %s" % getName(e)) - print("The file we run for is %s" % d.getVar('FILE')) - } - myclass_eventhandler[eventmask] = "bb.event.BuildStarted bb.event.BuildCompleted" - </literallayout> - In the previous example, an eventmask has been set so that - the handler only sees the "BuildStarted" and "BuildCompleted" - events. - This event handler gets called every time an event matching - the eventmask is triggered. - A global variable "e" is defined, which represents the current - event. - With the <filename>getName(e)</filename> method, you can get - the name of the triggered event. - The global datastore is available as "d". - In legacy code, you might see "e.data" used to get the datastore. - However, realize that "e.data" is deprecated and you should use - "d" going forward. - </para> - - <para> - The context of the datastore is appropriate to the event - in question. - For example, "BuildStarted" and "BuildCompleted" events run - before any tasks are executed so would be in the global - configuration datastore namespace. - No recipe-specific metadata exists in that namespace. - The "BuildStarted" and "BuildCompleted" events also run in - the main cooker/server process rather than any worker context. - Thus, any changes made to the datastore would be seen by other - cooker/server events within the current build but not seen - outside of that build or in any worker context. - Task events run in the actual tasks in question consequently - have recipe-specific and task-specific contents. - These events run in the worker context and are discarded at - the end of task execution. - </para> - - <para> - During a standard build, the following common events might - occur. - The following events are the most common kinds of events that - most metadata might have an interest in viewing: - <itemizedlist> - <listitem><para> - <filename>bb.event.ConfigParsed()</filename>: - Fired when the base configuration; which consists of - <filename>bitbake.conf</filename>, - <filename>base.bbclass</filename> and any global - <filename>INHERIT</filename> statements; has been parsed. - You can see multiple such events when each of the - workers parse the base configuration or if the server - changes configuration and reparses. - Any given datastore only has one such event executed - against it, however. - If - <link linkende='var-bb-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link> - is set in the datastore by the event handler, the - configuration is reparsed and a new event triggered, - allowing the metadata to update configuration. - </para></listitem> - <listitem><para> - <filename>bb.event.HeartbeatEvent()</filename>: - Fires at regular time intervals of one second. - You can configure the interval time using the - <filename>BB_HEARTBEAT_EVENT</filename> variable. - The event's "time" attribute is the - <filename>time.time()</filename> value when the - event is triggered. - This event is useful for activities such as - system state monitoring. - </para></listitem> - <listitem><para> - <filename>bb.event.ParseStarted()</filename>: - Fired when BitBake is about to start parsing recipes. - This event's "total" attribute represents the number of - recipes BitBake plans to parse. - </para></listitem> - <listitem><para> - <filename>bb.event.ParseProgress()</filename>: - Fired as parsing progresses. - This event's "current" attribute is the number of - recipes parsed as well as the "total" attribute. - </para></listitem> - <listitem><para> - <filename>bb.event.ParseCompleted()</filename>: - Fired when parsing is complete. - This event's "cached", "parsed", "skipped", "virtuals", - "masked", and "errors" attributes provide statistics - for the parsing results. - </para></listitem> - <listitem><para> - <filename>bb.event.BuildStarted()</filename>: - Fired when a new build starts. - BitBake fires multiple "BuildStarted" events (one per configuration) - when multiple configuration (multiconfig) is enabled. - </para></listitem> - <listitem><para> - <filename>bb.build.TaskStarted()</filename>: - Fired when a task starts. - This event's "taskfile" attribute points to the recipe - from which the task originates. - The "taskname" attribute, which is the task's name, - includes the <filename>do_</filename> prefix, and the - "logfile" attribute point to where the task's output is - stored. - Finally, the "time" attribute is the task's execution start - time. - </para></listitem> - <listitem><para> - <filename>bb.build.TaskInvalid()</filename>: - Fired if BitBake tries to execute a task that does not exist. - </para></listitem> - <listitem><para> - <filename>bb.build.TaskFailedSilent()</filename>: - Fired for setscene tasks that fail and should not be - presented to the user verbosely. - </para></listitem> - <listitem><para> - <filename>bb.build.TaskFailed()</filename>: - Fired for normal tasks that fail. - </para></listitem> - <listitem><para> - <filename>bb.build.TaskSucceeded()</filename>: - Fired when a task successfully completes. - </para></listitem> - <listitem><para> - <filename>bb.event.BuildCompleted()</filename>: - Fired when a build finishes. - </para></listitem> - <listitem><para> - <filename>bb.cooker.CookerExit()</filename>: - Fired when the BitBake server/cooker shuts down. - This event is usually only seen by the UIs as a - sign they should also shutdown. - </para></listitem> - </itemizedlist> - </para> - - <para> - This next list of example events occur based on specific - requests to the server. - These events are often used to communicate larger pieces of - information from the BitBake server to other parts of - BitBake such as user interfaces: - <itemizedlist> - <listitem><para> - <filename>bb.event.TreeDataPreparationStarted()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.TreeDataPreparationProgress()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.TreeDataPreparationCompleted()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.DepTreeGenerated()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.CoreBaseFilesFound()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.ConfigFilePathFound()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.FilesMatchingFound()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.ConfigFilesFound()</filename> - </para></listitem> - <listitem><para> - <filename>bb.event.TargetsTreeGenerated()</filename> - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='variants-class-extension-mechanism'> - <title>Variants - Class Extension Mechanism</title> - - <para> - BitBake supports two features that facilitate creating - from a single recipe file multiple incarnations of that - recipe file where all incarnations are buildable. - These features are enabled through the - <link linkend='var-bb-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> - and - <link linkend='var-bb-BBVERSIONS'><filename>BBVERSIONS</filename></link> - variables. - <note> - The mechanism for this class extension is extremely - specific to the implementation. - Usually, the recipe's - <link linkend='var-bb-PROVIDES'><filename>PROVIDES</filename></link>, - <link linkend='var-bb-PN'><filename>PN</filename></link>, and - <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> - variables would need to be modified by the extension class. - For specific examples, see the OE-Core - <filename>native</filename>, <filename>nativesdk</filename>, - and <filename>multilib</filename> classes. - </note> - <itemizedlist> - <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis> - This variable is a space separated list of classes used to "extend" the - recipe for each variant. - Here is an example that results in a second incarnation of the current - recipe being available. - This second incarnation will have the "native" class inherited. - <literallayout class='monospaced'> - BBCLASSEXTEND = "native" - </literallayout></para></listitem> - <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis> - This variable allows a single recipe to build multiple versions of a - project from a single recipe file. - You can also specify conditional metadata - (using the - <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> - mechanism) for a single version, or an optionally named range of versions. - Here is an example: - <literallayout class='monospaced'> - BBVERSIONS = "1.0 2.0 git" - SRC_URI_git = "git://someurl/somepath.git" - - BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+" - SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1" - </literallayout> - The name of the range defaults to the original version of the - recipe. - For example, in OpenEmbedded, the recipe file - <filename>foo_1.0.0+.bb</filename> creates a default name range - of <filename>1.0.0+</filename>. - This is useful because the range name is not only placed - into overrides, but it is also made available for the metadata to use - in the variable that defines the base recipe versions for use in - <filename>file://</filename> search paths - (<link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link>). - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='dependencies'> - <title>Dependencies</title> - - <para> - To allow for efficient parallel processing, BitBake handles - dependencies at the task level. - Dependencies can exist both between tasks within a single recipe - and between tasks in different recipes. - Following are examples of each: - <itemizedlist> - <listitem><para>For tasks within a single recipe, a - recipe's <filename>do_configure</filename> - task might need to complete before its - <filename>do_compile</filename> task can run. - </para></listitem> - <listitem><para>For tasks in different recipes, one - recipe's <filename>do_configure</filename> - task might require another recipe's - <filename>do_populate_sysroot</filename> - task to finish first such that the libraries and headers - provided by the other recipe are available. - </para></listitem> - </itemizedlist> - </para> - - <para> - This section describes several ways to declare dependencies. - Remember, even though dependencies are declared in different ways, they - are all simply dependencies between tasks. - </para> - - <section id='dependencies-internal-to-the-bb-file'> - <title>Dependencies Internal to the <filename>.bb</filename> File</title> - - <para> - BitBake uses the <filename>addtask</filename> directive - to manage dependencies that are internal to a given recipe - file. - You can use the <filename>addtask</filename> directive to - indicate when a task is dependent on other tasks or when - other tasks depend on that recipe. - Here is an example: - <literallayout class='monospaced'> - addtask printdate after do_fetch before do_build - </literallayout> - In this example, the <filename>do_printdate</filename> - task depends on the completion of the - <filename>do_fetch</filename> task, and the - <filename>do_build</filename> task depends on the - completion of the <filename>do_printdate</filename> - task. - <note><para> - For a task to run, it must be a direct or indirect - dependency of some other task that is scheduled to - run.</para> - - <para>For illustration, here are some examples: - <itemizedlist> - <listitem><para> - The directive - <filename>addtask mytask before do_configure</filename> - causes <filename>do_mytask</filename> to run before - <filename>do_configure</filename> runs. - Be aware that <filename>do_mytask</filename> still only - runs if its <link linkend='checksums'>input checksum</link> - has changed since the last time it was run. - Changes to the input checksum of - <filename>do_mytask</filename> also indirectly cause - <filename>do_configure</filename> to run. - </para></listitem> - <listitem><para> - The directive - <filename>addtask mytask after do_configure</filename> - by itself never causes <filename>do_mytask</filename> - to run. - <filename>do_mytask</filename> can still be run manually - as follows: - <literallayout class='monospaced'> - $ bitbake <replaceable>recipe</replaceable> -c mytask - </literallayout> - Declaring <filename>do_mytask</filename> as a dependency - of some other task that is scheduled to run also causes - it to run. - Regardless, the task runs after - <filename>do_configure</filename>. - </para></listitem> - </itemizedlist></para> - </note> - </para> - </section> - - <section id='build-dependencies'> - <title>Build Dependencies</title> - - <para> - BitBake uses the - <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> - variable to manage build time dependencies. - The <filename>[deptask]</filename> varflag for tasks - signifies the task of each - item listed in <filename>DEPENDS</filename> that must - complete before that task can be executed. - Here is an example: - <literallayout class='monospaced'> - do_configure[deptask] = "do_populate_sysroot" - </literallayout> - In this example, the <filename>do_populate_sysroot</filename> - task of each item in <filename>DEPENDS</filename> must complete before - <filename>do_configure</filename> can execute. - </para> - </section> - - <section id='runtime-dependencies'> - <title>Runtime Dependencies</title> - - <para> - BitBake uses the - <link linkend='var-bb-PACKAGES'><filename>PACKAGES</filename></link>, - <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>, and - <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> - variables to manage runtime dependencies. - </para> - - <para> - The <filename>PACKAGES</filename> variable lists runtime - packages. - Each of those packages can have <filename>RDEPENDS</filename> and - <filename>RRECOMMENDS</filename> runtime dependencies. - The <filename>[rdeptask]</filename> flag for tasks is used to - signify the task of each - item runtime dependency which must have completed before that - task can be executed. - <literallayout class='monospaced'> - do_package_qa[rdeptask] = "do_packagedata" - </literallayout> - In the previous example, the <filename>do_packagedata</filename> - task of each item in <filename>RDEPENDS</filename> must have - completed before <filename>do_package_qa</filename> can execute. - Although <filename>RDEPENDS</filename> contains entries from the - runtime dependency namespace, BitBake knows how to map them back - to the build-time dependency namespace, in which the tasks are defined. - </para> - </section> - - <section id='recursive-dependencies'> - <title>Recursive Dependencies</title> - - <para> - BitBake uses the <filename>[recrdeptask]</filename> flag to manage - recursive task dependencies. - BitBake looks through the build-time and runtime - dependencies of the current recipe, looks through - the task's inter-task - dependencies, and then adds dependencies for the - listed task. - Once BitBake has accomplished this, it recursively works through - the dependencies of those tasks. - Iterative passes continue until all dependencies are discovered - and added. - </para> - - <para> - The <filename>[recrdeptask]</filename> flag is most commonly - used in high-level - recipes that need to wait for some task to finish "globally". - For example, <filename>image.bbclass</filename> has the following: - <literallayout class='monospaced'> - do_rootfs[recrdeptask] += "do_packagedata" - </literallayout> - This statement says that the <filename>do_packagedata</filename> - task of the current recipe and all recipes reachable - (by way of dependencies) from the - image recipe must run before the <filename>do_rootfs</filename> - task can run. - </para> - - <para> - BitBake allows a task to recursively depend on itself by - referencing itself in the task list: - <literallayout class='monospaced'> - do_a[recrdeptask] = "do_a do_b" - </literallayout> - In the same way as before, this means that the <filename>do_a</filename> - and <filename>do_b</filename> tasks of the current recipe and all - recipes reachable (by way of dependencies) from the recipe - must run before the <filename>do_a</filename> task can run. In this - case BitBake will ignore the current recipe's <filename>do_a</filename> - task circular dependency on itself. - </para> - </section> - - <section id='inter-task-dependencies'> - <title>Inter-Task Dependencies</title> - - <para> - BitBake uses the <filename>[depends]</filename> - flag in a more generic form - to manage inter-task dependencies. - This more generic form allows for inter-dependency - checks for specific tasks rather than checks for - the data in <filename>DEPENDS</filename>. - Here is an example: - <literallayout class='monospaced'> - do_patch[depends] = "quilt-native:do_populate_sysroot" - </literallayout> - In this example, the <filename>do_populate_sysroot</filename> - task of the target <filename>quilt-native</filename> - must have completed before the - <filename>do_patch</filename> task can execute. - </para> - - <para> - The <filename>[rdepends]</filename> flag works in a similar - way but takes targets - in the runtime namespace instead of the build-time dependency - namespace. - </para> - </section> - </section> - - <section id='functions-you-can-call-from-within-python'> - <title>Functions You Can Call From Within Python</title> - - <para> - BitBake provides many functions you can call from - within Python functions. - This section lists the most commonly used functions, - and mentions where to find others. - </para> - - <section id='functions-for-accessing-datastore-variables'> - <title>Functions for Accessing Datastore Variables</title> - - <para> - It is often necessary to access variables in the - BitBake datastore using Python functions. - The BitBake datastore has an API that allows you this - access. - Here is a list of available operations: - </para> - - <para> - <informaltable frame='none'> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth='1*'/> - <colspec colname='c2' colwidth='1*'/> - <thead> - <row> - <entry align="left"><emphasis>Operation</emphasis></entry> - <entry align="left"><emphasis>Description</emphasis></entry> - </row> - </thead> - <tbody> - <row> - <entry align="left"><filename>d.getVar("X", expand)</filename></entry> - <entry align="left">Returns the value of variable "X". - Using "expand=True" expands the value. - Returns "None" if the variable "X" does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.setVar("X", "value")</filename></entry> - <entry align="left">Sets the variable "X" to "value".</entry> - </row> - <row> - <entry align="left"><filename>d.appendVar("X", "value")</filename></entry> - <entry align="left">Adds "value" to the end of the variable "X". - Acts like <filename>d.setVar("X", "value")</filename> - if the variable "X" does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.prependVar("X", "value")</filename></entry> - <entry align="left">Adds "value" to the start of the variable "X". - Acts like <filename>d.setVar("X", "value")</filename> - if the variable "X" does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.delVar("X")</filename></entry> - <entry align="left">Deletes the variable "X" from the datastore. - Does nothing if the variable "X" does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry> - <entry align="left">Renames the variable "X" to "Y". - Does nothing if the variable "X" does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.getVarFlag("X", flag, expand)</filename></entry> - <entry align="left">Returns the value of variable "X". - Using "expand=True" expands the value. - Returns "None" if either the variable "X" or the named flag - does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry> - <entry align="left">Sets the named flag for variable "X" to "value".</entry> - </row> - <row> - <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry> - <entry align="left">Appends "value" to the named flag on the - variable "X". - Acts like <filename>d.setVarFlag("X", flag, "value")</filename> - if the named flag does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry> - <entry align="left">Prepends "value" to the named flag on - the variable "X". - Acts like <filename>d.setVarFlag("X", flag, "value")</filename> - if the named flag does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry> - <entry align="left">Deletes the named flag on the variable - "X" from the datastore.</entry> - </row> - <row> - <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry> - <entry align="left">Sets the flags specified in - the <filename>flagsdict()</filename> parameter. - <filename>setVarFlags</filename> does not clear previous flags. - Think of this operation as <filename>addVarFlags</filename>.</entry> - </row> - <row> - <entry align="left"><filename>d.getVarFlags("X")</filename></entry> - <entry align="left">Returns a <filename>flagsdict</filename> - of the flags for the variable "X". - Returns "None" if the variable "X" does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.delVarFlags("X")</filename></entry> - <entry align="left">Deletes all the flags for the variable "X". - Does nothing if the variable "X" does not exist.</entry> - </row> - <row> - <entry align="left"><filename>d.expand(expression)</filename></entry> - <entry align="left">Expands variable references in the specified - string expression. - References to variables that do not exist are left as is. - For example, <filename>d.expand("foo ${X}")</filename> - expands to the literal string "foo ${X}" if the - variable "X" does not exist.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </section> - - <section id='other-functions'> - <title>Other Functions</title> - - <para> - You can find many other functions that can be called - from Python by looking at the source code of the - <filename>bb</filename> module, which is in - <filename>bitbake/lib/bb</filename>. - For example, - <filename>bitbake/lib/bb/utils.py</filename> includes - the commonly used functions - <filename>bb.utils.contains()</filename> and - <filename>bb.utils.mkdirhier()</filename>, which come - with docstrings. - </para> - </section> - </section> - - <section id='task-checksums-and-setscene'> - <title>Task Checksums and Setscene</title> - - <para> - BitBake uses checksums (or signatures) along with the setscene - to determine if a task needs to be run. - This section describes the process. - To help understand how BitBake does this, the section assumes an - OpenEmbedded metadata-based example. - </para> - - <para> - These checksums are stored in - <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>. - You can examine the checksums using the following BitBake command: - <literallayout class='monospaced'> - $ bitbake-dumpsigs - </literallayout> - This command returns the signature data in a readable format - that allows you to examine the inputs used when the - OpenEmbedded build system generates signatures. - For example, using <filename>bitbake-dumpsigs</filename> - allows you to examine the <filename>do_compile</filename> - task's “sigdata” for a C application (e.g. - <filename>bash</filename>). - Running the command also reveals that the “CC” variable is part of - the inputs that are hashed. - Any changes to this variable would invalidate the stamp and - cause the <filename>do_compile</filename> task to run. - </para> - - <para> - The following list describes related variables: - <itemizedlist> - <listitem><para> - <link linkend='var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>: - Specifies the name of the function to call during - the "setscene" part of the task's execution in order - to validate the list of task hashes. - </para></listitem> - <listitem><para> - <link linkend='var-bb-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>: - Specifies a function BitBake calls that determines - whether BitBake requires a setscene dependency to - be met. - </para></listitem> - <listitem><para> - <link linkend='var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link>: - Specifies a function to call that verifies the list of - planned task execution before the main task execution - happens. - </para></listitem> - <listitem><para> - <link linkend='var-bb-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>: - Defines the mode for comparing timestamps of stamp files. - </para></listitem> - <listitem><para> - <link linkend='var-bb-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>: - Lists stamp files that are looked at when the stamp policy - is "whitelist". - </para></listitem> - <listitem><para> - <link linkend='var-bb-BB_TASKHASH'><filename>BB_TASKHASH</filename></link>: - Within an executing task, this variable holds the hash - of the task as returned by the currently enabled - signature generator. - </para></listitem> - <listitem><para> - <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>: - The base path to create stamp files. - </para></listitem> - <listitem><para> - <link linkend='var-bb-STAMPCLEAN'><filename>STAMPCLEAN</filename></link>: - Again, the base path to create stamp files but can use wildcards - for matching a range of files for clean operations. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='wildcard-support-in-variables'> - <title>Wildcard Support in Variables</title> - - <para> - Support for wildcard use in variables varies depending on the - context in which it is used. - For example, some variables and file names allow limited use of - wildcards through the "<filename>%</filename>" and - "<filename>*</filename>" characters. - Other variables or names support Python's - <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink> - syntax, - <ulink url='https://docs.python.org/3/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink> - syntax, or - <ulink url='https://docs.python.org/3/library/re.html#re'><filename>Regular Expression (re)</filename></ulink> - syntax. - </para> - - <para> - For variables that have wildcard suport, the - documentation describes which form of wildcard, its - use, and its limitations. - </para> - </section> - -</chapter> |