Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
new file mode 100644
index 0000000..0ca5321
--- /dev/null
+++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -0,0 +1,2862 @@
+<!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>