diff options
author | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-18 13:14:30 +0000 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-27 21:03:20 +0000 |
commit | a0f3328679fef6c14d2d38d3fbb398a952f77cfa (patch) | |
tree | f4e2cce15bf8e2dfc2c710fc009599592ae92089 /bitbake/doc/user-manual | |
parent | 0e90d0f1a4e5b9b89b88bd4d34049b9cdf7f03f7 (diff) | |
download | ast2050-yocto-poky-a0f3328679fef6c14d2d38d3fbb398a952f77cfa.zip ast2050-yocto-poky-a0f3328679fef6c14d2d38d3fbb398a952f77cfa.tar.gz |
bitbake: user-manual-metadata: Replace screen tags with literallayout tags
(Bitbake rev: be3967f9f088e414c679e72a947817b60bab82d7)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/user-manual')
-rw-r--r-- | bitbake/doc/user-manual/user-manual-metadata.xml | 320 |
1 files changed, 142 insertions, 178 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml index c693e1e..6ee8971 100644 --- a/bitbake/doc/user-manual/user-manual-metadata.xml +++ b/bitbake/doc/user-manual/user-manual-metadata.xml @@ -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. |