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