1958 lines
90 KiB
XML
1958 lines
90 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<chapter id="user-manual-metadata">
|
|
<title>Metadata</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
The BitBake task executor together with various types of configuration
|
|
files form the OpenEmbedded Core.
|
|
This section provides an overview of the task executor and the
|
|
configuration files by describing their use and interaction.
|
|
</para>
|
|
|
|
<para>
|
|
BitBake handles the parsing and execution of the data files.
|
|
The data itself is of various types:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>Recipes:</emphasis>
|
|
Details about particular pieces of software.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Class Data:</emphasis>
|
|
An abstraction of common build information
|
|
(e.g. how to build a Linux kernel).
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Configuration Data:</emphasis>
|
|
Machine-specific settings, policy decisions,
|
|
and so forth.
|
|
Configuration data acts as the glue to bind everything
|
|
together.</para></listitem>
|
|
</itemizedlist>
|
|
The remainder of this chapter provides examples of BitBake metadata.
|
|
Any syntax not supported in any of the previously listed areas
|
|
is documented as such.
|
|
</para>
|
|
</section>
|
|
|
|
<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>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='variable-expansion'>
|
|
<title>Variable Expansion</title>
|
|
|
|
<para>
|
|
BitBake supports variables referencing one another's
|
|
contents using a syntax that is similar to shell scripting.
|
|
Following is an example that results in <filename>A</filename>
|
|
containing "aval" and <filename>B</filename> containing
|
|
"preavalpost".
|
|
<literallayout class='monospaced'>
|
|
A = "aval"
|
|
B = "pre${A}post"
|
|
</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 that 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 := "${B} ${A} test ${T}"
|
|
T = "456"
|
|
B = "${T} bval"
|
|
C = "cval"
|
|
C := "${C}append"
|
|
</literallayout>
|
|
In this example, <filename>A</filename> contains
|
|
"test 123" because <filename>${B}</filename> and
|
|
<filename>${A}</filename> at the time of parsing are undefined,
|
|
which leaves "test 123".
|
|
And, 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.
|
|
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.
|
|
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.
|
|
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>
|
|
</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 are removed as well.
|
|
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"
|
|
FOO2_remove = "abc def"
|
|
</literallayout>
|
|
The variable <filename>FOO</filename> becomes
|
|
"789 123456" and <filename>FOO2</filename> becomes
|
|
"ghi abcdef".
|
|
</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. <filename>_prepend</filename>, <filename>_append</filename>,
|
|
and <filename>_remove</filename>).
|
|
</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 "abc456".
|
|
</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 becoming the current date.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='conditional-syntax-overrides'>
|
|
<title>Conditional Syntax (Overrides)</title>
|
|
|
|
<para>
|
|
BitBake uses
|
|
<link linkend='var-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.
|
|
<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></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></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='key-expansion'>
|
|
<title>Key Expansion</title>
|
|
|
|
<para>
|
|
Key expansion happens when the BitBake datastore is finalized
|
|
just before BitBake expands overrides.
|
|
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, and
|
|
before any overrides are handled, 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 "Z X".
|
|
Finally, applying the override for "foo" results in the conditional
|
|
variable <filename>A</filename> becoming "Z X" (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
|
|
<filename>_append</filename> 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-BBPATH'><filename>BBPATH</filename></link>
|
|
variable to locate needed include and class files.
|
|
The <filename>BBPATH</filename> variable is analogous to
|
|
the environment variable <filename>PATH</filename>.
|
|
</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 what classes of functionality 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 that can be used by your package.
|
|
</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>
|
|
</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 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>
|
|
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>
|
|
Similar to how BitBake uses
|
|
<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 <filename>INHERIT</filename> 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>
|
|
</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 three 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>
|
|
</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>
|
|
</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", True)
|
|
}
|
|
</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.
|
|
</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', True):
|
|
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>
|
|
|
|
<section id='tasks'>
|
|
<title>Tasks</title>
|
|
|
|
<para>
|
|
Tasks are BitBake execution units that originate as
|
|
functions and make up the steps that BitBake needs to run
|
|
for given recipe.
|
|
Tasks are only supported in recipe (<filename>.bb</filename>
|
|
or <filename>.inc</filename>) and class
|
|
(<filename>.bbclass</filename>) files.
|
|
By convention, tasks begin with the string "do_".
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example of a task that prints out the date:
|
|
<literallayout class='monospaced'>
|
|
python do_printdate () {
|
|
import time print
|
|
time.strftime('%Y%m%d', time.gmtime())
|
|
}
|
|
</literallayout>
|
|
</para>
|
|
|
|
<section id='promoting-a-function-to-a-task'>
|
|
<title>Promoting a Function to a Task</title>
|
|
|
|
<para>
|
|
Any function can be promoted to a task by applying the
|
|
<filename>addtask</filename> command.
|
|
The <filename>addtask</filename> command also describes
|
|
inter-task dependencies.
|
|
Here is the function from the previous section but with the
|
|
<filename>addtask</filename> command promoting it to a task
|
|
and defining 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>
|
|
In the example, the function is defined and then promoted
|
|
as a task.
|
|
The <filename>do_printdate</filename> task becomes a dependency of
|
|
the <filename>do_build</filename> task, which is the default
|
|
task.
|
|
And, the <filename>do_printdate</filename> task is dependent upon
|
|
the <filename>do_fetch</filename> task.
|
|
Execution of the <filename>do_build</filename> task results
|
|
in the <filename>do_printdate</filename> task running first.
|
|
</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 execution
|
|
environment of the build tasks to make
|
|
sure unwanted contamination from the build machine cannot
|
|
influence the build.
|
|
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_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
|
|
variable.
|
|
For example, assume you want to prevent the build system from
|
|
accessing your <filename>$HOME/.ccache</filename>
|
|
directory.
|
|
The following command tells BitBake to load
|
|
<filename>CCACHE_DIR</filename> from the environment 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>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='running-a-task'>
|
|
<title>Running a Task</title>
|
|
|
|
<para>
|
|
Tasks can either be a shell task or a Python task.
|
|
For shell tasks, BitBake writes a shell script to
|
|
<filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
|
|
and then executes the script.
|
|
The generated shell script contains all the exported variables,
|
|
and the shell functions with all variables expanded.
|
|
Output from the shell script goes to the file
|
|
<filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
|
|
Looking at the expanded shell functions in the run file and
|
|
the output in the log files is a useful debugging technique.
|
|
</para>
|
|
|
|
<para>
|
|
For Python tasks, BitBake executes the task internally and logs
|
|
information to the controlling terminal.
|
|
Future versions of BitBake will write the functions to files
|
|
similar to the way shell tasks are handled.
|
|
Logging will be handled in a way similar to shell tasks as well.
|
|
</para>
|
|
|
|
<para>
|
|
Once all the tasks have been completed BitBake exits.
|
|
</para>
|
|
</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'>
|
|
<variable> = d.getVarFlags("<variable>")
|
|
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.
|
|
You can discover the complete set by using <filename>grep</filename>
|
|
within a shell and search on the string "VarFlags".
|
|
</para>
|
|
|
|
<para>
|
|
Tasks support a number of these flags which control various
|
|
functionality of the task:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>dirs:</emphasis>
|
|
Directories that should be created before the task runs.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>cleandirs:</emphasis>
|
|
Empty directories that should created before the task runs.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>noexec:</emphasis>
|
|
Marks the tasks as being empty and no execution required.
|
|
These flags are used as dependency placeholders or used when
|
|
added tasks need to be subsequently disabled.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>nostamp:</emphasis>
|
|
Tells BitBake to not generate a stamp file for a task,
|
|
which implies the task is always executed.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>fakeroot:</emphasis>
|
|
Causes a task to be run in a fakeroot environment,
|
|
obtained by adding the variables in
|
|
<link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
|
|
to the environment.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>umask:</emphasis>
|
|
The umask to run the task under.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>deptask:</emphasis>
|
|
Controls task build-time dependencies.
|
|
See the
|
|
<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
|
|
variable and the
|
|
"<link linkend='build-dependencies'>Build Dependencies</link>"
|
|
section for more information.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>rdeptask:</emphasis>
|
|
Controls task runtime dependencies.
|
|
See the
|
|
<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
|
|
variable, the
|
|
<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
|
|
variable, and the
|
|
"<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
|
|
section for more information.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>recrdeptask:</emphasis>
|
|
Controls task recursive runtime dependencies.
|
|
See the
|
|
<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
|
|
variable, the
|
|
<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
|
|
variable, and the
|
|
"<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
|
|
section for more information.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>depends:</emphasis>
|
|
Controls inter-task dependencies.
|
|
See the
|
|
<link linkend='var-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>rdepends:</emphasis>
|
|
Controls inter-task runtime dependencies.
|
|
See the
|
|
<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
|
|
variable, the
|
|
<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
|
|
variable, and the
|
|
"<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
|
|
section for more information.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='parsing-and-execution'>
|
|
<title>Parsing and Execution</title>
|
|
|
|
<section id='parsing-overview'>
|
|
<title>Parsing Overview</title>
|
|
|
|
<para>
|
|
BitBake parses configuration files, classes, recipes, and append
|
|
files.
|
|
</para>
|
|
|
|
<para>
|
|
The first thing BitBake does is look for the
|
|
<filename>bitbake.conf</filename> file.
|
|
This file resides in the <filename>conf</filename>
|
|
directory, which must be listed in
|
|
<link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>bitbake.conf</filename> file lists other configuration
|
|
files to include from the <filename>conf</filename> directory below the
|
|
directories listed in <filename>BBPATH</filename>.
|
|
In general, the most important of these
|
|
configuration files from a user's perspective
|
|
is <filename>local.conf</filename>, which contains the user's
|
|
customized settings for the build environment.
|
|
</para>
|
|
|
|
<para>
|
|
Other notable configuration files are the distribution configuration
|
|
file and the machine configuration file.
|
|
These configuration files are normally identified by
|
|
variables unique to the build systems using BitBake.
|
|
For example, the Yocto Project uses the
|
|
<filename>DISTRO</filename> and <filename>MACHINE</filename>
|
|
variables, respectively.
|
|
</para>
|
|
|
|
<para>
|
|
After parsing of the configuration files, some standard classes are
|
|
included.
|
|
The <filename>base.bbclass</filename> file
|
|
is always included.
|
|
Other classes that are specified in the configuration using the
|
|
<link linkend='var-INHERIT'><filename>INHERIT</filename></link>
|
|
variable are also included.
|
|
BitBake searches for class files in a "classes" subdirectory under
|
|
the paths in <filename>BBPATH</filename> in the same way as
|
|
configuration files.
|
|
</para>
|
|
|
|
<para>
|
|
After classes are included, the variable
|
|
<filename>BBFILES</filename> is set, usually in
|
|
<filename>local.conf</filename>, and defines the list of
|
|
places to search for recipe and append files.
|
|
Adding extra content to <filename>BBFILES</filename> is best
|
|
achieved through the use of BitBake layers.
|
|
</para>
|
|
|
|
<para>
|
|
BitBake parses each recipe and append file located with
|
|
<filename>BBFILES</filename> and stores the values of various
|
|
variables into the datastore.
|
|
In summary, for each recipe and append file pairing, the configuration
|
|
plus the base class of variables are set, followed by the data in the
|
|
recipe file itself, followed by any inherit commands
|
|
that the recipe file might contain.
|
|
</para>
|
|
|
|
<para>
|
|
Because parsing recipe and append files is a time consuming
|
|
process, a cache, referred to as the "setscene"
|
|
is kept to speed up subsequent parsing.
|
|
The setscene is invalid if the timestamps of a recipe changes,
|
|
any of the include files change, configuration files change,
|
|
or class files on which the recipe file depends change.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='parsing-configuration-files'>
|
|
<title>Configuration files</title>
|
|
|
|
<para>
|
|
Prior to parsing configuration files, Bitbake looks
|
|
at certain variables, including:
|
|
<itemizedlist>
|
|
<listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
|
|
<listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
|
|
<listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
|
|
<listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem>
|
|
<listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem>
|
|
<listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
The first kind of metadata in BitBake is configuration metadata.
|
|
This metadata is global, and therefore affects all packages and
|
|
tasks that are executed.
|
|
</para>
|
|
|
|
<para>
|
|
BitBake will first search the current working directory for an
|
|
optional <filename>conf/bblayers.conf</filename> configuration file.
|
|
This file is expected to contain a
|
|
<link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
|
|
variable that is a space delimited list of 'layer' directories.
|
|
For each directory in this list, a <filename>conf/layer.conf</filename>
|
|
file will be searched for and parsed with the
|
|
<link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
|
|
variable being set to the directory where the layer was found.
|
|
The idea is these files will setup
|
|
<link linkend='var-BBPATH'><filename>BBPATH</filename></link>
|
|
and other variables correctly for a given build directory automatically
|
|
for the user.
|
|
</para>
|
|
|
|
<para>
|
|
BitBake will then expect to find <filename>conf/bitbake.conf</filename>
|
|
file somewhere in the user specified <filename>BBPATH</filename>.
|
|
That configuration file generally has include directives to pull
|
|
in any other metadata (generally files specific to architecture,
|
|
machine, local and so on).
|
|
</para>
|
|
|
|
<para>
|
|
Only variable definitions and include directives are allowed
|
|
in <filename>.conf</filename> files.
|
|
The following variables include:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-MULTI_PROVIDER_WHITELIST'><filename>MULTI_PROVIDER_WHITELIST</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>BBPKGS</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BB_DEFAULT_TASK'><filename>BB_DEFAULT_TASK</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BB_VERBOSE_LOGS'><filename>BB_VERBOSE_LOGS</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BB_NICE_LEVEL'><filename>BB_NICE_LEVEL</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BUILDNAME'><filename>BUILDNAME</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BBMASK'><filename>BBMASK</filename></link>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<section id='layers'>
|
|
<title>Layers</title>
|
|
|
|
<para>
|
|
Layers allow you to isolate different types of
|
|
customizations from each other.
|
|
While you might find it tempting to keep everything in one layer
|
|
when working on a single project, the more modular you organize
|
|
your metadata, the easier it is to cope with future changes.
|
|
</para>
|
|
|
|
<para>
|
|
To illustrate how you can use layers to keep things modular,
|
|
consider machine customizations.
|
|
These types of customizations typically reside in a special layer,
|
|
rather than a general layer, called a Board Specific Package (BSP) Layer.
|
|
Furthermore, the machine customizations should be isolated from
|
|
recipes and metadata that support a new GUI environment, for
|
|
example.
|
|
This situation gives you a couple of layers: one for the machine
|
|
configurations and one for the GUI environment.
|
|
It is important to understand, however, that the BSP layer can still
|
|
make machine-specific additions to recipes within
|
|
the GUI environment layer without polluting the GUI layer itself
|
|
with those machine-specific changes.
|
|
You can accomplish this through a recipe that is a BitBake append
|
|
(<filename>.bbappend</filename>) file.
|
|
</para>
|
|
|
|
<para>
|
|
There are certain variables specific to layers:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='schedulers'>
|
|
<title>Schedulers</title>
|
|
|
|
<para>
|
|
Variables specific to scheduling functionality exist:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='metadata-classes'>
|
|
<title>Classes</title>
|
|
|
|
<para>
|
|
BitBake's rudimentary inheritance mechanism is accomplished using
|
|
classes.
|
|
As briefly mentioned in the metadata introduction, BitBake
|
|
parses a class when an inherit directive is encountered, and it
|
|
is located in the <filename>classes</filename> directory
|
|
relative to the directories in
|
|
<link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='recipe-bb-files'>
|
|
<title>Recipe (<filename>.bb</filename>) Files</title>
|
|
|
|
<para>
|
|
Recipe files, which are files that have the
|
|
<filename>.bb</filename> file extension, are logical units of
|
|
tasks for execution.
|
|
Normally, that logical unit is a package that needs to be
|
|
built.
|
|
</para>
|
|
|
|
<para>
|
|
BitBake obeys all inter-recipe dependencies.
|
|
</para>
|
|
|
|
<para>
|
|
Recipe files must reside in locations found in the
|
|
<link linkend='var-BBFILES'><filename>BBFILES</filename></link>
|
|
variable.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='append-bbappend-files'>
|
|
<title>Append (<filename>.bbappend</filename>) Files</title>
|
|
|
|
<para>
|
|
Append files, which are files that have the
|
|
<filename>.bbappend</filename> file extension, add or
|
|
extend build information to an existing
|
|
<link linkend='recipe-bb-files'>recipe file</link>.
|
|
</para>
|
|
|
|
<para>
|
|
BitBake expects every append file to have a corresponding recipe file.
|
|
Furthermore, the append file and corresponding recipe file
|
|
must use the same root filename.
|
|
The filenames can differ only in the file type suffix used
|
|
(e.g. <filename>formfactor_0.0.bb</filename> and
|
|
<filename>formfactor_0.0.bbappend</filename>).
|
|
</para>
|
|
|
|
<para>
|
|
Information in append files overrides the information in the
|
|
similarly-named recipe file.
|
|
</para>
|
|
</section>
|
|
</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
|
|
<filename>.bb</filename>, the start of a given task,
|
|
task failure, task success, and so forth.
|
|
The intent is to make it easy to do things like email
|
|
notification on build failure.
|
|
</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
|
|
from bb import data
|
|
print("The name of the Event is %s" % getName(e))
|
|
print("The file we run for is %s" % data.getVar('FILE', e.data, True))
|
|
}
|
|
</literallayout>
|
|
This event handler gets called every time an event is
|
|
triggered.
|
|
A global variable "<filename>e</filename>" is defined and
|
|
"<filename>e.data</filename>" contains an instance of
|
|
"<filename>bb.data</filename>".
|
|
With the <filename>getName(e)</filename> method, one can get
|
|
the name of the triggered event.
|
|
</para>
|
|
|
|
<para>
|
|
During all builds, the following common events occur:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<filename>bb.event.ConfigParsed()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.event.ParseStarted()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.event.ParseProgress()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.event.ParseCompleted()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.event.BuildStarted()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.build.TaskStarted()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.build.TaskInvalid()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.build.TaskFailedSilent()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.build.TaskFailed()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.build.TaskSucceeded()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.event.BuildCompleted()</filename>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<filename>bb.cooker.CookerExit()</filename>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
Here is a list of other events that occur based on specific requests
|
|
to the server:
|
|
<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-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
|
|
and
|
|
<link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link>
|
|
variables:
|
|
<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-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-FILESPATH'><filename>FILESPATH</filename></link>).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='dependencies'>
|
|
<title>Dependencies</title>
|
|
|
|
<para>
|
|
To allow for efficient operation given multiple processes
|
|
executing in parallel, BitBake handles dependencies at
|
|
the task level.
|
|
BitBake supports a robust method to handle these dependencies.
|
|
</para>
|
|
|
|
<para>
|
|
This section describes several types of dependency mechanisms.
|
|
</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>printdate</filename> task is
|
|
depends on the completion of the <filename>do_fetch</filename>
|
|
task.
|
|
And, the <filename>do_build</filename> depends on the completion
|
|
of the <filename>printdate</filename> task.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='build-dependencies'>
|
|
<title>Build Dependencies</title>
|
|
|
|
<para>
|
|
BitBake uses the
|
|
<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
|
|
variable to manage build time dependencies.
|
|
The "deptask" 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_staging"
|
|
</literallayout>
|
|
In this example, the <filename>do_populate_staging</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-PACKAGES'><filename>PACKAGES</filename></link>,
|
|
<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, and
|
|
<link linkend='var-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 "rdeptask" 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_write[rdeptask] = "do_package"
|
|
</literallayout>
|
|
In the previous example, the <filename>do_package</filename>
|
|
task of each item in <filename>RDEPENDS</filename> must have
|
|
completed before <filename>do_package_write</filename> can execute.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='recursive-dependencies'>
|
|
<title>Recursive Dependencies</title>
|
|
|
|
<para>
|
|
BitBake uses the "recrdeptask" 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>
|
|
You might want to not only have BitBake look for
|
|
dependencies of those tasks, but also have BitBake look
|
|
for build-time and runtime dependencies of the dependent
|
|
tasks as well.
|
|
If that is the case, you need to reference the task name
|
|
itself in the task list:
|
|
<literallayout class='monospaced'>
|
|
do_a[recrdeptask] = "do_a do_b"
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='inter-task-dependencies'>
|
|
<title>Inter-Task Dependencies</title>
|
|
|
|
<para>
|
|
BitBake uses the "depends" 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_staging"
|
|
</literallayout>
|
|
In this example, the <filename>do_populate_staging</filename>
|
|
task of the target <filename>quilt-native</filename>
|
|
must have completed before the
|
|
<filename>do_patch</filename> task can execute.
|
|
</para>
|
|
|
|
<para>
|
|
The "rdepends" 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='accessing-datastore-variables-using-python'>
|
|
<title>Accessing Datastore Variables Using Python</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=False)</filename></entry>
|
|
<entry align="left">Returns the value of variable "X".
|
|
Using "expand=True" expands the value.</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".</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".</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.delVar("X")</filename></entry>
|
|
<entry align="left">Deletes the variable "X" from the datastore.</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
|
|
<entry align="left">Renames the variable "X" to "Y".</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
|
|
<entry align="left">Gets "flag" from the variable "X".
|
|
Using "expand=True" expands the flag.</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry>
|
|
<entry align="left">Sets "flag" for variable "X" to "value".
|
|
<filename>setVarFlags</filename> does not clear previous flags.
|
|
Think of this operation as <filename>addVarFlags</filename>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry>
|
|
<entry align="left">Need description.</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry>
|
|
<entry align="left">Need description.</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
|
|
<entry align="left">Need description.</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
|
|
<entry align="left">Sets the flags specified in
|
|
the <filename>dict()</filename> parameter.</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.getVarFlags("X")</filename></entry>
|
|
<entry align="left">Returns a <filename>dict</filename> of the flags for
|
|
the variable "X".</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left"><filename>d.delVarFlags</filename></entry>
|
|
<entry align="left">Deletes all the flags for a variable.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</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>
|
|
This list is a place holder of content existed from previous work
|
|
on the manual.
|
|
Some or all of it probably needs integrated into the subsections
|
|
that make up this section.
|
|
For now, I have just provided a short glossary-like description
|
|
for each variable.
|
|
Ultimately, this list goes away.
|
|
<itemizedlist>
|
|
<listitem><para><filename>STAMP</filename>:
|
|
The base path to create stamp files.</para></listitem>
|
|
<listitem><para><filename>STAMPCLEAN</filename>
|
|
Again, the base path to create stamp files but can use wildcards
|
|
for matching a range of files for clean operations.
|
|
</para></listitem>
|
|
<listitem><para><filename>BB_STAMP_WHITELIST</filename>
|
|
Lists stamp files that are looked at when the stamp policy
|
|
is "whitelist".
|
|
</para></listitem>
|
|
<listitem><para><filename>BB_STAMP_POLICY</filename>
|
|
Defines the mode for comparing timestamps of stamp files.
|
|
</para></listitem>
|
|
<listitem><para><filename>BB_HASHCHECK_FUNCTION</filename>
|
|
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><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
|
|
Specifies a function to call that verifies the list of
|
|
planned task execution before the main task execution
|
|
happens.
|
|
</para></listitem>
|
|
<listitem><para><filename>BB_SETSCENE_DEPVALID</filename>
|
|
Specifies a function BitBake calls that determines
|
|
whether BitBake requires a setscene dependency to
|
|
be met.
|
|
</para></listitem>
|
|
<listitem><para><filename>BB_TASKHASH</filename>
|
|
Within an executing task, this variable holds the hash
|
|
of the task as returned by the currently enabled
|
|
signature generator.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<section id='setscene'>
|
|
<title>Setscene</title>
|
|
|
|
<para>
|
|
This section needs to get the concept of the setscene across.
|
|
The reader needs to know what it is and what it is used for during
|
|
the build process.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='checksums'>
|
|
<title>Checksums (Signatures)</title>
|
|
|
|
<para>
|
|
A checksum is a unique signature of a task's inputs.
|
|
The setscene code uses a checksum to determine if a task needs
|
|
to be run.
|
|
Because it is a change in a task's inputs that triggers running
|
|
the task, the process needs to detect all the inputs to a given task.
|
|
For shell tasks, this turns out to be fairly easy because
|
|
BitBake generates a "run" shell script for each task and
|
|
it is possible to create a checksum that gives you a good idea of when
|
|
the task's data changes.
|
|
</para>
|
|
|
|
<para>
|
|
To complicate the problem, some things should not be included in
|
|
the checksum.
|
|
First, there is the actual specific build path of a given task -
|
|
the working directory.
|
|
It does not matter if the working directory changes because it should not
|
|
affect the output for target packages.
|
|
The simplistic approach for excluding the working directory is to set
|
|
it to some fixed value and create the checksum for the "run" script.
|
|
</para>
|
|
|
|
<para>
|
|
Another problem results from the "run" scripts containing functions that
|
|
might or might not get called.
|
|
The incremental build solution contains code that figures out dependencies
|
|
between shell functions.
|
|
This code is used to prune the "run" scripts down to the minimum set,
|
|
thereby alleviating this problem and making the "run" scripts much more
|
|
readable as a bonus.
|
|
</para>
|
|
|
|
<para>
|
|
So far we have solutions for shell scripts.
|
|
What about Python tasks?
|
|
The same approach applies even though these tasks are more difficult.
|
|
The process needs to figure out what variables a Python function accesses
|
|
and what functions it calls.
|
|
Again, the incremental build solution contains code that first figures out
|
|
the variable and function dependencies, and then creates a checksum for the data
|
|
used as the input to the task.
|
|
</para>
|
|
|
|
<para>
|
|
Like the working directory case, situations exist where dependencies
|
|
should be ignored.
|
|
For these cases, you can instruct the build process to ignore a dependency
|
|
by using a line like the following:
|
|
<literallayout class='monospaced'>
|
|
PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
|
|
</literallayout>
|
|
This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
|
|
depend on the value of <filename>MACHINE</filename>, even if it does reference it.
|
|
</para>
|
|
|
|
<para>
|
|
Equally, there are cases where we need to add dependencies BitBake
|
|
is not able to find.
|
|
You can accomplish this by using a line like the following:
|
|
<literallayout class='monospaced'>
|
|
PACKAGE_ARCHS[vardeps] = "MACHINE"
|
|
</literallayout>
|
|
This example explicitly adds the <filename>MACHINE</filename> variable as a
|
|
dependency for <filename>PACKAGE_ARCHS</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
Consider a case with in-line Python, for example, where BitBake is not
|
|
able to figure out dependencies.
|
|
When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
|
|
produces output when it discovers something for which it cannot figure out
|
|
dependencies.
|
|
</para>
|
|
|
|
<para>
|
|
Thus far, this section has limited discussion to the direct inputs into a task.
|
|
Information based on direct inputs is referred to as the "basehash" in the
|
|
code.
|
|
However, there is still the question of a task's indirect inputs - the
|
|
things that were already built and present in the build directory.
|
|
The checksum (or signature) for a particular task needs to add the hashes
|
|
of all the tasks on which the particular task depends.
|
|
Choosing which dependencies to add is a policy decision.
|
|
However, the effect is to generate a master checksum that combines the basehash
|
|
and the hashes of the task's dependencies.
|
|
</para>
|
|
|
|
<para>
|
|
At the code level, there are a variety of ways both the basehash and the
|
|
dependent task hashes can be influenced.
|
|
Within the BitBake configuration file, we can give BitBake some extra information
|
|
to help it construct the basehash.
|
|
The following statement effectively results in a list of global variable
|
|
dependency excludes - variables never included in any checksum.
|
|
This example uses variables from OpenEmbedded to help illustrate
|
|
the concept:
|
|
<literallayout class='monospaced'>
|
|
BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
|
|
SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
|
|
USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
|
|
PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
|
|
CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
|
|
</literallayout>
|
|
The previous example excludes the work directory, which is part of
|
|
<filename>TMPDIR</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
The rules for deciding which hashes of dependent tasks to include through
|
|
dependency chains are more complex and are generally accomplished with a
|
|
Python function.
|
|
The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
|
|
of this and also illustrates how you can insert your own policy into the system
|
|
if so desired.
|
|
This file defines the two basic signature generators OpenEmbedded Core
|
|
uses: "OEBasic" and "OEBasicHash".
|
|
By default, there is a dummy "noop" signature handler enabled in BitBake.
|
|
This means that behavior is unchanged from previous versions.
|
|
<filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
|
|
through this setting in the <filename>bitbake.conf</filename> file:
|
|
<literallayout class='monospaced'>
|
|
BB_SIGNATURE_HANDLER ?= "OEBasicHash"
|
|
</literallayout>
|
|
The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
|
|
"OEBasic" version but adds the task hash to the stamp files.
|
|
This results in any metadata change that changes the task hash, automatically
|
|
causing the task to be run again.
|
|
This removes the need to bump
|
|
<link linkend='var-PR'><filename>PR</filename></link>
|
|
values, and changes to metadata automatically ripple across the build.
|
|
</para>
|
|
|
|
<para>
|
|
It is also worth noting that the end result of these signature generators is to
|
|
make some dependency and hash information available to the build.
|
|
This information includes:
|
|
<itemizedlist>
|
|
<listitem><para><filename>BB_BASEHASH_task-<taskname></filename>:
|
|
The base hashes for each task in the recipe.
|
|
</para></listitem>
|
|
<listitem><para><filename>BB_BASEHASH_<filename:taskname></filename>:
|
|
The base hashes for each dependent task.
|
|
</para></listitem>
|
|
<listitem><para><filename>BBHASHDEPS_<filename:taskname></filename>:
|
|
The task dependencies for each task.
|
|
</para></listitem>
|
|
<listitem><para><filename>BB_TASKHASH</filename>:
|
|
The hash of the currently running task.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|