bitbake: user-manual-metadata: Replace screen tags with literallayout tags
(Bitbake rev: be3967f9f088e414c679e72a947817b60bab82d7) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Richard Purdie
parent
0e90d0f1a4
commit
a0f3328679
|
|
@ -31,9 +31,9 @@
|
|||
<title>Basic variable setting</title>
|
||||
|
||||
<para>
|
||||
<screen><varname>VARIABLE</varname> = "value"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
VARIABLE = "value"
|
||||
</literallayout>
|
||||
In this example, <varname>VARIABLE</varname> is <literal>value</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -48,10 +48,10 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
<screen><varname>A</varname> = "aval"
|
||||
<varname>B</varname> = "pre${A}post"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
A = "aval"
|
||||
B = "pre${A}post"
|
||||
</literallayout>
|
||||
This results in <varname>A</varname> containing
|
||||
<literal>aval</literal> and <varname>B</varname> containing
|
||||
<literal>preavalpost</literal>.
|
||||
|
|
@ -62,9 +62,9 @@
|
|||
<title>Setting a default value (?=)</title>
|
||||
|
||||
<para>
|
||||
<screen><varname>A</varname> ?= "aval"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
A ?= "aval"
|
||||
</literallayout>
|
||||
If <varname>A</varname> is set before the above is called,
|
||||
it will retain its previous value.
|
||||
If <varname>A</varname> is unset prior to the above call,
|
||||
|
|
@ -78,10 +78,10 @@
|
|||
<title>Setting a weak default value (??=)</title>
|
||||
|
||||
<para>
|
||||
<screen><varname>A</varname> ??= "somevalue"
|
||||
<varname>A</varname> ??= "someothervalue"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
A ??= "somevalue"
|
||||
A ??= "someothervalue"
|
||||
</literallayout>
|
||||
If <varname>A</varname> is set before the above,
|
||||
it will retain that value.
|
||||
If <varname>A</varname> is unset prior to the above,
|
||||
|
|
@ -99,17 +99,14 @@
|
|||
|
||||
<para>
|
||||
:= results in a variable's contents being expanded immediately, rather than when the variable is actually used.
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>T</varname> = "123"
|
||||
<varname>A</varname> := "${B} ${A} test ${T}"
|
||||
<varname>T</varname> = "456"
|
||||
<varname>B</varname> = "${T} bval"
|
||||
|
||||
<varname>C</varname> = "cval"
|
||||
<varname>C</varname> := "${C}append"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
T = "123"
|
||||
A := "${B} ${A} test ${T}"
|
||||
T = "456"
|
||||
B = "${T} bval"
|
||||
C = "cval"
|
||||
C := "${C}append"
|
||||
</literallayout>
|
||||
In that example, <varname>A</varname> would contain <literal> test 123</literal>, <varname>B</varname> would contain <literal>456 bval</literal>, and <varname>C</varname> would be <literal>cvalappend</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -118,12 +115,12 @@
|
|||
<title>Appending (+=) and prepending (=+)</title>
|
||||
|
||||
<para>
|
||||
<screen><varname>B</varname> = "bval"
|
||||
<varname>B</varname> += "additionaldata"
|
||||
<varname>C</varname> = "cval"
|
||||
<varname>C</varname> =+ "test"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
B = "bval"
|
||||
B += "additionaldata"
|
||||
C = "cval"
|
||||
C =+ "test"
|
||||
</literallayout>
|
||||
In this example, <varname>B</varname> is now <literal>bval additionaldata</literal> and <varname>C</varname> is <literal>test cval</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -132,12 +129,12 @@
|
|||
<title>Appending (.=) and prepending (=.) without spaces</title>
|
||||
|
||||
<para>
|
||||
<screen><varname>B</varname> = "bval"
|
||||
<varname>B</varname> .= "additionaldata"
|
||||
<varname>C</varname> = "cval"
|
||||
<varname>C</varname> =. "test"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
B = "bval"
|
||||
B .= "additionaldata"
|
||||
C = "cval"
|
||||
C =. "test"
|
||||
</literallayout>
|
||||
In this example, <varname>B</varname> is now
|
||||
<literal>bvaladditionaldata</literal> and
|
||||
<varname>C</varname> is <literal>testcval</literal>.
|
||||
|
|
@ -150,12 +147,12 @@
|
|||
<title>Appending and Prepending (override style syntax)</title>
|
||||
|
||||
<para>
|
||||
<screen><varname>B</varname> = "bval"
|
||||
<varname>B_append</varname> = " additional data"
|
||||
<varname>C</varname> = "cval"
|
||||
<varname>C_prepend</varname> = "additional data "</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
B = "bval"
|
||||
B_append = " additional data"
|
||||
C = "cval"
|
||||
C_prepend = "additional data "
|
||||
</literallayout>
|
||||
This example results in <varname>B</varname>
|
||||
becoming <literal>bval additional data</literal>
|
||||
and <varname>C</varname> becoming
|
||||
|
|
@ -170,11 +167,11 @@ yourself.
|
|||
<section id='removing-override-style-syntax'>
|
||||
<title>Removing (override style syntax)</title>
|
||||
<para>
|
||||
<screen><varname>FOO</varname> = "123 456 789 123456 123 456 123 456"
|
||||
<varname>FOO_remove</varname> = "123"
|
||||
<varname>FOO_remove</varname> = "456"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
FOO = "123 456 789 123456 123 456 123 456"
|
||||
FOO_remove = "123"
|
||||
FOO_remove = "456"
|
||||
</literallayout>
|
||||
In this example, <varname>FOO</varname> is now <literal>789 123456</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -186,11 +183,9 @@ yourself.
|
|||
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.
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>VARIABLE</varname>[<varname>SOMEFLAG</varname>] = "value"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
VARIABLE[SOMEFLAG] = "value"
|
||||
</literallayout>
|
||||
In this example, <varname>VARIABLE</varname> has a flag,
|
||||
<varname>SOMEFLAG</varname> which is set to <literal>value</literal>.
|
||||
</para>
|
||||
|
|
@ -200,9 +195,9 @@ yourself.
|
|||
<title>Python variable expansion</title>
|
||||
|
||||
<para>
|
||||
<screen><varname>DATE</varname> = "${@time.strftime('%Y%m%d',time.gmtime())}"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
|
||||
</literallayout>
|
||||
This would result in the <varname>DATE</varname>
|
||||
variable containing today's date.
|
||||
</para>
|
||||
|
|
@ -219,14 +214,12 @@ yourself.
|
|||
version of the variable is used rather than the non-conditional
|
||||
version.
|
||||
Example:
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>OVERRIDES</varname> = "architecture:os:machine"
|
||||
<varname>TEST</varname> = "defaultvalue"
|
||||
<varname>TEST_os</varname> = "osspecificvalue"
|
||||
<varname>TEST_condnotinoverrides</varname> = "othercondvalue"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
OVERRIDES = "architecture:os:machine"
|
||||
TEST = "defaultvalue"
|
||||
TEST_os = "osspecificvalue"
|
||||
TEST_condnotinoverrides = "othercondvalue"
|
||||
</literallayout>
|
||||
In this example, <varname>TEST</varname> would be
|
||||
<literal>osspecificvalue</literal>, due to the condition
|
||||
<quote>os</quote> being in <varname>OVERRIDES</varname>.
|
||||
|
|
@ -239,13 +232,11 @@ yourself.
|
|||
<para>
|
||||
BitBake also supports appending and prepending to variables based
|
||||
on whether something is in OVERRIDES. Example:
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>DEPENDS</varname> = "glibc ncurses"
|
||||
<varname>OVERRIDES</varname> = "machine:local"
|
||||
<varname>DEPENDS_append_machine</varname> = " libmad"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
DEPENDS = "glibc ncurses"
|
||||
OVERRIDES = "machine:local"
|
||||
DEPENDS_append_machine = "libmad"
|
||||
</literallayout>
|
||||
In this example, <varname>DEPENDS</varname> is set to
|
||||
<literal>glibc ncurses libmad</literal>.
|
||||
</para>
|
||||
|
|
@ -268,43 +259,38 @@ yourself.
|
|||
</para>
|
||||
|
||||
<para>
|
||||
<screen><varname>OVERRIDES</varname> = "foo"
|
||||
<varname>A_foo_append</varname> = "X"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
OVERRIDES = "foo"
|
||||
A_foo_append = "X"
|
||||
</literallayout>
|
||||
In this case, X is unconditionally appended
|
||||
to the variable <varname>A_foo</varname>.
|
||||
Since foo is an override, A_foo would then replace
|
||||
<varname>A</varname>.
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>OVERRIDES</varname> = "foo"
|
||||
<varname>A</varname> = "X"
|
||||
<varname>A_append_foo</varname> = "Y"</screen></para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
OVERRIDES = "foo"
|
||||
A = "X"
|
||||
A_append_foo = "Y"
|
||||
</literallayout>
|
||||
In this case, only when foo is in
|
||||
OVERRIDES, Y
|
||||
is appended to the variable <varname>A</varname>
|
||||
so the value of <varname>A</varname> would
|
||||
become XY (NB: no spaces are appended).
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>OVERRIDES</varname> = "foo"
|
||||
<varname>A_foo_append</varname> = "X"
|
||||
<varname>A_foo_append</varname> += "Y"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
OVERRIDES = "foo"
|
||||
A_foo_append = "X"
|
||||
A_foo_append += "Y"
|
||||
</literallayout>
|
||||
This behaves as per the first case above, but the value of
|
||||
<varname>A</varname> would be "X Y" instead of just "X".
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>A</varname> = "1"
|
||||
<varname>A_append</varname> = "2"
|
||||
<varname>A_append</varname> = "3"
|
||||
<varname>A</varname> += "4"
|
||||
<varname>A</varname> .= "5"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
A = "1"
|
||||
A_append = "2"
|
||||
A_append = "3"
|
||||
A += "4"
|
||||
A .= "5"
|
||||
</literallayout>
|
||||
Would ultimately result in <varname>A</varname> taking the value
|
||||
"1 4523" since the _append operator executes at the
|
||||
same time as the expansion of other overrides.
|
||||
|
|
@ -317,13 +303,11 @@ yourself.
|
|||
<para>
|
||||
Key expansion happens at the data store finalisation
|
||||
time just before overrides are expanded.
|
||||
</para>
|
||||
<para>
|
||||
<screen><varname>A${B}</varname> = "X"
|
||||
<varname>B</varname> = "2"
|
||||
<varname>A2</varname> = "Y"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
A${B} = "X"
|
||||
B = "2"
|
||||
A2 = "Y"
|
||||
</literallayout>
|
||||
So in this case <varname>A2</varname> would take the value of "X".
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -378,18 +362,15 @@ raise an
|
|||
<title>Defining Python functions into the global Python namespace</title>
|
||||
|
||||
<para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files
|
||||
</para>
|
||||
<para>
|
||||
<screen>def get_depends(bb, d):
|
||||
if d.getVar('SOMECONDITION', True):
|
||||
return "dependencywithcond"
|
||||
else:
|
||||
return "dependency"
|
||||
|
||||
<varname>SOMECONDITION</varname> = "1"
|
||||
<varname>DEPENDS</varname> = "${@get_depends(bb, d)}"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<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 <varname>DEPENDS</varname> containing <literal>dependencywithcond</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -397,22 +378,18 @@ raise an
|
|||
<section>
|
||||
<title>Defining executable metadata</title>
|
||||
<para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.
|
||||
</para>
|
||||
<para>
|
||||
<screen>do_mytask () {
|
||||
<literallayout class='monospaced'>
|
||||
do_mytask () {
|
||||
echo "Hello, world!"
|
||||
}</screen>
|
||||
</para>
|
||||
<para>
|
||||
}
|
||||
</literallayout>
|
||||
This is essentially identical to setting a variable, except that this variable happens to be executable shell code.
|
||||
</para>
|
||||
<para>
|
||||
<screen>python do_printdate () {
|
||||
<literallayout class='monospaced'>
|
||||
python do_printdate () {
|
||||
import time
|
||||
print time.strftime('%Y%m%d', time.gmtime())
|
||||
}</screen>
|
||||
</para>
|
||||
<para>
|
||||
}
|
||||
</literallayout>
|
||||
This is the similar to the previous, but flags it as Python so that BitBake knows it is Python code.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -421,16 +398,13 @@ raise an
|
|||
<title>Tasks</title>
|
||||
<para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para>
|
||||
<para>In BitBake, each step that needs to be run for a given .bb is known as a task. There is a command <literal>addtask</literal> to add new tasks (must be a defined Python executable metadata and must start with <quote>do_</quote>) and describe intertask dependencies.
|
||||
</para>
|
||||
<para>
|
||||
<screen>python do_printdate () {
|
||||
import time
|
||||
print time.strftime('%Y%m%d', time.gmtime())
|
||||
}
|
||||
|
||||
addtask printdate before do_build</screen>
|
||||
</para>
|
||||
<para>
|
||||
<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>
|
||||
This defines the necessary Python function and adds it as a task which is now a dependency of do_build, the default task. If anyone executes the do_build task, that will result in do_printdate being run first.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -529,19 +503,15 @@ addtask printdate before do_build</screen>
|
|||
task failure, task success, et cetera.
|
||||
The intent is to make it easy to do things like email
|
||||
notification on build failure.
|
||||
</para>
|
||||
<para>
|
||||
<screen>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))
|
||||
}
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
<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 <varname>e</varname> is defined.
|
||||
|
|
@ -569,7 +539,10 @@ python myclass_eventhandler() {
|
|||
The first is <varname>BBCLASSEXTEND</varname>.
|
||||
This variable is a space separated list of classes used to "extend" the
|
||||
recipe for each variant.
|
||||
As an example, setting <screen>BBCLASSEXTEND = "native"</screen>
|
||||
As an example, setting
|
||||
<literallayout class='monospaced'>
|
||||
BBCLASSEXTEND = "native"
|
||||
</literallayout>
|
||||
results in a second incarnation of the current
|
||||
recipe being available.
|
||||
This second incarnation will have the "native" class inherited.
|
||||
|
|
@ -580,17 +553,14 @@ python myclass_eventhandler() {
|
|||
project from a single recipe file, and allows you to specify
|
||||
conditional metadata (using the <varname>OVERRIDES</varname>
|
||||
mechanism) for a single version, or an optionally named range of versions:
|
||||
</para>
|
||||
<para>
|
||||
<screen>BBVERSIONS = "1.0 2.0 git"
|
||||
SRC_URI_git = "git://someurl/somepath.git"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<screen>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"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<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>
|
||||
Note that the name of the range will default to the original version of the
|
||||
recipe, so given OE, a recipe file of foo_1.0.0+.bb
|
||||
will default the name of its versions to 1.0.0+.
|
||||
|
|
@ -629,11 +599,9 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
|
|||
The 'deptask' flag for tasks is used to signify the task of each
|
||||
item listed in DEPENDS which must have
|
||||
completed before that task can be executed.
|
||||
</para>
|
||||
<para>
|
||||
<screen>do_configure[deptask] = "do_populate_staging"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
do_configure[deptask] = "do_populate_staging"
|
||||
</literallayout>
|
||||
means the do_populate_staging
|
||||
task of each item in DEPENDS must have completed before
|
||||
do_configure can execute.
|
||||
|
|
@ -650,11 +618,9 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
|
|||
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.
|
||||
</para>
|
||||
<para>
|
||||
<screen>do_package_write[rdeptask] = "do_package"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
do_package_write[rdeptask] = "do_package"
|
||||
</literallayout>
|
||||
means the do_package
|
||||
task of each item in RDEPENDS must have
|
||||
completed before do_package_write can execute.
|
||||
|
|
@ -694,11 +660,9 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
|
|||
The 'depends' flag for tasks is a more generic form of which
|
||||
allows an interdependency on specific tasks rather than specifying
|
||||
the data in DEPENDS.
|
||||
</para>
|
||||
<para>
|
||||
<screen>do_patch[depends] = "quilt-native:do_populate_staging"</screen>
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>
|
||||
do_patch[depends] = "quilt-native:do_populate_staging"
|
||||
</literallayout>
|
||||
means the do_populate_staging
|
||||
task of the target quilt-native must have completed before the
|
||||
do_patch can execute.
|
||||
|
|
|
|||
Loading…
Reference in New Issue