2013-01-11 17:45:15 +00:00
|
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
2014-01-18 11:34:47 +00:00
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
|
|
|
|
<chapter id="user-manual-metadata">
|
|
|
|
<title>Metadata</title>
|
|
|
|
|
|
|
|
<section>
|
2014-01-18 14:02:18 +00:00
|
|
|
<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 BitBake task executor and the configuration files by
|
|
|
|
describing what they are used for and how they interact.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
BitBake handles the parsing and execution of the data files. The data itself is of various types:
|
2013-01-11 17:45:15 +00:00
|
|
|
<itemizedlist>
|
2014-01-18 14:02:18 +00:00
|
|
|
<listitem><para><emphasis>Recipes:</emphasis>
|
|
|
|
Provides 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>
|
|
|
|
Defines machine-specific settings, policy decisions, etc. Configuration data acts
|
|
|
|
as the glue to bind everything together.</para></listitem>
|
2013-01-11 17:45:15 +00:00
|
|
|
</itemizedlist>
|
2014-01-18 14:02:18 +00:00
|
|
|
What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported
|
2014-01-18 11:34:47 +00:00
|
|
|
in any of the aforementioned areas will be documented as such.
|
|
|
|
</para>
|
2014-01-17 16:22:42 +00:00
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='basic-syntax'>
|
|
|
|
<title>Basic Syntax</title>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='basic-variable-setting'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Basic Variable Setting</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
VARIABLE = "value"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this example, <filename>VARIABLE</filename> is <filename>value</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='variable-expansion'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Variable Expansion</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
BitBake supports variables referencing one another's
|
|
|
|
contents using a syntax which is similar to shell
|
|
|
|
scripting
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
A = "aval"
|
|
|
|
B = "pre${A}post"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
This results in <filename>A</filename> containing
|
|
|
|
<filename>aval</filename> and <filename>B</filename> containing
|
|
|
|
<filename>preavalpost</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='setting-a-default-value'>
|
|
|
|
<title>Setting a default value (?=)</title>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
A ?= "aval"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
If <filename>A</filename> is set before the above is called,
|
2014-01-18 11:34:47 +00:00
|
|
|
it will retain its previous value.
|
2014-01-18 13:20:36 +00:00
|
|
|
If <filename>A</filename> is unset prior to the above call,
|
|
|
|
<filename>A</filename> will be set to <filename>aval</filename>.
|
2014-01-18 14:02:18 +00:00
|
|
|
<note>
|
|
|
|
This assignment is immediate, so if there are multiple "?=" assignments
|
2014-01-18 11:34:47 +00:00
|
|
|
to a single variable, the first of those will be used.
|
2014-01-18 14:02:18 +00:00
|
|
|
</note>
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='setting-a-weak-default-value'>
|
|
|
|
<title>Setting a weak default value (??=)</title>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
A ??= "somevalue"
|
|
|
|
A ??= "someothervalue"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
If <filename>A</filename> is set before the above,
|
2014-01-18 11:34:47 +00:00
|
|
|
it will retain that value.
|
2014-01-18 13:20:36 +00:00
|
|
|
If <filename>A</filename> is unset prior to the above,
|
|
|
|
<filename>A</filename> will be set to <filename>someothervalue</filename>.
|
2014-01-18 14:02:18 +00:00
|
|
|
This is a lazy or weak assignment in that the assignment does not occur until the end
|
2014-01-18 11:34:47 +00:00
|
|
|
of the parsing process, so that the last, rather than the first,
|
2014-01-18 14:02:18 +00:00
|
|
|
"??=" assignment to a given variable will be used.
|
|
|
|
Any other setting of <filename>A</filename> using "=" or "?="
|
|
|
|
will, however, override the value set with "??=".
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='immediate-variable-expansion'>
|
|
|
|
<title>Immediate variable expansion (:=)</title>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
The ":=" operator results in a variable's contents being expanded immediately,
|
|
|
|
rather than when the variable is actually used:
|
|
|
|
<literallayout class='monospaced'>
|
2014-01-18 13:14:30 +00:00
|
|
|
T = "123"
|
|
|
|
A := "${B} ${A} test ${T}"
|
|
|
|
T = "456"
|
|
|
|
B = "${T} bval"
|
|
|
|
C = "cval"
|
|
|
|
C := "${C}append"
|
|
|
|
</literallayout>
|
2014-01-18 14:02:18 +00:00
|
|
|
In this example, <filename>A</filename> would contain
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>test 123</filename>, <filename>B</filename> would contain
|
|
|
|
<filename>456 bval</filename>, and <filename>C</filename>
|
|
|
|
would be <filename>cvalappend</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='appending-and-prepending'>
|
|
|
|
<title>Appending (+=) and prepending (=+)</title>
|
2014-01-17 16:22:42 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
B = "bval"
|
|
|
|
B += "additionaldata"
|
|
|
|
C = "cval"
|
|
|
|
C =+ "test"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this example, <filename>B</filename> is now
|
|
|
|
<filename>bval additionaldata</filename> and <filename>C</filename>
|
|
|
|
is <filename>test cval</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='appending-and-prepending-without-spaces'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Appending (.=) and Prepending (=.) Without Spaces</title>
|
2014-01-17 16:22:42 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
B = "bval"
|
|
|
|
B .= "additionaldata"
|
|
|
|
C = "cval"
|
|
|
|
C =. "test"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this example, <filename>B</filename> is now
|
|
|
|
<filename>bvaladditionaldata</filename> and
|
|
|
|
<filename>C</filename> is <filename>testcval</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
In contrast to the above appending and prepending operators,
|
|
|
|
no additional space will be introduced.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='appending-and-prepending-override-style-syntax'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Appending and Prepending (Override Style Syntax)</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
B = "bval"
|
|
|
|
B_append = " additional data"
|
|
|
|
C = "cval"
|
|
|
|
C_prepend = "additional data "
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
This example results in <filename>B</filename>
|
2014-01-18 14:02:18 +00:00
|
|
|
becoming <filename>bval additional data</filename> and
|
|
|
|
<filename>C</filename> becoming
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>additional data cval</filename>.
|
2014-01-18 14:02:18 +00:00
|
|
|
<note>
|
|
|
|
The spaces in <filename>_append</filename>.
|
|
|
|
Unlike the "+=" operator, additional space is not automatically added.
|
|
|
|
You must take steps to add space yourself.
|
|
|
|
</note>
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='removing-override-style-syntax'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Removing (Override Style Syntax)</title>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
FOO = "123 456 789 123456 123 456 123 456"
|
|
|
|
FOO_remove = "123"
|
|
|
|
FOO_remove = "456"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this example, <filename>FOO</filename> is now <filename>789 123456</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='variable-flags'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Variable Flags</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Variables can have associated flags which provide a way of tagging extra information onto a variable.
|
|
|
|
Several flags are used internally by BitBake but they can be used externally too if needed.
|
|
|
|
The standard operations mentioned above also work on flags.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
VARIABLE[SOMEFLAG] = "value"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this example, <filename>VARIABLE</filename> has a flag,
|
2014-01-18 14:02:18 +00:00
|
|
|
<filename>SOMEFLAG</filename> that is set to <filename>value</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='inline-python-variable-expansion'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Inline Python Variable Expansion</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
This would result in the <filename>DATE</filename>
|
2014-01-18 11:34:47 +00:00
|
|
|
variable containing today's date.
|
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-18 14:02:18 +00:00
|
|
|
</section>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<section id='conditional-syntax-overrides'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Conditional Syntax (Overrides)</title>
|
|
|
|
|
|
|
|
<section id='conditional-metadata'>
|
|
|
|
<title>Conditional Metadata</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
<filename>OVERRIDES</filename> is a “:” separated variable containing
|
|
|
|
each item for which you want to satisfy conditions.
|
|
|
|
So, if you have a variable that is conditional on “arm”, and “arm”
|
|
|
|
is in <filename>OVERRIDES</filename>, then the “arm” specific
|
2014-01-18 11:34:47 +00:00
|
|
|
version of the variable is used rather than the non-conditional
|
|
|
|
version.
|
2014-01-18 14:02:18 +00:00
|
|
|
Here is an example:
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
OVERRIDES = "architecture:os:machine"
|
|
|
|
TEST = "defaultvalue"
|
|
|
|
TEST_os = "osspecificvalue"
|
|
|
|
TEST_condnotinoverrides = "othercondvalue"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this example, <filename>TEST</filename> would be
|
|
|
|
<filename>osspecificvalue</filename>, due to the condition
|
2014-01-18 14:02:18 +00:00
|
|
|
“os” being in <filename>OVERRIDES</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-17 16:22:42 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='conditional-appending'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Conditional Appending</title>
|
2014-01-17 16:35:32 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
|
|
|
BitBake also supports appending and prepending to variables based
|
2014-01-18 14:02:18 +00:00
|
|
|
on whether something is in <filename>OVERRIDES</filename>.
|
|
|
|
Here is an example:
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
DEPENDS = "glibc ncurses"
|
|
|
|
OVERRIDES = "machine:local"
|
|
|
|
DEPENDS_append_machine = "libmad"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this example, <filename>DEPENDS</filename> is set to
|
|
|
|
"glibc ncurses libmad".
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-17 16:35:32 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='variable-interaction-worked-examples'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Variable Interaction: Worked Examples</title>
|
2014-01-17 16:35:32 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
|
|
|
Despite the documentation of the different forms of
|
|
|
|
variable definition above, it can be hard to work
|
|
|
|
out what happens when variable operators are combined.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
Following are some common scenarios where variables interact
|
|
|
|
that can confuse users.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
There is often confusion about which order overrides and the
|
|
|
|
various "append" operators take effect:
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
OVERRIDES = "foo"
|
|
|
|
A_foo_append = "X"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this case, <filename>X</filename> is unconditionally appended
|
|
|
|
to the variable <filename>A_foo</filename>.
|
|
|
|
Since foo is an override, <filename>A_foo</filename> would then replace
|
|
|
|
<filename>A</filename>.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
OVERRIDES = "foo"
|
|
|
|
A = "X"
|
|
|
|
A_append_foo = "Y"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
In this case, only when <filename>foo</filename> is in
|
|
|
|
<filename>OVERRIDES</filename>, <filename>Y</filename>
|
|
|
|
is appended to the variable <filename>A</filename>
|
|
|
|
so the value of <filename>A</filename> would
|
|
|
|
become <filename>XY</filename> (NB: no spaces are appended).
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
OVERRIDES = "foo"
|
|
|
|
A_foo_append = "X"
|
|
|
|
A_foo_append += "Y"
|
|
|
|
</literallayout>
|
2014-01-18 11:34:47 +00:00
|
|
|
This behaves as per the first case above, but the value of
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>A</filename> would be "X Y" instead of just "X".
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
A = "1"
|
|
|
|
A_append = "2"
|
|
|
|
A_append = "3"
|
|
|
|
A += "4"
|
|
|
|
A .= "5"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
Would ultimately result in <filename>A</filename> taking the value
|
2014-01-18 14:02:18 +00:00
|
|
|
"1 4523" since the "_append" operator executes at the
|
2014-01-18 11:34:47 +00:00
|
|
|
same time as the expansion of other overrides.
|
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-17 16:35:32 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='key-expansion'>
|
|
|
|
<title>Key Expansion</title>
|
2014-01-17 16:35:32 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
Key expansion happens at the data store finalization
|
2014-01-18 11:34:47 +00:00
|
|
|
time just before overrides are expanded.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
A${B} = "X"
|
|
|
|
B = "2"
|
|
|
|
A2 = "Y"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
So in this case <filename>A2</filename> would take the value of "X".
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-17 16:35:32 +00:00
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='inheritance'>
|
|
|
|
<title>Inheritance</title>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='inheritance-directive'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Inheritance Directive</title>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
This is only supported in <filename>.bb</filename> and
|
|
|
|
<filename>.bbclass</filename> files.
|
|
|
|
</note>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
2014-01-18 13:20:36 +00:00
|
|
|
The inherit directive is a means of specifying what classes
|
|
|
|
of functionality your <filename>.bb</filename> requires.
|
2014-01-18 11:34:47 +00:00
|
|
|
It is a rudimentary form of inheritance.
|
|
|
|
For example, you can easily abstract out the tasks involved in
|
|
|
|
building a package that uses autoconf and automake, and put
|
|
|
|
that into a bbclass for your packages to make use of.
|
|
|
|
A given bbclass is located by searching for classes/filename.bbclass
|
2014-01-18 13:20:36 +00:00
|
|
|
in <filename>BBPATH</filename>, where filename is what you inherited.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='inclusion-directive'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Inclusion Directive</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
This directive causes BitBake to parse whatever file you specify,
|
|
|
|
and insert it at that location, which is not unlike Make.
|
|
|
|
However, if the path specified on the include line is a
|
2014-01-18 11:34:47 +00:00
|
|
|
relative path, BitBake will locate the first one it can find
|
2014-01-18 13:20:36 +00:00
|
|
|
within <filename>BBPATH</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='requiring-inclusion'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Requiring Inclusion</title>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
In contrast to the include directive, require will raise a
|
2014-01-18 11:34:47 +00:00
|
|
|
ParseError if the file to be included cannot
|
|
|
|
be found.
|
2014-01-18 14:02:18 +00:00
|
|
|
Otherwise it will behave just like the include directive.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-17 16:22:42 +00:00
|
|
|
|
2014-01-18 14:29:16 +00:00
|
|
|
<section id='inherit-configuration-directive'>
|
|
|
|
<title><filename>INHERIT</filename> Configuration Directive</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This configuration directive causes the named class to be inherited
|
|
|
|
at this point during parsing.
|
|
|
|
This variable is only valid in configuration files.
|
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-17 16:35:32 +00:00
|
|
|
</section>
|
2014-01-17 16:22:42 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='defining-python-functions-into-the-global-python-namespace'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Defining Python Functions into the Global Python Namespace</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
2014-01-18 14:02:18 +00:00
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
This is only supported in <filename>.bb</filename>
|
|
|
|
and <filename>.bbclass</filename> files.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Python functions are in the global namespace so should use
|
|
|
|
unique names.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
def get_depends(d):
|
|
|
|
if d.getVar('SOMECONDITION', True):
|
|
|
|
return "dependencywithcond"
|
|
|
|
else:
|
|
|
|
return "dependency"
|
|
|
|
SOMECONDITION = "1"
|
|
|
|
DEPENDS = "${@get_depends(d)}"
|
|
|
|
</literallayout>
|
2014-01-18 14:02:18 +00:00
|
|
|
This would result in <filename>DEPENDS</filename>
|
|
|
|
containing <filename>dependencywithcond</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
2014-01-18 14:02:18 +00:00
|
|
|
</note>
|
2014-01-18 11:34:47 +00:00
|
|
|
</section>
|
|
|
|
|
2014-01-18 14:26:07 +00:00
|
|
|
<section id='functions'>
|
|
|
|
<title>Functions</title>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
This is only supported in <filename>.bb</filename>
|
|
|
|
and <filename>.bbclass</filename> files.
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As with most languages, functions are the building blocks
|
|
|
|
that define operations.
|
|
|
|
Bitbake supports shell and Python functions.
|
|
|
|
An example shell function definition is:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
some_function () {
|
|
|
|
echo "Hello World"
|
|
|
|
}
|
|
|
|
</literallayout>
|
|
|
|
An example Python function definition is:
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
2014-01-18 14:26:07 +00:00
|
|
|
python some_python_function () {
|
|
|
|
d.setVar("TEXT", "Hello World")
|
|
|
|
print d.getVar("TEXT", True)
|
|
|
|
}
|
2014-01-18 13:14:30 +00:00
|
|
|
</literallayout>
|
2014-01-18 14:26:07 +00:00
|
|
|
In python functions, the "bb" and "os" modules are already
|
|
|
|
imported, there is no need to import those modules.
|
|
|
|
The datastore, "d" is also a global variable and always
|
|
|
|
available to these functions automatically.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Bitbake will execute functions of this form using
|
|
|
|
the <filename>bb.build.exec_func()</filename>, which can also be
|
|
|
|
called from Python functions to execute other functions,
|
|
|
|
either shell or Python based.
|
|
|
|
Shell functions can only execute other shell functions.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There is also a second way to declare python functions with
|
|
|
|
parameters which takes the form:
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
2014-01-18 14:26:07 +00:00
|
|
|
def some_python_function(arg1, arg2):
|
|
|
|
print arg1 + " " + arg2
|
2014-01-18 13:14:30 +00:00
|
|
|
</literallayout>
|
2014-01-18 14:26:07 +00:00
|
|
|
The difference is that the second form takes parameters,
|
|
|
|
the datastore is not available automatically
|
|
|
|
and must be passed as a parameter and these functions are
|
|
|
|
not called with the <filename>exec_func()</filename> but are
|
|
|
|
executed with direct Python function calls.
|
|
|
|
The "bb" and "os" modules are still automatically available
|
|
|
|
and there is no need to import them.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2014-01-18 14:34:14 +00:00
|
|
|
<section id='tasks'>
|
2014-01-18 11:34:47 +00:00
|
|
|
<title>Tasks</title>
|
2014-01-18 14:34:14 +00:00
|
|
|
|
|
|
|
<note>
|
|
|
|
This is only supported in <filename>.bb</filename>
|
|
|
|
and <filename>.bbclass</filename> files.
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A shell or Python function executable through the
|
|
|
|
<filename>exec_func</filename> can be promoted to become a task.
|
|
|
|
Tasks are the execution unit Bitbake uses and each step that
|
|
|
|
needs to be run for a given <filename>.bb</filename> is known as
|
|
|
|
a task.
|
|
|
|
There is an <filename>addtask</filename> command to add new tasks
|
|
|
|
and promote functions which by convention must start with “do_”.
|
|
|
|
The <filename>addtask</filename> command is also used to describe
|
|
|
|
intertask dependencies.
|
2014-01-18 13:14:30 +00:00
|
|
|
<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>
|
2014-01-18 14:34:14 +00:00
|
|
|
The above example defined a Python function, then adds
|
|
|
|
it as a task which is now a dependency of
|
|
|
|
<filename>do_build</filename>, the default task and states it
|
|
|
|
has to happen after <filename>do_fetch</filename>.
|
|
|
|
If anyone executes the <filename>do_build</filename>
|
|
|
|
task, that will result in <filename>do_printdate</filename>
|
|
|
|
being run first.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2014-01-18 14:27:30 +00:00
|
|
|
<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>
|
|
|
|
|
|
|
|
<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's environment, you must take a few steps:
|
|
|
|
<orderedlist>
|
|
|
|
<listitem><para>
|
|
|
|
Tell BitBake to load what you want from the environment
|
|
|
|
into the data store.
|
|
|
|
You can do so through the
|
|
|
|
<filename>BB_ENV_EXTRAWHITE</filename> 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 data store:
|
|
|
|
<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
|
|
|
|
environment store to the task environment of
|
|
|
|
every running task.
|
|
|
|
Loading something from the environment into the data
|
|
|
|
store (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
|
|
|
|
<filename>local.conf</filename> or 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 shared state checksums.
|
|
|
|
If doing so results in unnecessary rebuilds of tasks, you can
|
|
|
|
whitelist the variable so that the shared state code
|
|
|
|
ignores the dependency when it creates checksums.
|
|
|
|
</note></para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='task-flags'>
|
|
|
|
<title>Task Flags</title>
|
2013-01-11 17:45:15 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
|
|
|
Tasks support a number of flags which control various
|
2014-01-18 14:33:33 +00:00
|
|
|
functionality of the task.
|
|
|
|
These are as follows:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para><emphasis>dirs:</emphasis>
|
|
|
|
Directories which should be created before the task runs.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para><emphasis>cleandirs:</emphasis>
|
|
|
|
Directories which should created before the task runs
|
|
|
|
but should be empty.</para></listitem>
|
|
|
|
<listitem><para><emphasis>noexec:</emphasis>
|
|
|
|
Marks the tasks as being empty and no execution required.
|
|
|
|
These are used as dependency placeholders or used when added tasks
|
|
|
|
need to be subsequently disabled.</para></listitem>
|
|
|
|
<listitem><para><emphasis>nostamp:</emphasis>
|
|
|
|
Do not generate a stamp file for a task.
|
|
|
|
This means the task is always executed.</para></listitem>
|
|
|
|
<listitem><para><emphasis>fakeroot:</emphasis>
|
|
|
|
This task needs to be run in a fakeroot environment,
|
|
|
|
obtained by adding the variables in <filename>FAKEROOTENV</filename>
|
|
|
|
to the environment.</para></listitem>
|
|
|
|
<listitem><para><emphasis>umask:</emphasis>
|
|
|
|
The umask to run the task under.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
For the 'deptask', 'rdeptask', 'depends', 'rdepends'and
|
|
|
|
'recrdeptask' flags, please see the dependencies section.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
2014-01-18 14:33:33 +00:00
|
|
|
</section>
|
2014-01-18 14:32:51 +00:00
|
|
|
|
|
|
|
<section id='parsing-and-execution'>
|
|
|
|
<title>Parsing and Execution</title>
|
|
|
|
|
2014-01-17 16:35:32 +00:00
|
|
|
<section id='parsing-overview'>
|
2014-01-18 14:32:51 +00:00
|
|
|
<title>Parsing Overview</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
BitBake parses configuration files, classes, and
|
|
|
|
<filename>.bb</filename> files.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The first thing BitBake does is look for the
|
|
|
|
<filename>bitbake.conf</filename> file.
|
|
|
|
This file resides in the within the <filename>conf/</filename>
|
|
|
|
directory.
|
|
|
|
BitBake finds it by examining its <filename>BBPATH</filename>
|
|
|
|
environment variable and looking for the
|
|
|
|
<filename>conf/</filename> directory.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The <filename>bitbake.conf</filename> file lists other configuration
|
|
|
|
files to include from a <filename>conf/</filename> directory below the
|
|
|
|
directories listed in <filename>BBPATH</filename>.
|
|
|
|
In general, the most important configuration file from a user's perspective
|
|
|
|
is <filename>local.conf</filename>, which contains a user's
|
|
|
|
customized settings for the build environment.
|
|
|
|
Other notable configuration files are the distribution configuration
|
|
|
|
file (set by the <filename>DISTRO</filename> variable) and the machine
|
|
|
|
configuration file (set by the <filename>MACHINE</filename> variable).
|
|
|
|
The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake
|
|
|
|
environment variables are both usually set in the
|
|
|
|
<filename>local.conf file</filename>.
|
|
|
|
Valid distribution configuration files are available
|
|
|
|
in the <filename>conf/distro/</filename> directory and valid machine
|
|
|
|
configuration files in the <filename>meta/conf/machine/</filename>
|
|
|
|
directory.
|
|
|
|
Within the <filename>conf/machine/include/</filename> directory are
|
|
|
|
various <filename>tune-*.inc</filename> configuration files
|
|
|
|
that provide common "tuning" settings specific to and shared between
|
|
|
|
particular architectures and machines.
|
|
|
|
</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
|
|
|
|
<filename>INHERIT</filename> variable are also included.
|
|
|
|
Class files are searched for 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 <filename>.bb</filename> files.
|
|
|
|
Adding extra content to <filename>BBFILES</filename> is best
|
|
|
|
achieved through the use of BitBake layers as described in the
|
|
|
|
Layers section below.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
BitBake parses each <filename>.bb</filename> file in
|
|
|
|
<filename>BBFILES</filename> and stores the values of various
|
|
|
|
variables.
|
|
|
|
In summary, for each <filename>.bb</filename> file the configuration
|
|
|
|
plus the base class of variables are set, followed by the data in the
|
|
|
|
<filename>.bb</filename> file itself, followed by any inherit commands
|
|
|
|
that <filename>.bb</filename> file might contain.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Because parsing <filename>.bb</filename> files is a time consuming
|
|
|
|
process, a cache is kept to speed up subsequent parsing.
|
|
|
|
This cache is invalid if the timestamp of the
|
|
|
|
<filename>.bb</filename> file itself changes, or if the timestamps of
|
|
|
|
any of the include, configuration files or class files on which
|
|
|
|
the <filename>.bb</filename> file depends change.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='configiguration-files'>
|
|
|
|
<title>Configuration files</title>
|
2014-01-18 14:32:51 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
|
|
|
The first kind of metadata in BitBake is configuration metadata.
|
2014-01-18 14:02:18 +00:00
|
|
|
This metadata is global, and therefore affects all packages and
|
|
|
|
tasks that are executed.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
BitBake will first search the current working directory for an
|
2014-01-18 13:20:36 +00:00
|
|
|
optional <filename>conf/bblayers.conf</filename> configuration file.
|
|
|
|
This file is expected to contain a <filename>BBLAYERS</filename>
|
2014-01-18 14:02:18 +00:00
|
|
|
variable that is a space delimited list of 'layer' directories.
|
2014-01-18 13:20:36 +00:00
|
|
|
For each directory in this list, a <filename>conf/layer.conf</filename>
|
2014-01-18 11:34:47 +00:00
|
|
|
file will be searched for and parsed with the
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>LAYERDIR</filename> variable being set to the directory where
|
2014-01-18 11:34:47 +00:00
|
|
|
the layer was found.
|
2014-01-18 13:20:36 +00:00
|
|
|
The idea is these files will setup <filename>BBPATH</filename>
|
2014-01-18 11:34:47 +00:00
|
|
|
and other variables correctly for a given build directory automatically
|
|
|
|
for the user.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:20:36 +00:00
|
|
|
BitBake will then expect to find <filename>conf/bitbake.conf</filename>
|
2014-01-18 14:02:18 +00:00
|
|
|
file somewhere in the user specified <filename>BBPATH</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
That configuration file generally has include directives to pull
|
|
|
|
in any other metadata (generally files specific to architecture,
|
2014-01-18 14:02:18 +00:00
|
|
|
machine, local and so on).
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:20:36 +00:00
|
|
|
Only variable definitions and include directives are allowed
|
|
|
|
in <filename>.conf</filename> files.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
2014-01-18 14:30:45 +00:00
|
|
|
|
|
|
|
<section id='layers'>
|
|
|
|
<title>Layers</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Layers allow you to isolate different types of
|
|
|
|
customizations from each other.
|
|
|
|
You might find it tempting to keep everything in one layer
|
|
|
|
when working on a single project.
|
|
|
|
However, the more modular you organize your Metadata, the
|
|
|
|
easier it is to cope with future changes.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To illustrate how layers are used 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, which is described
|
|
|
|
later in this section.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There are certain variable specific to layers, including:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para><filename>LAYERDEPENDS</filename></para></listitem>
|
|
|
|
<listitem><para><filename>LAYERVERSION</filename></para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-18 11:34:47 +00:00
|
|
|
</section>
|
2014-01-18 14:02:18 +00:00
|
|
|
|
2014-01-20 21:13:18 +00:00
|
|
|
<section id='metadata-classes'>
|
2014-01-18 11:34:47 +00:00
|
|
|
<title>Classes</title>
|
2014-01-18 14:02:18 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
|
|
|
BitBake classes are our rudimentary inheritance mechanism.
|
|
|
|
As briefly mentioned in the metadata introduction, they're
|
2014-01-18 13:20:36 +00:00
|
|
|
parsed when an inherit directive is encountered, and they
|
|
|
|
are located in the <filename>classes/</filename> directory
|
|
|
|
relative to the directories in <filename>BBPATH</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
2014-01-17 16:35:32 +00:00
|
|
|
</section>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='bb-files'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title><filename>.bb</filename> Files</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
A BitBake (<filename>.bb</filename>) file is a logical unit
|
2014-01-18 11:34:47 +00:00
|
|
|
of tasks to be executed.
|
|
|
|
Normally this is a package to be built.
|
2014-01-18 13:20:36 +00:00
|
|
|
Inter-<filename>.bb</filename> dependencies are obeyed.
|
2014-01-18 14:02:18 +00:00
|
|
|
The files themselves are located via the
|
|
|
|
<filename>BBFILES</filename> variable, which
|
2014-01-18 13:20:36 +00:00
|
|
|
is set to a space separated list of <filename>.bb</filename>
|
2014-01-18 11:34:47 +00:00
|
|
|
files, and does handle wildcards.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='events'>
|
|
|
|
<title>Events</title>
|
|
|
|
|
2014-01-18 14:02:18 +00:00
|
|
|
<note>
|
|
|
|
This is only supported in <filename>.bb</filename>
|
2014-01-18 13:20:36 +00:00
|
|
|
and <filename>.bbclass</filename> files.
|
2014-01-18 14:02:18 +00:00
|
|
|
</note>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<para>
|
|
|
|
BitBake allows installation of event handlers.
|
|
|
|
Events are triggered at certain points during operation,
|
|
|
|
such as the beginning of operation against a given
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>.bb</filename>, the start of a given task,
|
2014-01-18 14:02:18 +00:00
|
|
|
task failure, task success, and so forth.
|
2014-01-18 11:34:47 +00:00
|
|
|
The intent is to make it easy to do things like email
|
|
|
|
notification on build failure.
|
2014-01-18 13:14:30 +00:00
|
|
|
<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>
|
2014-01-18 11:34:47 +00:00
|
|
|
This event handler gets called every time an event is
|
|
|
|
triggered.
|
2014-01-18 14:02:18 +00:00
|
|
|
A global variable "<filename>e</filename>" is defined.
|
|
|
|
"<filename>e.data</filename>" contains an instance of
|
|
|
|
"<filename>bb.data</filename>".
|
2014-01-18 13:20:36 +00:00
|
|
|
With the <filename>getName(e)</filename> method one can get
|
2014-01-18 11:34:47 +00:00
|
|
|
the name of the triggered event.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The above event handler prints the name of the event
|
2014-01-18 13:20:36 +00:00
|
|
|
and the content of the <filename>FILE</filename> variable.
|
2014-01-18 14:22:41 +00:00
|
|
|
During a Build, 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>
|
|
|
|
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>
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='variants-class-extension-mechanism'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Variants - Class Extension Mechanism</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Two BitBake features exist to facilitate the creation of
|
|
|
|
multiple buildable incarnations from a single recipe file.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:20:36 +00:00
|
|
|
The first is <filename>BBCLASSEXTEND</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
This variable is a space separated list of classes used to "extend" the
|
|
|
|
recipe for each variant.
|
2014-01-18 14:02:18 +00:00
|
|
|
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.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
BBCLASSEXTEND = "native"
|
|
|
|
</literallayout>
|
2014-01-18 13:20:36 +00:00
|
|
|
The second feature is <filename>BBVERSIONS</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
This variable allows a single recipe to build multiple versions of a
|
|
|
|
project from a single recipe file, and allows you to specify
|
2014-01-18 13:20:36 +00:00
|
|
|
conditional metadata (using the <filename>OVERRIDES</filename>
|
2014-01-18 11:34:47 +00:00
|
|
|
mechanism) for a single version, or an optionally named range of versions:
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
BBVERSIONS = "1.0 2.0 git"
|
|
|
|
SRC_URI_git = "git://someurl/somepath.git"
|
|
|
|
</literallayout>
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
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>
|
2014-01-18 14:02:18 +00:00
|
|
|
The name of the range will default to the original version of the
|
2014-01-18 13:20:36 +00:00
|
|
|
recipe, so given OE, a recipe file of <filename>foo_1.0.0+.bb</filename>
|
|
|
|
will default the name of its versions to <filename>1.0.0+</filename>.
|
2014-01-18 11:34:47 +00:00
|
|
|
This is useful, as the range name is not only placed into overrides;
|
|
|
|
it's also made available for the metadata to use in the form of the
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>BPV</filename> variable, for use in
|
|
|
|
<filename>file://</filename> search paths (<filename>FILESPATH</filename>).
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='dependencies'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Dependencies</title>
|
|
|
|
|
|
|
|
<section id='dependencies-overview'>
|
|
|
|
<title>Overview</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
BitBake handles dependencies at the task level since to
|
|
|
|
allow for efficient operation with multiple
|
2014-01-18 14:02:18 +00:00
|
|
|
processes executing in parallel, a robust method of
|
|
|
|
specifying task dependencies is needed.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
2014-01-18 14:02:18 +00:00
|
|
|
</section>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<section id='dependencies-internal-to-the-bb-file'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Dependencies Internal to the <filename>.bb</filename> File</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Where the dependencies are internal to a given
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>.bb</filename> file, the dependencies are handled by the
|
|
|
|
previously detailed <filename>addtask</filename> directive.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
2013-01-11 17:45:15 +00:00
|
|
|
</section>
|
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='build-dependencies'>
|
|
|
|
<title>Build Dependencies</title>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>DEPENDS</filename> lists build time dependencies.
|
2014-01-18 11:34:47 +00:00
|
|
|
The 'deptask' flag for tasks is used to signify the task of each
|
2014-01-18 13:20:36 +00:00
|
|
|
item listed in <filename>DEPENDS</filename> which must have
|
2014-01-18 11:34:47 +00:00
|
|
|
completed before that task can be executed.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
do_configure[deptask] = "do_populate_staging"
|
|
|
|
</literallayout>
|
2014-01-18 14:02:18 +00:00
|
|
|
In the previous example, the <filename>do_populate_staging</filename>
|
2014-01-18 13:20:36 +00:00
|
|
|
task of each item in <filename>DEPENDS</filename> must have completed before
|
|
|
|
<filename>do_configure</filename> can execute.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='runtime-dependencies'>
|
|
|
|
<title>Runtime Dependencies</title>
|
|
|
|
|
|
|
|
<para>
|
2014-01-18 13:20:36 +00:00
|
|
|
The <filename>PACKAGES</filename> variable lists runtime
|
|
|
|
packages and each of these can have <filename>RDEPENDS</filename> and
|
|
|
|
<filename>RRECOMMENDS</filename> runtime dependencies.
|
2014-01-18 11:34:47 +00:00
|
|
|
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.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
do_package_write[rdeptask] = "do_package"
|
|
|
|
</literallayout>
|
2014-01-18 14:02:18 +00:00
|
|
|
In the previous example, the <filename>do_package</filename>
|
2014-01-18 13:20:36 +00:00
|
|
|
task of each item in <filename>RDEPENDS</filename> must have
|
|
|
|
completed before <filename>do_package_write</filename> can execute.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-17 16:35:32 +00:00
|
|
|
|
2014-01-18 11:34:47 +00:00
|
|
|
<section id='recursive-dependencies'>
|
|
|
|
<title>Recursive Dependencies</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
These are specified with the 'recrdeptask' flag
|
2014-01-18 14:02:18 +00:00
|
|
|
which is used to signify the task(s) of dependencies
|
2014-01-18 11:34:47 +00:00
|
|
|
which must have completed before that task can be
|
|
|
|
executed.
|
|
|
|
It works by looking though the build
|
|
|
|
and runtime dependencies of the current recipe as well
|
|
|
|
as any inter-task dependencies the task has,
|
|
|
|
then adding a dependency on the listed task.
|
|
|
|
It will then recurse through the dependencies of those
|
|
|
|
tasks and so on.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It may be desireable to recurse not just through the
|
|
|
|
dependencies of those tasks but through the
|
|
|
|
build and runtime dependencies of dependent tasks too.
|
|
|
|
If that is the case, the taskname itself should
|
2014-01-18 14:02:18 +00:00
|
|
|
be referenced in the task list (e.g.
|
|
|
|
<filename>do_a[recrdeptask] = "do_a do_b"</filename>).
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='inter-task-dependencies'>
|
2014-01-18 14:02:18 +00:00
|
|
|
<title>Inter-Task Dependencies</title>
|
2014-01-18 11:34:47 +00:00
|
|
|
|
|
|
|
<para>
|
2014-01-18 14:02:18 +00:00
|
|
|
The 'depends' flag for tasks is a more generic form which
|
|
|
|
allows an inter-dependency on specific tasks rather than specifying
|
2014-01-18 13:20:36 +00:00
|
|
|
the data in <filename>DEPENDS</filename>.
|
2014-01-18 13:14:30 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
do_patch[depends] = "quilt-native:do_populate_staging"
|
|
|
|
</literallayout>
|
2014-01-18 14:02:18 +00:00
|
|
|
In the previous example, the <filename>do_populate_staging</filename>
|
2014-01-18 11:34:47 +00:00
|
|
|
task of the target quilt-native must have completed before the
|
2014-01-18 13:20:36 +00:00
|
|
|
<filename>do_patch</filename> task can execute.
|
2014-01-18 11:34:47 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The 'rdepends' flag works in a similar way but takes targets
|
2014-01-18 14:02:18 +00:00
|
|
|
in the runtime namespace instead of the build-time dependency
|
2014-01-18 11:34:47 +00:00
|
|
|
namespace.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
2014-01-18 14:24:13 +00:00
|
|
|
|
|
|
|
<section id='accessing-variables-and-the-data-store-from-python'>
|
|
|
|
<title>Accessing Variables and the Data Store from Python</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It is often necessary to manipulate variables within python functions
|
|
|
|
and the Bitbake data store has an API which allows this.
|
|
|
|
The operations available are:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.getVar("X", expand=False)
|
|
|
|
</literallayout>
|
|
|
|
returns the value of variable "X", expanding the value
|
|
|
|
if specified.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.setVar("X", value)
|
|
|
|
</literallayout>
|
|
|
|
sets the value of "X" to "value".
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.appendVar("X", value)
|
|
|
|
</literallayout>
|
|
|
|
adds "value" to the end of variable X.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.prependVar("X", value)
|
|
|
|
</literallayout>
|
|
|
|
adds "value" to the start of variable X.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.delVar("X")
|
|
|
|
</literallayout>
|
|
|
|
deletes the variable X from the data store.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.renameVar("X", "Y")
|
|
|
|
</literallayout>
|
|
|
|
renames variable X to Y.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.getVarFlag("X", flag, expand=False)
|
|
|
|
</literallayout>
|
|
|
|
gets given flag from variable X but does not expand it.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.setVarFlag("X", flag, value)
|
|
|
|
</literallayout>
|
|
|
|
sets given flag for variable X to value.
|
|
|
|
<filename>setVarFlags</filename> will not clear previous flags.
|
|
|
|
Think of this method as <filename>addVarFlags</filename>.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.appendVarFlag("X", flag, value)
|
|
|
|
</literallayout>
|
|
|
|
Need description.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.prependVarFlag("X", flag, value)
|
|
|
|
</literallayout>
|
|
|
|
Need description.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.delVarFlag("X", flag)
|
|
|
|
</literallayout>
|
|
|
|
Need description.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.setVarFlags("X", flagsdict)
|
|
|
|
</literallayout>
|
|
|
|
sets the flags specified in the <filename>dict()</filename> parameter.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.getVarFlags("X")
|
|
|
|
</literallayout>
|
|
|
|
returns a <filename>dict</filename> of the flags for X.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
d.delVarFlags
|
|
|
|
</literallayout>
|
|
|
|
deletes all the flags for a variable.
|
|
|
|
</para>
|
|
|
|
</section>
|
2014-01-18 11:34:47 +00:00
|
|
|
</chapter>
|