mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-31 12:49:46 +00:00
Code Issues Projects Releases Wiki Activity

bitbake: user-manual-metadata: Replace screen tags with literallayout tags

Browse Source 
(Bitbake rev: be3967f9f088e414c679e72a947817b60bab82d7)

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