summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-18 14:02:18 +0000
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-27 21:03:20 +0000
commitc8892fc919c4f358371dc4e74a329f32836bea0c (patch)
treeb619cd89ef82a52e7708204d20504fe51a430a24 /bitbake/doc
parent98b41e41ff7f218e36bc1027a4738ab20021e57c (diff)
downloadpoky-c8892fc919c4f358371dc4e74a329f32836bea0c.tar.gz
bitbake: user-manual-metadata: Editing pass over the manual chapter
(Bitbake rev: 6f326f2f2785d6d48d7753abee6e8162852d8702) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml242
1 files changed, 137 insertions, 105 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 5e4551bb6b..c6b9005cd7 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -5,21 +5,27 @@
5 <title>Metadata</title> 5 <title>Metadata</title>
6 6
7 <section> 7 <section>
8 <title>Description</title> 8 <title>Overview</title>
9
10 <para>
11 The BitBake task executor together with various types of configuration files form the OpenEmbedded
12 Core.
13 This section provides an overview of the BitBake task executor and the configuration files by
14 describing what they are used for and how they interact.
15 </para>
16
17 <para>
18 BitBake handles the parsing and execution of the data files. The data itself is of various types:
9 <itemizedlist> 19 <itemizedlist>
10 <para>BitBake metadata can be classified into 3 major areas:</para> 20 <listitem><para><emphasis>Recipes:</emphasis>
11 <listitem> 21 Provides details about particular pieces of software.</para></listitem>
12 <para>Configuration Files</para> 22 <listitem><para><emphasis>Class Data:</emphasis>
13 </listitem> 23 An abstraction of common build information (e.g. how to build a Linux kernel).</para></listitem>
14 <listitem> 24 <listitem><para><emphasis>Configuration Data:</emphasis>
15 <para>.bb Files</para> 25 Defines machine-specific settings, policy decisions, etc. Configuration data acts
16 </listitem> 26 as the glue to bind everything together.</para></listitem>
17 <listitem>
18 <para>Classes</para>
19 </listitem>
20 </itemizedlist> 27 </itemizedlist>
21 <para> 28 What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported
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. 29 in any of the aforementioned areas will be documented as such.
24 </para> 30 </para>
25 </section> 31 </section>
@@ -28,7 +34,7 @@
28 <title>Basic Syntax</title> 34 <title>Basic Syntax</title>
29 35
30 <section id='basic-variable-setting'> 36 <section id='basic-variable-setting'>
31 <title>Basic variable setting</title> 37 <title>Basic Variable Setting</title>
32 38
33 <para> 39 <para>
34 <literallayout class='monospaced'> 40 <literallayout class='monospaced'>
@@ -39,7 +45,7 @@
39 </section> 45 </section>
40 46
41 <section id='variable-expansion'> 47 <section id='variable-expansion'>
42 <title>Variable expansion</title> 48 <title>Variable Expansion</title>
43 49
44 <para> 50 <para>
45 BitBake supports variables referencing one another's 51 BitBake supports variables referencing one another's
@@ -69,8 +75,10 @@
69 it will retain its previous value. 75 it will retain its previous value.
70 If <filename>A</filename> is unset prior to the above call, 76 If <filename>A</filename> is unset prior to the above call,
71 <filename>A</filename> will be set to <filename>aval</filename>. 77 <filename>A</filename> will be set to <filename>aval</filename>.
72 Note that this assignment is immediate, so if there are multiple ?= assignments 78 <note>
79 This assignment is immediate, so if there are multiple "?=" assignments
73 to a single variable, the first of those will be used. 80 to a single variable, the first of those will be used.
81 </note>
74 </para> 82 </para>
75 </section> 83 </section>
76 84
@@ -86,11 +94,11 @@
86 it will retain that value. 94 it will retain that value.
87 If <filename>A</filename> is unset prior to the above, 95 If <filename>A</filename> is unset prior to the above,
88 <filename>A</filename> will be set to <filename>someothervalue</filename>. 96 <filename>A</filename> will be set to <filename>someothervalue</filename>.
89 This is a lazy/weak assignment in that the assignment does not occur until the end 97 This is a lazy or 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, 98 of the parsing process, so that the last, rather than the first,
91 ??= assignment to a given variable will be used. 99 "??=" assignment to a given variable will be used.
92 Any other setting of <filename>A</filename> using = or ?= 100 Any other setting of <filename>A</filename> using "=" or "?="
93 will however override the value set with ??= 101 will, however, override the value set with "??=".
94 </para> 102 </para>
95 </section> 103 </section>
96 104
@@ -98,8 +106,9 @@
98 <title>Immediate variable expansion (:=)</title> 106 <title>Immediate variable expansion (:=)</title>
99 107
100 <para> 108 <para>
101 := results in a variable's contents being expanded immediately, rather than when the variable is actually used. 109 The ":=" operator results in a variable's contents being expanded immediately,
102 <literallayout class='monospaced'> 110 rather than when the variable is actually used:
111 <literallayout class='monospaced'>
103 T = "123" 112 T = "123"
104 A := "${B} ${A} test ${T}" 113 A := "${B} ${A} test ${T}"
105 T = "456" 114 T = "456"
@@ -107,7 +116,7 @@
107 C = "cval" 116 C = "cval"
108 C := "${C}append" 117 C := "${C}append"
109 </literallayout> 118 </literallayout>
110 In that example, <filename>A</filename> would contain 119 In this example, <filename>A</filename> would contain
111 <filename>test 123</filename>, <filename>B</filename> would contain 120 <filename>test 123</filename>, <filename>B</filename> would contain
112 <filename>456 bval</filename>, and <filename>C</filename> 121 <filename>456 bval</filename>, and <filename>C</filename>
113 would be <filename>cvalappend</filename>. 122 would be <filename>cvalappend</filename>.
@@ -131,7 +140,7 @@
131 </section> 140 </section>
132 141
133 <section id='appending-and-prepending-without-spaces'> 142 <section id='appending-and-prepending-without-spaces'>
134 <title>Appending (.=) and prepending (=.) without spaces</title> 143 <title>Appending (.=) and Prepending (=.) Without Spaces</title>
135 144
136 <para> 145 <para>
137 <literallayout class='monospaced'> 146 <literallayout class='monospaced'>
@@ -149,7 +158,7 @@
149 </section> 158 </section>
150 159
151 <section id='appending-and-prepending-override-style-syntax'> 160 <section id='appending-and-prepending-override-style-syntax'>
152 <title>Appending and Prepending (override style syntax)</title> 161 <title>Appending and Prepending (Override Style Syntax)</title>
153 162
154 <para> 163 <para>
155 <literallayout class='monospaced'> 164 <literallayout class='monospaced'>
@@ -159,18 +168,20 @@
159 C_prepend = "additional data " 168 C_prepend = "additional data "
160 </literallayout> 169 </literallayout>
161 This example results in <filename>B</filename> 170 This example results in <filename>B</filename>
162 becoming <filename>bval additional data</filename> 171 becoming <filename>bval additional data</filename> and
163 and <filename>C</filename> becoming 172 <filename>C</filename> becoming
164 <filename>additional data cval</filename>. 173 <filename>additional data cval</filename>.
165 Note the spaces in the <filename>_append</filename>. 174 <note>
166 Unlike the += operator, additional space is not automatically added. 175 The spaces in <filename>_append</filename>.
167 You must take steps to add space 176 Unlike the "+=" operator, additional space is not automatically added.
168yourself. 177 You must take steps to add space yourself.
178 </note>
169 </para> 179 </para>
170 </section> 180 </section>
171 181
172 <section id='removing-override-style-syntax'> 182 <section id='removing-override-style-syntax'>
173 <title>Removing (override style syntax)</title> 183 <title>Removing (Override Style Syntax)</title>
184
174 <para> 185 <para>
175 <literallayout class='monospaced'> 186 <literallayout class='monospaced'>
176 FOO = "123 456 789 123456 123 456 123 456" 187 FOO = "123 456 789 123456 123 456 123 456"
@@ -182,7 +193,7 @@ yourself.
182 </section> 193 </section>
183 194
184 <section id='variable-flags'> 195 <section id='variable-flags'>
185 <title>Variable flags</title> 196 <title>Variable Flags</title>
186 197
187 <para> 198 <para>
188 Variables can have associated flags which provide a way of tagging extra information onto a variable. 199 Variables can have associated flags which provide a way of tagging extra information onto a variable.
@@ -192,12 +203,12 @@ yourself.
192 VARIABLE[SOMEFLAG] = "value" 203 VARIABLE[SOMEFLAG] = "value"
193 </literallayout> 204 </literallayout>
194 In this example, <filename>VARIABLE</filename> has a flag, 205 In this example, <filename>VARIABLE</filename> has a flag,
195 <filename>SOMEFLAG</filename> which is set to <filename>value</filename>. 206 <filename>SOMEFLAG</filename> that is set to <filename>value</filename>.
196 </para> 207 </para>
197 </section> 208 </section>
198 209
199 <section id='inline-python-variable-expansion'> 210 <section id='inline-python-variable-expansion'>
200 <title>Python variable expansion</title> 211 <title>Inline Python Variable Expansion</title>
201 212
202 <para> 213 <para>
203 <literallayout class='monospaced'> 214 <literallayout class='monospaced'>
@@ -207,18 +218,22 @@ yourself.
207 variable containing today's date. 218 variable containing today's date.
208 </para> 219 </para>
209 </section> 220 </section>
221 </section>
210 222
211 <section id='conditional-syntax-overrides'> 223 <section id='conditional-syntax-overrides'>
212 <title>Conditional metadata set</title> 224 <title>Conditional Syntax (Overrides)</title>
225
226 <section id='conditional-metadata'>
227 <title>Conditional Metadata</title>
213 228
214 <para> 229 <para>
215 <filename>OVERRIDES</filename> is a <quote>:</quote> separated variable containing 230 <filename>OVERRIDES</filename> is a : separated variable containing
216 each item you want to satisfy conditions. 231 each item for which you want to satisfy conditions.
217 So, if you have a variable which is conditional on <quote>arm</quote>, and <quote>arm</quote> 232 So, if you have a variable that is conditional on arm, and arm
218 is in <filename>OVERRIDES</filename>, then the <quote>arm</quote> specific 233 is in <filename>OVERRIDES</filename>, then the arm specific
219 version of the variable is used rather than the non-conditional 234 version of the variable is used rather than the non-conditional
220 version. 235 version.
221 Example: 236 Here is an example:
222 <literallayout class='monospaced'> 237 <literallayout class='monospaced'>
223 OVERRIDES = "architecture:os:machine" 238 OVERRIDES = "architecture:os:machine"
224 TEST = "defaultvalue" 239 TEST = "defaultvalue"
@@ -227,16 +242,17 @@ yourself.
227 </literallayout> 242 </literallayout>
228 In this example, <filename>TEST</filename> would be 243 In this example, <filename>TEST</filename> would be
229 <filename>osspecificvalue</filename>, due to the condition 244 <filename>osspecificvalue</filename>, due to the condition
230 <quote>os</quote> being in <filename>OVERRIDES</filename>. 245 os being in <filename>OVERRIDES</filename>.
231 </para> 246 </para>
232 </section> 247 </section>
233 248
234 <section id='conditional-appending'> 249 <section id='conditional-appending'>
235 <title>Conditional appending</title> 250 <title>Conditional Appending</title>
236 251
237 <para> 252 <para>
238 BitBake also supports appending and prepending to variables based 253 BitBake also supports appending and prepending to variables based
239 on whether something is in <filename>OVERRIDES</filename>. Example: 254 on whether something is in <filename>OVERRIDES</filename>.
255 Here is an example:
240 <literallayout class='monospaced'> 256 <literallayout class='monospaced'>
241 DEPENDS = "glibc ncurses" 257 DEPENDS = "glibc ncurses"
242 OVERRIDES = "machine:local" 258 OVERRIDES = "machine:local"
@@ -248,22 +264,22 @@ yourself.
248 </section> 264 </section>
249 265
250 <section id='variable-interaction-worked-examples'> 266 <section id='variable-interaction-worked-examples'>
251 <title>Variable interaction: Worked Examples</title> 267 <title>Variable Interaction: Worked Examples</title>
252 268
253 <para> 269 <para>
254 Despite the documentation of the different forms of 270 Despite the documentation of the different forms of
255 variable definition above, it can be hard to work 271 variable definition above, it can be hard to work
256 out what happens when variable operators are combined. 272 out what happens when variable operators are combined.
257 This section documents some common questions people have
258 regarding the way variables interact.
259 </para> 273 </para>
260 274
261 <para> 275 <para>
262 There is often confusion about which order overrides and the 276 Following are some common scenarios where variables interact
263 various append operators take effect. 277 that can confuse users.
264 </para> 278 </para>
265 279
266 <para> 280 <para>
281 There is often confusion about which order overrides and the
282 various "append" operators take effect:
267 <literallayout class='monospaced'> 283 <literallayout class='monospaced'>
268 OVERRIDES = "foo" 284 OVERRIDES = "foo"
269 A_foo_append = "X" 285 A_foo_append = "X"
@@ -297,7 +313,7 @@ yourself.
297 A .= "5" 313 A .= "5"
298 </literallayout> 314 </literallayout>
299 Would ultimately result in <filename>A</filename> taking the value 315 Would ultimately result in <filename>A</filename> taking the value
300 "1 4523" since the _append operator executes at the 316 "1 4523" since the "_append" operator executes at the
301 same time as the expansion of other overrides. 317 same time as the expansion of other overrides.
302 </para> 318 </para>
303 </section> 319 </section>
@@ -306,7 +322,7 @@ yourself.
306 <title>Key Expansion</title> 322 <title>Key Expansion</title>
307 323
308 <para> 324 <para>
309 Key expansion happens at the data store finalisation 325 Key expansion happens at the data store finalization
310 time just before overrides are expanded. 326 time just before overrides are expanded.
311 <literallayout class='monospaced'> 327 <literallayout class='monospaced'>
312 A${B} = "X" 328 A${B} = "X"
@@ -322,10 +338,13 @@ yourself.
322 <title>Inheritance</title> 338 <title>Inheritance</title>
323 339
324 <section id='inheritance-directive'> 340 <section id='inheritance-directive'>
325 <title>Inheritance</title> 341 <title>Inheritance Directive</title>
326 <para><emphasis>NOTE:</emphasis> 342
327 This is only supported in .bb and .bbclass files. 343 <note>
328 </para> 344 This is only supported in <filename>.bb</filename> and
345 <filename>.bbclass</filename> files.
346 </note>
347
329 <para> 348 <para>
330 The inherit directive is a means of specifying what classes 349 The inherit directive is a means of specifying what classes
331 of functionality your <filename>.bb</filename> requires. 350 of functionality your <filename>.bb</filename> requires.
@@ -339,34 +358,42 @@ yourself.
339 </section> 358 </section>
340 359
341 <section id='inclusion-directive'> 360 <section id='inclusion-directive'>
342 <title>Inclusion</title> 361 <title>Inclusion Directive</title>
343 362
344 <para> 363 <para>
345 Next, there is the <filename>include</filename> directive, which causes BitBake to parse whatever file you specify, 364 This directive causes BitBake to parse whatever file you specify,
346 and insert it at that location, which is not unlike <command>make</command>. 365 and insert it at that location, which is not unlike Make.
347 However, if the path specified on the <filename>include</filename> line is a 366 However, if the path specified on the include line is a
348 relative path, BitBake will locate the first one it can find 367 relative path, BitBake will locate the first one it can find
349 within <filename>BBPATH</filename>. 368 within <filename>BBPATH</filename>.
350 </para> 369 </para>
351 </section> 370 </section>
352 371
353 <section id='requiring-inclusion'> 372 <section id='requiring-inclusion'>
354 <title>Requiring inclusion</title> 373 <title>Requiring Inclusion</title>
374
355 <para> 375 <para>
356 In contrast to the <filename>include</filename> directive, <filename>require</filename> will 376 In contrast to the include directive, require will raise a
357raise an
358 ParseError if the file to be included cannot 377 ParseError if the file to be included cannot
359 be found. 378 be found.
360 Otherwise it will behave just like the <filename>include</filename> directive. 379 Otherwise it will behave just like the include directive.
361 </para> 380 </para>
362 </section> 381 </section>
363 382
364 </section> 383 </section>
365 384
366 <section id='defining-python-functions-into-the-global-python-namespace'> 385 <section id='defining-python-functions-into-the-global-python-namespace'>
367 <title>Defining Python functions into the global Python namespace</title> 386 <title>Defining Python Functions into the Global Python Namespace</title>
368 387
369 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files 388 <note>
389 <para>
390 This is only supported in <filename>.bb</filename>
391 and <filename>.bbclass</filename> files.
392 </para>
393
394 <para>
395 Python functions are in the global namespace so should use
396 unique names.
370 <literallayout class='monospaced'> 397 <literallayout class='monospaced'>
371 def get_depends(d): 398 def get_depends(d):
372 if d.getVar('SOMECONDITION', True): 399 if d.getVar('SOMECONDITION', True):
@@ -376,8 +403,10 @@ raise an
376 SOMECONDITION = "1" 403 SOMECONDITION = "1"
377 DEPENDS = "${@get_depends(d)}" 404 DEPENDS = "${@get_depends(d)}"
378 </literallayout> 405 </literallayout>
379 This would result in <filename>DEPENDS</filename> containing <filename>dependencywithcond</filename>. 406 This would result in <filename>DEPENDS</filename>
407 containing <filename>dependencywithcond</filename>.
380 </para> 408 </para>
409 </note>
381 </section> 410 </section>
382 411
383 <section> 412 <section>
@@ -436,15 +465,15 @@ python do_printdate () {
436 <title>Configuration files</title> 465 <title>Configuration files</title>
437 <para> 466 <para>
438 The first kind of metadata in BitBake is configuration metadata. 467 The first kind of metadata in BitBake is configuration metadata.
439 This metadata is global, and therefore affects <emphasis>all</emphasis> packages and 468 This metadata is global, and therefore affects all packages and
440 tasks which are executed. 469 tasks that are executed.
441 </para> 470 </para>
442 471
443 <para> 472 <para>
444 BitBake will first search the current working directory for an 473 BitBake will first search the current working directory for an
445 optional <filename>conf/bblayers.conf</filename> configuration file. 474 optional <filename>conf/bblayers.conf</filename> configuration file.
446 This file is expected to contain a <filename>BBLAYERS</filename> 475 This file is expected to contain a <filename>BBLAYERS</filename>
447 variable which is a space delimited list of 'layer' directories. 476 variable that is a space delimited list of 'layer' directories.
448 For each directory in this list, a <filename>conf/layer.conf</filename> 477 For each directory in this list, a <filename>conf/layer.conf</filename>
449 file will be searched for and parsed with the 478 file will be searched for and parsed with the
450 <filename>LAYERDIR</filename> variable being set to the directory where 479 <filename>LAYERDIR</filename> variable being set to the directory where
@@ -456,10 +485,10 @@ python do_printdate () {
456 485
457 <para> 486 <para>
458 BitBake will then expect to find <filename>conf/bitbake.conf</filename> 487 BitBake will then expect to find <filename>conf/bitbake.conf</filename>
459 somewhere in the user specified <filename>BBPATH</filename>. 488 file somewhere in the user specified <filename>BBPATH</filename>.
460 That configuration file generally has include directives to pull 489 That configuration file generally has include directives to pull
461 in any other metadata (generally files specific to architecture, 490 in any other metadata (generally files specific to architecture,
462 machine, <emphasis>local</emphasis> and so on). 491 machine, local and so on).
463 </para> 492 </para>
464 493
465 <para> 494 <para>
@@ -467,8 +496,10 @@ python do_printdate () {
467 in <filename>.conf</filename> files. 496 in <filename>.conf</filename> files.
468 </para> 497 </para>
469 </section> 498 </section>
499
470 <section id='classes'> 500 <section id='classes'>
471 <title>Classes</title> 501 <title>Classes</title>
502
472 <para> 503 <para>
473 BitBake classes are our rudimentary inheritance mechanism. 504 BitBake classes are our rudimentary inheritance mechanism.
474 As briefly mentioned in the metadata introduction, they're 505 As briefly mentioned in the metadata introduction, they're
@@ -479,15 +510,15 @@ python do_printdate () {
479 </section> 510 </section>
480 511
481 <section id='bb-files'> 512 <section id='bb-files'>
482 <title>.<filename>.bb</filename> files</title> 513 <title><filename>.bb</filename> Files</title>
483 514
484 <para> 515 <para>
485 BitBake (<filename>.bb</filename>) file is a logical unit 516 A BitBake (<filename>.bb</filename>) file is a logical unit
486 of tasks to be executed. 517 of tasks to be executed.
487 Normally this is a package to be built. 518 Normally this is a package to be built.
488 Inter-<filename>.bb</filename> dependencies are obeyed. 519 Inter-<filename>.bb</filename> dependencies are obeyed.
489 The files themselves are located via 520 The files themselves are located via the
490 the <filename>BBFILES</filename> variable, which 521 <filename>BBFILES</filename> variable, which
491 is set to a space separated list of <filename>.bb</filename> 522 is set to a space separated list of <filename>.bb</filename>
492 files, and does handle wildcards. 523 files, and does handle wildcards.
493 </para> 524 </para>
@@ -497,17 +528,17 @@ python do_printdate () {
497 <section id='events'> 528 <section id='events'>
498 <title>Events</title> 529 <title>Events</title>
499 530
500 <para> 531 <note>
501 <emphasis>NOTE:</emphasis> 532 This is only supported in <filename>.bb</filename>
502 This is only supported in <filename>.bb</filename>
503 and <filename>.bbclass</filename> files. 533 and <filename>.bbclass</filename> files.
504 </para> 534 </note>
535
505 <para> 536 <para>
506 BitBake allows installation of event handlers. 537 BitBake allows installation of event handlers.
507 Events are triggered at certain points during operation, 538 Events are triggered at certain points during operation,
508 such as the beginning of operation against a given 539 such as the beginning of operation against a given
509 <filename>.bb</filename>, the start of a given task, 540 <filename>.bb</filename>, the start of a given task,
510 task failure, task success, et cetera. 541 task failure, task success, and so forth.
511 The intent is to make it easy to do things like email 542 The intent is to make it easy to do things like email
512 notification on build failure. 543 notification on build failure.
513 <literallayout class='monospaced'> 544 <literallayout class='monospaced'>
@@ -521,9 +552,9 @@ python do_printdate () {
521 </literallayout> 552 </literallayout>
522 This event handler gets called every time an event is 553 This event handler gets called every time an event is
523 triggered. 554 triggered.
524 A global variable <filename>e</filename> is defined. 555 A global variable "<filename>e</filename>" is defined.
525 <filename>e.data</filename> contains an instance of 556 "<filename>e.data</filename>" contains an instance of
526 <filename>bb.data</filename>. 557 "<filename>bb.data</filename>".
527 With the <filename>getName(e)</filename> method one can get 558 With the <filename>getName(e)</filename> method one can get
528 the name of the triggered event. 559 the name of the triggered event.
529 </para> 560 </para>
@@ -535,7 +566,7 @@ python do_printdate () {
535 </section> 566 </section>
536 567
537 <section id='variants-class-extension-mechanism'> 568 <section id='variants-class-extension-mechanism'>
538 <title>Variants</title> 569 <title>Variants - Class Extension Mechanism</title>
539 570
540 <para> 571 <para>
541 Two BitBake features exist to facilitate the creation of 572 Two BitBake features exist to facilitate the creation of
@@ -546,15 +577,12 @@ python do_printdate () {
546 The first is <filename>BBCLASSEXTEND</filename>. 577 The first is <filename>BBCLASSEXTEND</filename>.
547 This variable is a space separated list of classes used to "extend" the 578 This variable is a space separated list of classes used to "extend" the
548 recipe for each variant. 579 recipe for each variant.
549 As an example, setting 580 Here is an example that results in a second incarnation of the current
581 recipe being available.
582 This second incarnation will have the "native" class inherited.
550 <literallayout class='monospaced'> 583 <literallayout class='monospaced'>
551 BBCLASSEXTEND = "native" 584 BBCLASSEXTEND = "native"
552 </literallayout> 585 </literallayout>
553 results in a second incarnation of the current
554 recipe being available.
555 This second incarnation will have the "native" class inherited.
556 </para>
557 <para>
558 The second feature is <filename>BBVERSIONS</filename>. 586 The second feature is <filename>BBVERSIONS</filename>.
559 This variable allows a single recipe to build multiple versions of a 587 This variable allows a single recipe to build multiple versions of a
560 project from a single recipe file, and allows you to specify 588 project from a single recipe file, and allows you to specify
@@ -568,7 +596,7 @@ python do_printdate () {
568 BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+" 596 BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
569 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1" 597 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
570 </literallayout> 598 </literallayout>
571 Note that the name of the range will default to the original version of the 599 The name of the range will default to the original version of the
572 recipe, so given OE, a recipe file of <filename>foo_1.0.0+.bb</filename> 600 recipe, so given OE, a recipe file of <filename>foo_1.0.0+.bb</filename>
573 will default the name of its versions to <filename>1.0.0+</filename>. 601 will default the name of its versions to <filename>1.0.0+</filename>.
574 This is useful, as the range name is not only placed into overrides; 602 This is useful, as the range name is not only placed into overrides;
@@ -579,17 +607,21 @@ python do_printdate () {
579 </section> 607 </section>
580 608
581 <section id='dependencies'> 609 <section id='dependencies'>
582 <title>Dependency handling</title> 610 <title>Dependencies</title>
611
612 <section id='dependencies-overview'>
613 <title>Overview</title>
583 614
584 <para> 615 <para>
585 BitBake handles dependencies at the task level since to 616 BitBake handles dependencies at the task level since to
586 allow for efficient operation with multiple 617 allow for efficient operation with multiple
587 processed executing in parallel. A robust method of 618 processes executing in parallel, a robust method of
588 specifying task dependencies is therefore needed. 619 specifying task dependencies is needed.
589 </para> 620 </para>
621 </section>
590 622
591 <section id='dependencies-internal-to-the-bb-file'> 623 <section id='dependencies-internal-to-the-bb-file'>
592 <title>Dependencies internal to the <filename>.bb</filename> file</title> 624 <title>Dependencies Internal to the <filename>.bb</filename> File</title>
593 625
594 <para> 626 <para>
595 Where the dependencies are internal to a given 627 Where the dependencies are internal to a given
@@ -609,7 +641,7 @@ python do_printdate () {
609 <literallayout class='monospaced'> 641 <literallayout class='monospaced'>
610 do_configure[deptask] = "do_populate_staging" 642 do_configure[deptask] = "do_populate_staging"
611 </literallayout> 643 </literallayout>
612 means the <filename>do_populate_staging</filename> 644 In the previous example, the <filename>do_populate_staging</filename>
613 task of each item in <filename>DEPENDS</filename> must have completed before 645 task of each item in <filename>DEPENDS</filename> must have completed before
614 <filename>do_configure</filename> can execute. 646 <filename>do_configure</filename> can execute.
615 </para> 647 </para>
@@ -628,7 +660,7 @@ python do_printdate () {
628 <literallayout class='monospaced'> 660 <literallayout class='monospaced'>
629 do_package_write[rdeptask] = "do_package" 661 do_package_write[rdeptask] = "do_package"
630 </literallayout> 662 </literallayout>
631 means the <filename>do_package</filename> 663 In the previous example, the <filename>do_package</filename>
632 task of each item in <filename>RDEPENDS</filename> must have 664 task of each item in <filename>RDEPENDS</filename> must have
633 completed before <filename>do_package_write</filename> can execute. 665 completed before <filename>do_package_write</filename> can execute.
634 </para> 666 </para>
@@ -639,7 +671,7 @@ python do_printdate () {
639 671
640 <para> 672 <para>
641 These are specified with the 'recrdeptask' flag 673 These are specified with the 'recrdeptask' flag
642 which is used signify the task(s) of dependencies 674 which is used to signify the task(s) of dependencies
643 which must have completed before that task can be 675 which must have completed before that task can be
644 executed. 676 executed.
645 It works by looking though the build 677 It works by looking though the build
@@ -655,29 +687,29 @@ python do_printdate () {
655 dependencies of those tasks but through the 687 dependencies of those tasks but through the
656 build and runtime dependencies of dependent tasks too. 688 build and runtime dependencies of dependent tasks too.
657 If that is the case, the taskname itself should 689 If that is the case, the taskname itself should
658 be referenced in the task list, e.g. 690 be referenced in the task list (e.g.
659 <filename>do_a[recrdeptask] = "do_a do_b"</filename>. 691 <filename>do_a[recrdeptask] = "do_a do_b"</filename>).
660 </para> 692 </para>
661 </section> 693 </section>
662 694
663 <section id='inter-task-dependencies'> 695 <section id='inter-task-dependencies'>
664 <title>Inter task</title> 696 <title>Inter-Task Dependencies</title>
665 697
666 <para> 698 <para>
667 The 'depends' flag for tasks is a more generic form of which 699 The 'depends' flag for tasks is a more generic form which
668 allows an interdependency on specific tasks rather than specifying 700 allows an inter-dependency on specific tasks rather than specifying
669 the data in <filename>DEPENDS</filename>. 701 the data in <filename>DEPENDS</filename>.
670 <literallayout class='monospaced'> 702 <literallayout class='monospaced'>
671 do_patch[depends] = "quilt-native:do_populate_staging" 703 do_patch[depends] = "quilt-native:do_populate_staging"
672 </literallayout> 704 </literallayout>
673 means the <filename>do_populate_staging</filename> 705 In the previous example, the <filename>do_populate_staging</filename>
674 task of the target quilt-native must have completed before the 706 task of the target quilt-native must have completed before the
675 <filename>do_patch</filename> task can execute. 707 <filename>do_patch</filename> task can execute.
676 </para> 708 </para>
677 709
678 <para> 710 <para>
679 The 'rdepends' flag works in a similar way but takes targets 711 The 'rdepends' flag works in a similar way but takes targets
680 in the runtime namespace instead of the build time dependency 712 in the runtime namespace instead of the build-time dependency
681 namespace. 713 namespace.
682 </para> 714 </para>
683 </section> 715 </section>