summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual/user-manual-metadata.xml
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-18 11:34:47 +0000
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-27 21:03:20 +0000
commit0e90d0f1a4e5b9b89b88bd4d34049b9cdf7f03f7 (patch)
treef4ae90e2e3071c732167eeeebde1d62ea3aac9ab /bitbake/doc/user-manual/user-manual-metadata.xml
parent4dd8a0d6d6c9f9691e25c2ea8c4fc86435a8e864 (diff)
downloadpoky-0e90d0f1a4e5b9b89b88bd4d34049b9cdf7f03f7.tar.gz
bitbake: user-manual-metadata: Update whitespace (no content changes)
(Bitbake rev: 7eb1e340321ab4a5baa23e83eebf65ba13d23aef) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/user-manual/user-manual-metadata.xml')
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml868
1 files changed, 621 insertions, 247 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index efbbfb469e..c693e1e6ec 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -1,8 +1,10 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3 <chapter id="user-manual-metadata"> 3
4 <title>Metadata</title> 4<chapter id="user-manual-metadata">
5 <section> 5 <title>Metadata</title>
6
7 <section>
6 <title>Description</title> 8 <title>Description</title>
7 <itemizedlist> 9 <itemizedlist>
8 <para>BitBake metadata can be classified into 3 major areas:</para> 10 <para>BitBake metadata can be classified into 3 major areas:</para>
@@ -16,230 +18,430 @@
16 <para>Classes</para> 18 <para>Classes</para>
17 </listitem> 19 </listitem>
18 </itemizedlist> 20 </itemizedlist>
19 <para>What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported in any of the aforementioned areas will be documented as such.</para> 21 <para>
22 What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported
23 in any of the aforementioned areas will be documented as such.
24 </para>
20 </section> 25 </section>
21 26
22 <section id='basic-syntax'> 27 <section id='basic-syntax'>
23 <title>Basic Syntax</title> 28 <title>Basic Syntax</title>
24 29
25 <section id='basic-variable-setting'> 30 <section id='basic-variable-setting'>
26 <title>Basic variable setting</title> 31 <title>Basic variable setting</title>
27 <para><screen><varname>VARIABLE</varname> = "value"</screen></para> 32
28 <para>In this example, <varname>VARIABLE</varname> is <literal>value</literal>.</para> 33 <para>
29 </section> 34 <screen><varname>VARIABLE</varname> = "value"</screen>
30 35 </para>
31 <section id='variable-expansion'> 36 <para>
32 <title>Variable expansion</title> 37 In this example, <varname>VARIABLE</varname> is <literal>value</literal>.
33 <para>BitBake supports variables referencing one another's contents using a syntax which is similar to shell scripting</para> 38 </para>
34 <para><screen><varname>A</varname> = "aval" 39 </section>
35<varname>B</varname> = "pre${A}post"</screen></para> 40
36 <para>This results in <varname>A</varname> containing <literal>aval</literal> and <varname>B</varname> containing <literal>preavalpost</literal>.</para> 41 <section id='variable-expansion'>
37 </section> 42 <title>Variable expansion</title>
38 43
39 <section id='setting-a-default-value'> 44 <para>
40 <title>Setting a default value (?=)</title> 45 BitBake supports variables referencing one another's
41 <para><screen><varname>A</varname> ?= "aval"</screen></para> 46 contents using a syntax which is similar to shell
42 <para>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, <varname>A</varname> will be set to <literal>aval</literal>. Note that this assignment is immediate, so if there are multiple ?= assignments to a single variable, the first of those will be used.</para> 47 scripting
43 </section> 48 </para>
44 49
45 <section id='setting-a-weak-default-value'> 50 <para>
46 <title>Setting a weak default value (??=)</title> 51 <screen><varname>A</varname> = "aval"
47 <para><screen><varname>A</varname> ??= "somevalue" 52<varname>B</varname> = "pre${A}post"</screen>
48<varname>A</varname> ??= "someothervalue"</screen></para> 53 </para>
49 <para>If <varname>A</varname> is set before the above, it will retain that value. If <varname>A</varname> is unset prior to the above, <varname>A</varname> will be set to <literal>someothervalue</literal>. This is a lazy/weak assignment in that the assignment does not occur until the end of the parsing process, so that the last, rather than the first, ??= assignment to a given variable will be used. Any other setting of A using = or ?= will however override the value set with ??=</para> 54 <para>
50 </section> 55 This results in <varname>A</varname> containing
51 56 <literal>aval</literal> and <varname>B</varname> containing
52 <section id='immediate-variable-expansion'> 57 <literal>preavalpost</literal>.
53 <title>Immediate variable expansion (:=)</title> 58 </para>
54 <para>:= results in a variable's contents being expanded immediately, rather than when the variable is actually used.</para> 59 </section>
55 <para><screen><varname>T</varname> = "123" 60
61 <section id='setting-a-default-value'>
62 <title>Setting a default value (?=)</title>
63
64 <para>
65 <screen><varname>A</varname> ?= "aval"</screen>
66 </para>
67 <para>
68 If <varname>A</varname> is set before the above is called,
69 it will retain its previous value.
70 If <varname>A</varname> is unset prior to the above call,
71 <varname>A</varname> will be set to <literal>aval</literal>.
72 Note that this assignment is immediate, so if there are multiple ?= assignments
73 to a single variable, the first of those will be used.
74 </para>
75 </section>
76
77 <section id='setting-a-weak-default-value'>
78 <title>Setting a weak default value (??=)</title>
79
80 <para>
81 <screen><varname>A</varname> ??= "somevalue"
82<varname>A</varname> ??= "someothervalue"</screen>
83 </para>
84 <para>
85 If <varname>A</varname> is set before the above,
86 it will retain that value.
87 If <varname>A</varname> is unset prior to the above,
88 <varname>A</varname> will be set to <literal>someothervalue</literal>.
89 This is a lazy/weak assignment in that the assignment does not occur until the end
90 of the parsing process, so that the last, rather than the first,
91 ??= assignment to a given variable will be used.
92 Any other setting of A using = or ?=
93 will however override the value set with ??=
94 </para>
95 </section>
96
97 <section id='immediate-variable-expansion'>
98 <title>Immediate variable expansion (:=)</title>
99
100 <para>
101 := results in a variable's contents being expanded immediately, rather than when the variable is actually used.
102 </para>
103 <para>
104 <screen><varname>T</varname> = "123"
56<varname>A</varname> := "${B} ${A} test ${T}" 105<varname>A</varname> := "${B} ${A} test ${T}"
57<varname>T</varname> = "456" 106<varname>T</varname> = "456"
58<varname>B</varname> = "${T} bval" 107<varname>B</varname> = "${T} bval"
59 108
60<varname>C</varname> = "cval" 109<varname>C</varname> = "cval"
61<varname>C</varname> := "${C}append"</screen></para> 110<varname>C</varname> := "${C}append"</screen>
62 <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>.</para> 111 </para>
63 </section> 112 <para>
113 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>.
114 </para>
115 </section>
116
117 <section id='appending-and-prepending'>
118 <title>Appending (+=) and prepending (=+)</title>
64 119
65 <section id='appending-and-prepending'> 120 <para>
66 <title>Appending (+=) and prepending (=+)</title> 121 <screen><varname>B</varname> = "bval"
67 <para><screen><varname>B</varname> = "bval"
68<varname>B</varname> += "additionaldata" 122<varname>B</varname> += "additionaldata"
69<varname>C</varname> = "cval" 123<varname>C</varname> = "cval"
70<varname>C</varname> =+ "test"</screen></para> 124<varname>C</varname> =+ "test"</screen>
71 <para>In this example, <varname>B</varname> is now <literal>bval additionaldata</literal> and <varname>C</varname> is <literal>test cval</literal>.</para> 125 </para>
72 </section> 126 <para>
127 In this example, <varname>B</varname> is now <literal>bval additionaldata</literal> and <varname>C</varname> is <literal>test cval</literal>.
128 </para>
129 </section>
130
131 <section id='appending-and-prepending-without-spaces'>
132 <title>Appending (.=) and prepending (=.) without spaces</title>
73 133
74 <section id='appending-and-prepending-without-spaces'> 134 <para>
75 <title>Appending (.=) and prepending (=.) without spaces</title> 135 <screen><varname>B</varname> = "bval"
76 <para><screen><varname>B</varname> = "bval"
77<varname>B</varname> .= "additionaldata" 136<varname>B</varname> .= "additionaldata"
78<varname>C</varname> = "cval" 137<varname>C</varname> = "cval"
79<varname>C</varname> =. "test"</screen></para> 138<varname>C</varname> =. "test"</screen>
80 <para>In this example, <varname>B</varname> is now <literal>bvaladditionaldata</literal> and <varname>C</varname> is <literal>testcval</literal>. In contrast to the above appending and prepending operators, no additional space 139 </para>
81will be introduced.</para> 140 <para>
82 </section> 141 In this example, <varname>B</varname> is now
83 142 <literal>bvaladditionaldata</literal> and
84 <section id='appending-and-prepending-override-style-syntax'> 143 <varname>C</varname> is <literal>testcval</literal>.
85 <title>Appending and Prepending (override style syntax)</title> 144 In contrast to the above appending and prepending operators,
86 <para><screen><varname>B</varname> = "bval" 145 no additional space will be introduced.
146 </para>
147 </section>
148
149 <section id='appending-and-prepending-override-style-syntax'>
150 <title>Appending and Prepending (override style syntax)</title>
151
152 <para>
153 <screen><varname>B</varname> = "bval"
87<varname>B_append</varname> = " additional data" 154<varname>B_append</varname> = " additional data"
88<varname>C</varname> = "cval" 155<varname>C</varname> = "cval"
89<varname>C_prepend</varname> = "additional data "</screen></para> 156<varname>C_prepend</varname> = "additional data "</screen>
90 <para>This example results in <varname>B</varname> becoming <literal>bval additional data</literal> 157 </para>
91and <varname>C</varname> becoming <literal>additional data cval</literal>. Note the spaces in the append. 158 <para>
92Unlike the += operator, additional space is not automatically added. You must take steps to add space 159 This example results in <varname>B</varname>
93yourself.</para> 160 becoming <literal>bval additional data</literal>
94 </section> 161 and <varname>C</varname> becoming
95 162 <literal>additional data cval</literal>.
96 <section id='removing-override-style-syntax'> 163 Note the spaces in the append.
97 <title>Removing (override style syntax)</title> 164 Unlike the += operator, additional space is not automatically added.
98 <para><screen><varname>FOO</varname> = "123 456 789 123456 123 456 123 456" 165 You must take steps to add space
166yourself.
167 </para>
168 </section>
169
170 <section id='removing-override-style-syntax'>
171 <title>Removing (override style syntax)</title>
172 <para>
173 <screen><varname>FOO</varname> = "123 456 789 123456 123 456 123 456"
99<varname>FOO_remove</varname> = "123" 174<varname>FOO_remove</varname> = "123"
100<varname>FOO_remove</varname> = "456"</screen></para> 175<varname>FOO_remove</varname> = "456"</screen>
101 <para>In this example, <varname>FOO</varname> is now <literal>789 123456</literal>.</para> 176 </para>
102 </section> 177 <para>
103 178 In this example, <varname>FOO</varname> is now <literal>789 123456</literal>.
104 <section id='variable-flags'> 179 </para>
105 <title>Variable flags</title> 180 </section>
106 <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.</para> 181
107 <para><screen><varname>VARIABLE</varname>[<varname>SOMEFLAG</varname>] = "value"</screen></para> 182 <section id='variable-flags'>
108 <para>In this example, <varname>VARIABLE</varname> has a flag, <varname>SOMEFLAG</varname> which is set to <literal>value</literal>.</para> 183 <title>Variable flags</title>
109 </section> 184
110 185 <para>
111 <section id='inline-python-variable-expansion'> 186 Variables can have associated flags which provide a way of tagging extra information onto a variable.
112 <title>Python variable expansion</title> 187 Several flags are used internally by BitBake but they can be used externally too if needed.
113 <para><screen><varname>DATE</varname> = "${@time.strftime('%Y%m%d',time.gmtime())}"</screen></para> 188 The standard operations mentioned above also work on flags.
114 <para>This would result in the <varname>DATE</varname> variable containing today's date.</para> 189 </para>
115 </section> 190 <para>
116 191 <screen><varname>VARIABLE</varname>[<varname>SOMEFLAG</varname>] = "value"</screen>
117 <section id='conditional-syntax-overrides'> 192 </para>
118 <title>Conditional metadata set</title> 193 <para>
119 <para>OVERRIDES is a <quote>:</quote> separated variable containing each item you want to satisfy conditions. So, if you have a variable which is conditional on <quote>arm</quote>, and <quote>arm</quote> is in OVERRIDES, then the <quote>arm</quote> specific version of the variable is used rather than the non-conditional version. Example:</para> 194 In this example, <varname>VARIABLE</varname> has a flag,
120 <para><screen><varname>OVERRIDES</varname> = "architecture:os:machine" 195 <varname>SOMEFLAG</varname> which is set to <literal>value</literal>.
196 </para>
197 </section>
198
199 <section id='inline-python-variable-expansion'>
200 <title>Python variable expansion</title>
201
202 <para>
203 <screen><varname>DATE</varname> = "${@time.strftime('%Y%m%d',time.gmtime())}"</screen>
204 </para>
205 <para>
206 This would result in the <varname>DATE</varname>
207 variable containing today's date.
208 </para>
209 </section>
210
211 <section id='conditional-syntax-overrides'>
212 <title>Conditional metadata set</title>
213
214 <para>
215 OVERRIDES is a <quote>:</quote> separated variable containing
216 each item you want to satisfy conditions.
217 So, if you have a variable which is conditional on <quote>arm</quote>, and <quote>arm</quote>
218 is in OVERRIDES, then the <quote>arm</quote> specific
219 version of the variable is used rather than the non-conditional
220 version.
221 Example:
222 </para>
223 <para>
224 <screen><varname>OVERRIDES</varname> = "architecture:os:machine"
121<varname>TEST</varname> = "defaultvalue" 225<varname>TEST</varname> = "defaultvalue"
122<varname>TEST_os</varname> = "osspecificvalue" 226<varname>TEST_os</varname> = "osspecificvalue"
123<varname>TEST_condnotinoverrides</varname> = "othercondvalue"</screen></para> 227<varname>TEST_condnotinoverrides</varname> = "othercondvalue"</screen>
124 <para>In this example, <varname>TEST</varname> would be <literal>osspecificvalue</literal>, due to the condition <quote>os</quote> being in <varname>OVERRIDES</varname>.</para> 228 </para>
125 </section> 229 <para>
126 230 In this example, <varname>TEST</varname> would be
127 <section id='conditional-appending'> 231 <literal>osspecificvalue</literal>, due to the condition
128 <title>Conditional appending</title> 232 <quote>os</quote> being in <varname>OVERRIDES</varname>.
129 <para>BitBake also supports appending and prepending to variables based on whether something is in OVERRIDES. Example:</para> 233 </para>
130 <para><screen><varname>DEPENDS</varname> = "glibc ncurses" 234 </section>
131<varname>OVERRIDES</varname> = "machine:local"
132<varname>DEPENDS_append_machine</varname> = " libmad"</screen></para>
133 <para>In this example, <varname>DEPENDS</varname> is set to <literal>glibc ncurses libmad</literal>.</para>
134 </section>
135 235
136 <section id='variable-interaction-worked-examples'> 236 <section id='conditional-appending'>
137 <title>Variable interaction: Worked Examples</title> 237 <title>Conditional appending</title>
138 <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. This section documents some common questions people have regarding the way variables interact.</para>
139 238
140 <para>There is often confusion about which order overrides and the various append operators take effect.</para> 239 <para>
240 BitBake also supports appending and prepending to variables based
241 on whether something is in OVERRIDES. Example:
242 </para>
243 <para>
244 <screen><varname>DEPENDS</varname> = "glibc ncurses"
245<varname>OVERRIDES</varname> = "machine:local"
246<varname>DEPENDS_append_machine</varname> = " libmad"</screen>
247 </para>
248 <para>
249 In this example, <varname>DEPENDS</varname> is set to
250 <literal>glibc ncurses libmad</literal>.
251 </para>
252 </section>
141 253
142 <para><screen><varname>OVERRIDES</varname> = "foo" 254 <section id='variable-interaction-worked-examples'>
143<varname>A_foo_append</varname> = "X"</screen></para> 255 <title>Variable interaction: Worked Examples</title>
144 <para>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>
145 256
146 <para><screen><varname>OVERRIDES</varname> = "foo" 257 <para>
258 Despite the documentation of the different forms of
259 variable definition above, it can be hard to work
260 out what happens when variable operators are combined.
261 This section documents some common questions people have
262 regarding the way variables interact.
263 </para>
264
265 <para>
266 There is often confusion about which order overrides and the
267 various append operators take effect.
268 </para>
269
270 <para>
271 <screen><varname>OVERRIDES</varname> = "foo"
272<varname>A_foo_append</varname> = "X"</screen>
273 </para>
274 <para>
275 In this case, X is unconditionally appended
276 to the variable <varname>A_foo</varname>.
277 Since foo is an override, A_foo would then replace
278 <varname>A</varname>.
279 </para>
280 <para>
281 <screen><varname>OVERRIDES</varname> = "foo"
147<varname>A</varname> = "X" 282<varname>A</varname> = "X"
148<varname>A_append_foo</varname> = "Y"</screen></para> 283<varname>A_append_foo</varname> = "Y"</screen></para>
149 <para>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> 284 <para>
150 285 In this case, only when foo is in
151 <para><screen><varname>OVERRIDES</varname> = "foo" 286 OVERRIDES, Y
287 is appended to the variable <varname>A</varname>
288 so the value of <varname>A</varname> would
289 become XY (NB: no spaces are appended).
290 </para>
291 <para>
292 <screen><varname>OVERRIDES</varname> = "foo"
152<varname>A_foo_append</varname> = "X" 293<varname>A_foo_append</varname> = "X"
153<varname>A_foo_append</varname> += "Y"</screen></para> 294<varname>A_foo_append</varname> += "Y"</screen>
154 <para>This behaves as per the first case above, but the value of <varname>A</varname> would be "X Y" instead of just "X".</para> 295 </para>
155 296 <para>
156 <para><screen><varname>A</varname> = "1" 297 This behaves as per the first case above, but the value of
298 <varname>A</varname> would be "X Y" instead of just "X".
299 </para>
300 <para>
301 <screen><varname>A</varname> = "1"
157<varname>A_append</varname> = "2" 302<varname>A_append</varname> = "2"
158<varname>A_append</varname> = "3" 303<varname>A_append</varname> = "3"
159<varname>A</varname> += "4" 304<varname>A</varname> += "4"
160<varname>A</varname> .= "5"</screen></para> 305<varname>A</varname> .= "5"</screen>
161 306 </para>
162 <para>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.</para> 307 <para>
163 308 Would ultimately result in <varname>A</varname> taking the value
164 </section> 309 "1 4523" since the _append operator executes at the
165 <section id='key-expansion'> 310 same time as the expansion of other overrides.
166 <title>Key Expansion</title> 311 </para>
312 </section>
167 313
168 <para>Key expansion happens at the data store finalisation time just before overrides are expanded.</para> 314 <section id='key-expansion'>
315 <title>Key Expansion</title>
169 316
170 <para><screen><varname>A${B}</varname> = "X" 317 <para>
318 Key expansion happens at the data store finalisation
319 time just before overrides are expanded.
320 </para>
321 <para>
322 <screen><varname>A${B}</varname> = "X"
171<varname>B</varname> = "2" 323<varname>B</varname> = "2"
172<varname>A2</varname> = "Y"</screen></para> 324<varname>A2</varname> = "Y"</screen>
173 <para>So in this case <varname>A2</varname> would take the value of "X".</para> 325 </para>
174 </section> 326 <para>
327 So in this case <varname>A2</varname> would take the value of "X".
328 </para>
329 </section>
175 </section> 330 </section>
176 331
177 <section id='inheritance'> 332 <section id='inheritance'>
178 <title>Inheritance</title> 333 <title>Inheritance</title>
179 334
180 <section id='inheritance-directive'> 335 <section id='inheritance-directive'>
181 <title>Inheritance</title> 336 <title>Inheritance</title>
182 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> 337 <para><emphasis>NOTE:</emphasis>
183 <para>The <literal>inherit</literal> directive is a means of specifying what classes of functionality your .bb requires. 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 in <envar>BBPATH</envar>, where filename is what you inherited.</para> 338 This is only supported in .bb and .bbclass files.
184 </section> 339 </para>
185 340 <para>
186 <section id='inclusion-directive'> 341 The <literal>inherit</literal> directive is a means of specifying what classes
187 <title>Inclusion</title> 342 of functionality your .bb requires.
188 <para>Next, there is the <literal>include</literal> directive, which causes BitBake to parse whatever file you specify, and insert it at that location, which is not unlike <command>make</command>. However, if the path specified on the <literal>include</literal> line is a relative path, BitBake will locate the first one it can find within <envar>BBPATH</envar>.</para> 343 It is a rudimentary form of inheritance.
189 </section> 344 For example, you can easily abstract out the tasks involved in
190 <section id='requiring-inclusion'> 345 building a package that uses autoconf and automake, and put
191 <title>Requiring inclusion</title> 346 that into a bbclass for your packages to make use of.
192 <para>In contrast to the <literal>include</literal> directive, <literal>require</literal> will 347 A given bbclass is located by searching for classes/filename.bbclass
193raise an ParseError if the file to be included cannot be found. Otherwise it will behave just like the <literal> 348 in <envar>BBPATH</envar>, where filename is what you inherited.
194include</literal> directive.</para> 349 </para>
195 </section> 350 </section>
351
352 <section id='inclusion-directive'>
353 <title>Inclusion</title>
354
355 <para>
356 Next, there is the <literal>include</literal> directive, which causes BitBake to parse whatever file you specify,
357 and insert it at that location, which is not unlike <command>make</command>.
358 However, if the path specified on the <literal>include</literal> line is a
359 relative path, BitBake will locate the first one it can find
360 within <envar>BBPATH</envar>.
361 </para>
362 </section>
363
364 <section id='requiring-inclusion'>
365 <title>Requiring inclusion</title>
366 <para>
367 In contrast to the <literal>include</literal> directive, <literal>require</literal> will
368raise an
369 ParseError if the file to be included cannot
370 be found.
371 Otherwise it will behave just like the <literal>include</literal> directive.
372 </para>
373 </section>
196 374
197 </section> 375 </section>
198 376
199 <section id='defining-python-functions-into-the-global-python-namespace'> 377 <section id='defining-python-functions-into-the-global-python-namespace'>
200 <title>Defining Python functions into the global Python namespace</title> 378 <title>Defining Python functions into the global Python namespace</title>
201 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> 379
202 <para><screen>def get_depends(bb, d): 380 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files
381 </para>
382 <para>
383 <screen>def get_depends(bb, d):
203 if d.getVar('SOMECONDITION', True): 384 if d.getVar('SOMECONDITION', True):
204 return "dependencywithcond" 385 return "dependencywithcond"
205 else: 386 else:
206 return "dependency" 387 return "dependency"
207 388
208<varname>SOMECONDITION</varname> = "1" 389<varname>SOMECONDITION</varname> = "1"
209<varname>DEPENDS</varname> = "${@get_depends(bb, d)}"</screen></para> 390<varname>DEPENDS</varname> = "${@get_depends(bb, d)}"</screen>
210 <para>This would result in <varname>DEPENDS</varname> containing <literal>dependencywithcond</literal>.</para> 391 </para>
211 </section> 392 <para>
212 393 This would result in <varname>DEPENDS</varname> containing <literal>dependencywithcond</literal>.
213 <section> 394 </para>
214 <title>Defining executable metadata</title> 395 </section>
215 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> 396
216 <para><screen>do_mytask () { 397 <section>
398 <title>Defining executable metadata</title>
399 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.
400 </para>
401 <para>
402 <screen>do_mytask () {
217 echo "Hello, world!" 403 echo "Hello, world!"
218}</screen></para> 404}</screen>
219 <para>This is essentially identical to setting a variable, except that this variable happens to be executable shell code.</para> 405 </para>
220 <para><screen>python do_printdate () { 406 <para>
407 This is essentially identical to setting a variable, except that this variable happens to be executable shell code.
408 </para>
409 <para>
410 <screen>python do_printdate () {
221 import time 411 import time
222 print time.strftime('%Y%m%d', time.gmtime()) 412 print time.strftime('%Y%m%d', time.gmtime())
223}</screen></para> 413}</screen>
224 <para>This is the similar to the previous, but flags it as Python so that BitBake knows it is Python code.</para> 414 </para>
225 </section> 415 <para>
226 416 This is the similar to the previous, but flags it as Python so that BitBake knows it is Python code.
227 <section> 417 </para>
228 <title>Tasks</title> 418 </section>
229 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> 419
230 <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> 420 <section>
231 <para><screen>python do_printdate () { 421 <title>Tasks</title>
422 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para>
423 <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.
424 </para>
425 <para>
426 <screen>python do_printdate () {
232 import time 427 import time
233 print time.strftime('%Y%m%d', time.gmtime()) 428 print time.strftime('%Y%m%d', time.gmtime())
234} 429}
235 430
236addtask printdate before do_build</screen></para> 431addtask printdate before do_build</screen>
237 <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.</para> 432 </para>
238 </section> 433 <para>
434 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.
435 </para>
436 </section>
437
438 <section id='task-flags'>
439 <title>Task Flags</title>
239 440
240 <section id='task-flags'> 441 <para>
241 <title>Task Flags</title> 442 Tasks support a number of flags which control various
242 <para>Tasks support a number of flags which control various functionality of the task. These are as follows:</para> 443 functionality of the task. These are as follows:
444 </para>
243 <para>'dirs' - directories which should be created before the task runs</para> 445 <para>'dirs' - directories which should be created before the task runs</para>
244 <para>'cleandirs' - directories which should be created before the task runs but should be empty</para> 446 <para>'cleandirs' - directories which should be created before the task runs but should be empty</para>
245 <para>'noexec' - 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> 447 <para>'noexec' - 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>
@@ -247,32 +449,89 @@ addtask printdate before do_build</screen></para>
247 <para>'fakeroot' - this task needs to be run in a fakeroot environment, obtained by adding the variables in FAKEROOTENV to the environment.</para> 449 <para>'fakeroot' - this task needs to be run in a fakeroot environment, obtained by adding the variables in FAKEROOTENV to the environment.</para>
248 <para>'umask' - the umask to run the task under.</para> 450 <para>'umask' - the umask to run the task under.</para>
249 <para> For the 'deptask', 'rdeptask', 'depends', 'rdepends' and 'recrdeptask' flags please see the dependencies section.</para> 451 <para> For the 'deptask', 'rdeptask', 'depends', 'rdepends' and 'recrdeptask' flags please see the dependencies section.</para>
250 </section> 452 </section>
251 453
252 <section id='parsing-overview'> 454 <section id='parsing-overview'>
253 <title>Parsing</title> 455 <title>Parsing</title>
254 <section id='configiguration-files'> 456 <section id='configiguration-files'>
255 <title>Configuration files</title> 457 <title>Configuration files</title>
256 <para>The first kind of metadata in BitBake is configuration metadata. This metadata is global, and therefore affects <emphasis>all</emphasis> packages and tasks which are executed.</para> 458 <para>
257 <para>BitBake will first search the current working directory for an optional "conf/bblayers.conf" configuration file. This file is expected to contain a BBLAYERS variable which is a space delimited list of 'layer' directories. For each directory in this list, a "conf/layer.conf" file will be searched for and parsed with the LAYERDIR variable being set to the directory where the layer was found. The idea is these files will setup BBPATH and other variables correctly for a given build directory automatically for the user.</para> 459 The first kind of metadata in BitBake is configuration metadata.
258 <para>BitBake will then expect to find 'conf/bitbake.conf' somewhere in the user specified <envar>BBPATH</envar>. That configuration file generally has include directives to pull in any other metadata (generally files specific to architecture, machine, <emphasis>local</emphasis> and so on).</para> 460 This metadata is global, and therefore affects <emphasis>all</emphasis> packages and
259 <para>Only variable definitions and include directives are allowed in .conf files.</para> 461 tasks which are executed.
260 </section> 462 </para>
261 <section id='classes'> 463
262 <title>Classes</title> 464 <para>
263 <para>BitBake classes are our rudimentary inheritance mechanism. As briefly mentioned in the metadata introduction, they're parsed when an <literal>inherit</literal> directive is encountered, and they are located in classes/ relative to the directories in <envar>BBPATH</envar>.</para> 465 BitBake will first search the current working directory for an
264 </section> 466 optional "conf/bblayers.conf" configuration file.
265 <section id='bb-files'> 467 This file is expected to contain a BBLAYERS
266 <title>.bb files</title> 468 variable which is a space delimited list of 'layer' directories.
267 <para>A BitBake (.bb) file is a logical unit of tasks to be executed. Normally this is a package to be built. Inter-.bb dependencies are obeyed. The files themselves are located via the <varname>BBFILES</varname> variable, which is set to a space separated list of .bb files, and does handle wildcards.</para> 469 For each directory in this list, a "conf/layer.conf"
268 </section> 470 file will be searched for and parsed with the
471 LAYERDIR variable being set to the directory where
472 the layer was found.
473 The idea is these files will setup BBPATH
474 and other variables correctly for a given build directory automatically
475 for the user.
476 </para>
477
478 <para>
479 BitBake will then expect to find 'conf/bitbake.conf'
480 somewhere in the user specified <envar>BBPATH</envar>.
481 That configuration file generally has include directives to pull
482 in any other metadata (generally files specific to architecture,
483 machine, <emphasis>local</emphasis> and so on).
484 </para>
485
486 <para>
487 Only variable definitions and include directives are allowed in .conf files.
488 </para>
489 </section>
490 <section id='classes'>
491 <title>Classes</title>
492 <para>
493 BitBake classes are our rudimentary inheritance mechanism.
494 As briefly mentioned in the metadata introduction, they're
495 parsed when an <literal>inherit</literal> directive is encountered, and they
496 are located in classes/
497 relative to the directories in <envar>BBPATH</envar>.
498 </para>
269 </section> 499 </section>
270 500
271 <section id='events'> 501 <section id='bb-files'>
272 <title>Events</title> 502 <title>.bb files</title>
273 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> 503
274 <para>BitBake allows installation of event handlers. Events are triggered at certain points during operation, such as the beginning of operation against a given .bb, the start of a given task, task failure, task success, et cetera. The intent is to make it easy to do things like email notification on build failure.</para> 504 <para>
275 <para><screen>addhandler myclass_eventhandler 505 BitBake (.bb) file is a logical unit
506 of tasks to be executed.
507 Normally this is a package to be built.
508 Inter-.bb dependencies are obeyed.
509 The files themselves are located via
510 the <varname>BBFILES</varname> variable, which
511 is set to a space separated list of .bb
512 files, and does handle wildcards.
513 </para>
514 </section>
515 </section>
516
517 <section id='events'>
518 <title>Events</title>
519
520 <para>
521 <emphasis>NOTE:</emphasis>
522 This is only supported in .bb and .bbclass files.
523 </para>
524 <para>
525 BitBake allows installation of event handlers.
526 Events are triggered at certain points during operation,
527 such as the beginning of operation against a given
528 .bb, the start of a given task,
529 task failure, task success, et cetera.
530 The intent is to make it easy to do things like email
531 notification on build failure.
532 </para>
533 <para>
534 <screen>addhandler myclass_eventhandler
276python myclass_eventhandler() { 535python myclass_eventhandler() {
277 from bb.event import getName 536 from bb.event import getName
278 from bb import data 537 from bb import data
@@ -280,61 +539,176 @@ python myclass_eventhandler() {
280 print("The name of the Event is %s" % getName(e)) 539 print("The name of the Event is %s" % getName(e))
281 print("The file we run for is %s" % data.getVar('FILE', e.data, True)) 540 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
282} 541}
283</screen></para><para> 542</screen>
284This event handler gets called every time an event is triggered. A global variable <varname>e</varname> is defined. <varname>e</varname>.data contains an instance of bb.data. With the getName(<varname>e</varname>) 543 </para>
285method one can get the name of the triggered event.</para><para>The above event handler prints the name 544 <para>
286of the event and the content of the <varname>FILE</varname> variable.</para> 545 This event handler gets called every time an event is
287 </section> 546 triggered.
288 547 A global variable <varname>e</varname> is defined.
289 <section id='variants-class-extension-mechanism'> 548 <varname>e</varname>.data contains an instance of
290 <title>Variants</title> 549 bb.data.
291 <para>Two BitBake features exist to facilitate the creation of multiple buildable incarnations from a single recipe file.</para> 550 With the getName(<varname>e</varname>) method one can get
292 <para>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> results in a second incarnation of the current recipe being available. This second incarnation will have the "native" class inherited.</para> 551 the name of the triggered event.
293 <para>The second feature is <varname>BBVERSIONS</varname>. This variable allows a single recipe to build multiple versions of a 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> 552 </para>
294 <para><screen>BBVERSIONS = "1.0 2.0 git" 553
295SRC_URI_git = "git://someurl/somepath.git"</screen></para> 554 <para>
296 <para><screen>BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 555 The above event handler prints the name of the event
556 and the content of the <varname>FILE</varname> variable.
557 </para>
558 </section>
559
560 <section id='variants-class-extension-mechanism'>
561 <title>Variants</title>
562
563 <para>
564 Two BitBake features exist to facilitate the creation of
565 multiple buildable incarnations from a single recipe file.
566 </para>
567
568 <para>
569 The first is <varname>BBCLASSEXTEND</varname>.
570 This variable is a space separated list of classes used to "extend" the
571 recipe for each variant.
572 As an example, setting <screen>BBCLASSEXTEND = "native"</screen>
573 results in a second incarnation of the current
574 recipe being available.
575 This second incarnation will have the "native" class inherited.
576 </para>
577 <para>
578 The second feature is <varname>BBVERSIONS</varname>.
579 This variable allows a single recipe to build multiple versions of a
580 project from a single recipe file, and allows you to specify
581 conditional metadata (using the <varname>OVERRIDES</varname>
582 mechanism) for a single version, or an optionally named range of versions:
583 </para>
584 <para>
585 <screen>BBVERSIONS = "1.0 2.0 git"
586SRC_URI_git = "git://someurl/somepath.git"</screen>
587 </para>
588 <para>
589 <screen>BBVERSIONS = "1.0.[0-6]:1.0.0+ \
297 1.0.[7-9]:1.0.7+" 590 1.0.[7-9]:1.0.7+"
298SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"</screen></para> 591SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"</screen>
299 <para>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+. 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 <varname>BPV</varname> variable, for use in file:// search paths (<varname>FILESPATH</varname>).</para> 592 </para>
300 </section> 593 <para>
301 594 Note that the name of the range will default to the original version of the
302 <section id='dependencies'> 595 recipe, so given OE, a recipe file of foo_1.0.0+.bb
303 <title>Dependency handling</title> 596 will default the name of its versions to 1.0.0+.
304 <para>BitBake handles dependencies at the task level since to allow for efficient operation with multiple processed executing in parallel. A robust method of specifying task dependencies is therefore needed. </para> 597 This is useful, as the range name is not only placed into overrides;
305 <section id='dependencies-internal-to-the-bb-file'> 598 it's also made available for the metadata to use in the form of the
306 <title>Dependencies internal to the .bb file</title> 599 <varname>BPV</varname> variable, for use in
307 <para>Where the dependencies are internal to a given .bb file, the dependencies are handled by the previously detailed addtask directive.</para> 600 file:// search paths (<varname>FILESPATH</varname>).
308 </section> 601 </para>
309 602 </section>
310 <section id='build-dependencies'> 603
311 <title>Build Dependencies</title> 604 <section id='dependencies'>
312 <para>DEPENDS lists build time dependencies. 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> 605 <title>Dependency handling</title>
313 <para><screen>do_configure[deptask] = "do_populate_staging"</screen></para> 606
314 <para>means the do_populate_staging task of each item in DEPENDS must have completed before do_configure can execute.</para> 607 <para>
315 </section> 608 BitBake handles dependencies at the task level since to
316 609 allow for efficient operation with multiple
317 <section id='runtime-dependencies'> 610 processed executing in parallel. A robust method of
318 <title>Runtime Dependencies</title> 611 specifying task dependencies is therefore needed.
319 <para>The PACKAGES variable lists runtime packages and each of these can have RDEPENDS and RRECOMMENDS runtime dependencies. 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> 612 </para>
320 <para><screen>do_package_write[rdeptask] = "do_package"</screen></para> 613
321 <para>means the do_package task of each item in RDEPENDS must have completed before do_package_write can execute.</para> 614 <section id='dependencies-internal-to-the-bb-file'>
322 </section> 615 <title>Dependencies internal to the .bb file</title>
323 616
324 <section id='recursive-dependencies'> 617 <para>
325 <title>Recursive Dependencies</title> 618 Where the dependencies are internal to a given
326 <para>These are specified with the 'recrdeptask' flag which is used signify the task(s) of dependencies 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> 619 .bb file, the dependencies are handled by the
327 <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 be referenced in the task list, e.g. do_a[recrdeptask] = "do_a do_b".</para> 620 previously detailed addtask directive.
328 </section> 621 </para>
329
330 <section id='inter-task-dependencies'>
331 <title>Inter task</title>
332 <para>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>
333 <para><screen>do_patch[depends] = "quilt-native:do_populate_staging"</screen></para>
334 <para>means the do_populate_staging task of the target quilt-native must have completed before the do_patch can execute.</para>
335 <para>The 'rdepends' flag works in a similar way but takes targets in the runtime namespace instead of the build time dependency namespace.</para>
336 </section>
337 </section> 622 </section>
338 623
624 <section id='build-dependencies'>
625 <title>Build Dependencies</title>
626
627 <para>
628 DEPENDS lists build time dependencies.
629 The 'deptask' flag for tasks is used to signify the task of each
630 item listed in DEPENDS which must have
631 completed before that task can be executed.
632 </para>
633 <para>
634 <screen>do_configure[deptask] = "do_populate_staging"</screen>
635 </para>
636 <para>
637 means the do_populate_staging
638 task of each item in DEPENDS must have completed before
639 do_configure can execute.
640 </para>
641 </section>
642
643 <section id='runtime-dependencies'>
644 <title>Runtime Dependencies</title>
645
646 <para>
647 The PACKAGES variable lists runtime
648 packages and each of these can have RDEPENDS and
649 RRECOMMENDS runtime dependencies.
650 The 'rdeptask' flag for tasks is used to signify the task of each
651 item runtime dependency which must have completed before that
652 task can be executed.
653 </para>
654 <para>
655 <screen>do_package_write[rdeptask] = "do_package"</screen>
656 </para>
657 <para>
658 means the do_package
659 task of each item in RDEPENDS must have
660 completed before do_package_write can execute.
661 </para>
662 </section>
339 663
340 </chapter> 664 <section id='recursive-dependencies'>
665 <title>Recursive Dependencies</title>
666
667 <para>
668 These are specified with the 'recrdeptask' flag
669 which is used signify the task(s) of dependencies
670 which must have completed before that task can be
671 executed.
672 It works by looking though the build
673 and runtime dependencies of the current recipe as well
674 as any inter-task dependencies the task has,
675 then adding a dependency on the listed task.
676 It will then recurse through the dependencies of those
677 tasks and so on.
678 </para>
679
680 <para>
681 It may be desireable to recurse not just through the
682 dependencies of those tasks but through the
683 build and runtime dependencies of dependent tasks too.
684 If that is the case, the taskname itself should
685 be referenced in the task list, e.g.
686 do_a[recrdeptask] = "do_a do_b".
687 </para>
688 </section>
689
690 <section id='inter-task-dependencies'>
691 <title>Inter task</title>
692
693 <para>
694 The 'depends' flag for tasks is a more generic form of which
695 allows an interdependency on specific tasks rather than specifying
696 the data in DEPENDS.
697 </para>
698 <para>
699 <screen>do_patch[depends] = "quilt-native:do_populate_staging"</screen>
700 </para>
701 <para>
702 means the do_populate_staging
703 task of the target quilt-native must have completed before the
704 do_patch can execute.
705 </para>
706
707 <para>
708 The 'rdepends' flag works in a similar way but takes targets
709 in the runtime namespace instead of the build time dependency
710 namespace.
711 </para>
712 </section>
713 </section>
714</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-22 10:32:04 +0000