diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index c693e1e6ec..6ee8971562 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -31,9 +31,9 @@
Basic variable setting
- VARIABLE = "value"
-
-
+
+ VARIABLE = "value"
+
In this example, VARIABLE is value.
@@ -48,10 +48,10 @@
- A = "aval"
-B = "pre${A}post"
-
-
+
+ A = "aval"
+ B = "pre${A}post"
+
This results in A containing
aval and B containing
preavalpost.
@@ -62,9 +62,9 @@
Setting a default value (?=)
- A ?= "aval"
-
-
+
+ A ?= "aval"
+
If A is set before the above is called,
it will retain its previous value.
If A is unset prior to the above call,
@@ -78,10 +78,10 @@
Setting a weak default value (??=)
- A ??= "somevalue"
-A ??= "someothervalue"
-
-
+
+ A ??= "somevalue"
+ A ??= "someothervalue"
+
If A is set before the above,
it will retain that value.
If A is unset prior to the above,
@@ -99,17 +99,14 @@
:= results in a variable's contents being expanded immediately, rather than when the variable is actually used.
-
-
- T = "123"
-A := "${B} ${A} test ${T}"
-T = "456"
-B = "${T} bval"
-
-C = "cval"
-C := "${C}append"
-
-
+
+ T = "123"
+ A := "${B} ${A} test ${T}"
+ T = "456"
+ B = "${T} bval"
+ C = "cval"
+ C := "${C}append"
+
In that example, A would contain test 123, B would contain 456 bval, and C would be cvalappend.
@@ -118,12 +115,12 @@
Appending (+=) and prepending (=+)
- B = "bval"
-B += "additionaldata"
-C = "cval"
-C =+ "test"
-
-
+
+ B = "bval"
+ B += "additionaldata"
+ C = "cval"
+ C =+ "test"
+
In this example, B is now bval additionaldata and C is test cval.
@@ -132,12 +129,12 @@
Appending (.=) and prepending (=.) without spaces
- B = "bval"
-B .= "additionaldata"
-C = "cval"
-C =. "test"
-
-
+
+ B = "bval"
+ B .= "additionaldata"
+ C = "cval"
+ C =. "test"
+
In this example, B is now
bvaladditionaldata and
C is testcval.
@@ -150,12 +147,12 @@
Appending and Prepending (override style syntax)
- B = "bval"
-B_append = " additional data"
-C = "cval"
-C_prepend = "additional data "
-
-
+
+ B = "bval"
+ B_append = " additional data"
+ C = "cval"
+ C_prepend = "additional data "
+
This example results in B
becoming bval additional data
and C becoming
@@ -170,11 +167,11 @@ yourself.
Removing (override style syntax)
- FOO = "123 456 789 123456 123 456 123 456"
-FOO_remove = "123"
-FOO_remove = "456"
-
-
+
+ FOO = "123 456 789 123456 123 456 123 456"
+ FOO_remove = "123"
+ FOO_remove = "456"
+
In this example, FOO is now 789 123456.
@@ -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.
-
-
- VARIABLE[SOMEFLAG] = "value"
-
-
+
+ VARIABLE[SOMEFLAG] = "value"
+
In this example, VARIABLE has a flag,
SOMEFLAG which is set to value.
@@ -200,9 +195,9 @@ yourself.
Python variable expansion
- DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
-
-
+
+ DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
+
This would result in the DATE
variable containing today's date.
@@ -219,14 +214,12 @@ yourself.
version of the variable is used rather than the non-conditional
version.
Example:
-
-
- OVERRIDES = "architecture:os:machine"
-TEST = "defaultvalue"
-TEST_os = "osspecificvalue"
-TEST_condnotinoverrides = "othercondvalue"
-
-
+
+ OVERRIDES = "architecture:os:machine"
+ TEST = "defaultvalue"
+ TEST_os = "osspecificvalue"
+ TEST_condnotinoverrides = "othercondvalue"
+
In this example, TEST would be
osspecificvalue, due to the condition
os
being in OVERRIDES.
@@ -239,13 +232,11 @@ yourself.
BitBake also supports appending and prepending to variables based
on whether something is in OVERRIDES. Example:
-
-
- DEPENDS = "glibc ncurses"
-OVERRIDES = "machine:local"
-DEPENDS_append_machine = " libmad"
-
-
+
+ DEPENDS = "glibc ncurses"
+ OVERRIDES = "machine:local"
+ DEPENDS_append_machine = "libmad"
+
In this example, DEPENDS is set to
glibc ncurses libmad.
@@ -268,43 +259,38 @@ yourself.
- OVERRIDES = "foo"
-A_foo_append = "X"
-
-
+
+ OVERRIDES = "foo"
+ A_foo_append = "X"
+
In this case, X is unconditionally appended
to the variable A_foo.
Since foo is an override, A_foo would then replace
A.
-
-
- OVERRIDES = "foo"
-A = "X"
-A_append_foo = "Y"
-
+
+ OVERRIDES = "foo"
+ A = "X"
+ A_append_foo = "Y"
+
In this case, only when foo is in
OVERRIDES, Y
is appended to the variable A
so the value of A would
become XY (NB: no spaces are appended).
-
-
- OVERRIDES = "foo"
-A_foo_append = "X"
-A_foo_append += "Y"
-
-
+
+ OVERRIDES = "foo"
+ A_foo_append = "X"
+ A_foo_append += "Y"
+
This behaves as per the first case above, but the value of
A would be "X Y" instead of just "X".
-
-
- A = "1"
-A_append = "2"
-A_append = "3"
-A += "4"
-A .= "5"
-
-
+
+ A = "1"
+ A_append = "2"
+ A_append = "3"
+ A += "4"
+ A .= "5"
+
Would ultimately result in A 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.
Key expansion happens at the data store finalisation
time just before overrides are expanded.
-
-
- A${B} = "X"
-B = "2"
-A2 = "Y"
-
-
+
+ A${B} = "X"
+ B = "2"
+ A2 = "Y"
+
So in this case A2 would take the value of "X".
@@ -378,18 +362,15 @@ raise an
Defining Python functions into the global Python namespace
NOTE: This is only supported in .bb and .bbclass files
-
-
- def get_depends(bb, d):
- if d.getVar('SOMECONDITION', True):
- return "dependencywithcond"
- else:
- return "dependency"
-
-SOMECONDITION = "1"
-DEPENDS = "${@get_depends(bb, d)}"
-
-
+
+ def get_depends(d):
+ if d.getVar('SOMECONDITION', True):
+ return "dependencywithcond"
+ else:
+ return "dependency"
+ SOMECONDITION = "1"
+ DEPENDS = "${@get_depends(d)}"
+
This would result in DEPENDS containing dependencywithcond.
@@ -397,22 +378,18 @@ raise an
Defining executable metadata
NOTE: This is only supported in .bb and .bbclass files.
-
-
- do_mytask () {
+
+do_mytask () {
echo "Hello, world!"
-}
-
-
+}
+
This is essentially identical to setting a variable, except that this variable happens to be executable shell code.
-
-
- python do_printdate () {
+
+python do_printdate () {
import time
print time.strftime('%Y%m%d', time.gmtime())
-}
-
-
+}
+
This is the similar to the previous, but flags it as Python so that BitBake knows it is Python code.
@@ -421,16 +398,13 @@ raise an
Tasks
NOTE: This is only supported in .bb and .bbclass files.
In BitBake, each step that needs to be run for a given .bb is known as a task. There is a command addtask to add new tasks (must be a defined Python executable metadata and must start with do_
) and describe intertask dependencies.
-
-
- python do_printdate () {
- import time
- print time.strftime('%Y%m%d', time.gmtime())
-}
-
-addtask printdate before do_build
-
-
+
+ python do_printdate () {
+ import time print
+ time.strftime('%Y%m%d', time.gmtime())
+ }
+ addtask printdate after do_fetch before do_build
+
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.
@@ -529,19 +503,15 @@ addtask printdate before do_build
task failure, task success, et cetera.
The intent is to make it easy to do things like email
notification on build failure.
-
-
- 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))
-}
-
-
-
+
+ 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))
+ }
+
This event handler gets called every time an event is
triggered.
A global variable e is defined.
@@ -569,7 +539,10 @@ python myclass_eventhandler() {
The first is BBCLASSEXTEND.
This variable is a space separated list of classes used to "extend" the
recipe for each variant.
- As an example, setting BBCLASSEXTEND = "native"
+ As an example, setting
+
+ BBCLASSEXTEND = "native"
+
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 OVERRIDES
mechanism) for a single version, or an optionally named range of versions:
-
-
- 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"
-
-
+
+ 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"
+
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.
-
-
- do_configure[deptask] = "do_populate_staging"
-
-
+
+ do_configure[deptask] = "do_populate_staging"
+
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.
-
-
- do_package_write[rdeptask] = "do_package"
-
-
+
+ do_package_write[rdeptask] = "do_package"
+
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.
-
-
- do_patch[depends] = "quilt-native:do_populate_staging"
-
-
+
+ do_patch[depends] = "quilt-native:do_populate_staging"
+
means the do_populate_staging
task of the target quilt-native must have completed before the
do_patch can execute.