summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-03-06 09:48:37 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-03-09 18:59:04 -0700
commit40ab94036081f9fdc4ebf6126b077149c2a97c31 (patch)
tree65075fcb43ab2e731a9891063878d13addf0737e /bitbake/doc
parent96294ee40748dd96da7203cedf93a42e34b2a468 (diff)
downloadpoky-40ab94036081f9fdc4ebf6126b077149c2a97c31.tar.gz
bitbake: user-manual: Review edits applied from Paul Eggleton.
Review of the entire manual by Paul. I have implemented his suggestions throughout. (Bitbake rev: 5cd310d1df194cd171691a4bcfb98024e2bc66b8) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/user-manual/user-manual-execution.xml62
-rw-r--r--bitbake/doc/user-manual/user-manual-fetching.xml11
-rw-r--r--bitbake/doc/user-manual/user-manual-intro.xml81
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml87
4 files changed, 115 insertions, 126 deletions
diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml
index d451ebb533..6110a93e2a 100644
--- a/bitbake/doc/user-manual/user-manual-execution.xml
+++ b/bitbake/doc/user-manual/user-manual-execution.xml
@@ -87,21 +87,6 @@
87 just constructed. 87 just constructed.
88 The <filename>bitbake.conf</filename> file usually indicates 88 The <filename>bitbake.conf</filename> file usually indicates
89 all the other key include files to parse. 89 all the other key include files to parse.
90 The usual convention is to have machine, distro, site, and local
91 configurations.
92 This means a user provides their own customizations
93 through a <filename>local.conf</filename> file.
94 </para>
95
96 <para>
97 As mentioned in the previous paragraph, two of the other notable
98 configuration files are the distro and machine configuration
99 files.
100 These configuration files are normally identified by
101 variables unique to the build systems using BitBake.
102 For example, the Yocto Project uses the
103 <filename>DISTRO</filename> and <filename>MACHINE</filename>
104 variables, respectively.
105 </para> 90 </para>
106 91
107 <para> 92 <para>
@@ -122,7 +107,7 @@
122 107
123 <para> 108 <para>
124 The base configuration metadata is global 109 The base configuration metadata is global
125 and therefore affects all packages and tasks that are executed. 110 and therefore affects all recipes and tasks that are executed.
126 </para> 111 </para>
127 112
128 <para> 113 <para>
@@ -161,10 +146,11 @@
161 These variables might have been set from the environment 146 These variables might have been set from the environment
162 depending on the environment variables previously 147 depending on the environment variables previously
163 mentioned or set in the configuration files. 148 mentioned or set in the configuration files.
164 See the 149 The
165 "<link linkend='ref-variables-glos'>Variables Glossary</link>" 150 "<link linkend='ref-variables-glos'>Variables Glossary</link>"
166 for a full list of variables. 151 chapter presents a full list of variables.
167 The following list shows common variables set: 152<!--
153 Here are some common ones used:
168 <itemizedlist> 154 <itemizedlist>
169 <listitem><para> 155 <listitem><para>
170 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> 156 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
@@ -215,6 +201,7 @@
215 <link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link> 201 <link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link>
216 </para></listitem> 202 </para></listitem>
217 </itemizedlist> 203 </itemizedlist>
204-->
218 </para> 205 </para>
219 206
220 <para> 207 <para>
@@ -305,7 +292,7 @@
305 </para> 292 </para>
306 293
307 <para> 294 <para>
308 BitBake does not need all this information. 295 BitBake does not need all of this information.
309 It only needs a small subset of the information to make 296 It only needs a small subset of the information to make
310 decisions about the recipe. 297 decisions about the recipe.
311 Consequently, BitBake caches the values in which it is 298 Consequently, BitBake caches the values in which it is
@@ -375,7 +362,7 @@
375 <literallayout class='monospaced'> 362 <literallayout class='monospaced'>
376 PROVIDES += "virtual/package" 363 PROVIDES += "virtual/package"
377 </literallayout> 364 </literallayout>
378 The recipe now provides both "package1" and "virtual/package. 365 The recipe now provides both "package1" and "virtual/package".
379 The "virtual/" namespace is often used to denote cases where 366 The "virtual/" namespace is often used to denote cases where
380 multiple providers are expected with the user choosing between 367 multiple providers are expected with the user choosing between
381 them. 368 them.
@@ -395,20 +382,8 @@
395 The default 382 The default
396 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link> 383 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
397 is the provider with the same name as the target. 384 is the provider with the same name as the target.
398 </para> 385 Bitbake iterates through each target it needs to build and
399 386 resolves them and their dependencies using this process.
400 <para>
401 Bitbake iterates through each target it needs to build and resolve
402 them using this process.
403 As an example, suppose the target is
404 <filename>core-image-sato</filename>.
405 In this case, it would lead to
406 <filename>packagegroup-core-x11-sato</filename>,
407 which in turn leads to recipes like
408 <filename>matchbox-terminal</filename>, <filename>pcmanfm</filename>
409 and <filename>gthumb</filename>.
410 These recipes in turn depend on <filename>eglibc</filename>
411 and the toolchain.
412 </para> 387 </para>
413 388
414 <para> 389 <para>
@@ -418,21 +393,21 @@
418 Version comparisons are made using the same method as Debian. 393 Version comparisons are made using the same method as Debian.
419 You can use the 394 You can use the
420 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link> 395 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
421 variable to specify a particular version (usually in the distro configuration). 396 variable to specify a particular version.
422 You can influence the order by using the 397 You can influence the order by using the
423 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link> 398 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
424 variable. 399 variable.
425 By default, files have a preference of "0". 400 By default, files have a preference of "0".
426 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the 401 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
427 package unlikely to be used unless it is explicitly referenced. 402 recipe unlikely to be used unless it is explicitly referenced.
428 Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used. 403 Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the recipe is used.
429 <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting. 404 <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
430 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package 405 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental recipe
431 versions until they have undergone sufficient testing to be considered stable. 406 versions until they have undergone sufficient testing to be considered stable.
432 </para> 407 </para>
433 408
434 <para> 409 <para>
435 When there are multiple “versions” of a given package, 410 When there are multiple “versions” of a given recipe,
436 BitBake defaults to selecting the most recent 411 BitBake defaults to selecting the most recent
437 version, unless otherwise specified. 412 version, unless otherwise specified.
438 If the recipe in question has a 413 If the recipe in question has a
@@ -573,12 +548,12 @@
573 <para> 548 <para>
574 Tasks can either be a shell task or a Python task. 549 Tasks can either be a shell task or a Python task.
575 For shell tasks, BitBake writes a shell script to 550 For shell tasks, BitBake writes a shell script to
576 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> 551 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/run.do_taskname.pid</filename>
577 and then executes the script. 552 and then executes the script.
578 The generated shell script contains all the exported variables, 553 The generated shell script contains all the exported variables,
579 and the shell functions with all variables expanded. 554 and the shell functions with all variables expanded.
580 Output from the shell script goes to the file 555 Output from the shell script goes to the file
581 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 556 <filename>${T}/log.do_taskname.pid</filename>.
582 Looking at the expanded shell functions in the run file and 557 Looking at the expanded shell functions in the run file and
583 the output in the log files is a useful debugging technique. 558 the output in the log files is a useful debugging technique.
584 </para> 559 </para>
@@ -831,9 +806,6 @@
831 a setscene task named <filename>xxx_setscene</filename>. 806 a setscene task named <filename>xxx_setscene</filename>.
832 The setscene version of the task executes and provides the necessary 807 The setscene version of the task executes and provides the necessary
833 artifacts returning either success or failure. 808 artifacts returning either success or failure.
834 <note>
835 Artifacts might need to be fetched from the network.
836 </note>
837 </para> 809 </para>
838 810
839 <para> 811 <para>
diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index cbf08d949c..c66596ed6e 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -42,7 +42,7 @@
42 fetcher = bb.fetch2.Fetch(src_uri, d) 42 fetcher = bb.fetch2.Fetch(src_uri, d)
43 fetcher.download() 43 fetcher.download()
44 </literallayout> 44 </literallayout>
45 This code sets up an instance of the fetch module. 45 This code sets up an instance of the fetch class.
46 The instance uses a space-separated list of URLs from the 46 The instance uses a space-separated list of URLs from the
47 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> 47 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
48 variable and then calls the <filename>download</filename> 48 variable and then calls the <filename>download</filename>
@@ -155,14 +155,13 @@
155 <filename>SRC_URI</filename> variable with the appropriate 155 <filename>SRC_URI</filename> variable with the appropriate
156 varflags as follows: 156 varflags as follows:
157 <literallayout class='monospaced'> 157 <literallayout class='monospaced'>
158 SRC_URI[md5sum] 158 SRC_URI[md5sum] = "value"
159 SRC_URI[sha256sum] 159 SRC_URI[sha256sum] = "value"
160 </literallayout> 160 </literallayout>
161 You can also specify the checksums as parameters on the 161 You can also specify the checksums as parameters on the
162 <filename>SRC_URI</filename> as shown below: 162 <filename>SRC_URI</filename> as shown below:
163 <literallayout class='monospaced'> 163 <literallayout class='monospaced'>
164 SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07f 164 SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
165db994d"
166 </literallayout> 165 </literallayout>
167 If multiple URIs exist, you can specify the checksums either 166 If multiple URIs exist, you can specify the checksums either
168 directly as in the previous example, or you can name the URLs. 167 directly as in the previous example, or you can name the URLs.
@@ -578,7 +577,7 @@ db994d"
578 Fetch submodules also exist for the following: 577 Fetch submodules also exist for the following:
579 <itemizedlist> 578 <itemizedlist>
580 <listitem><para> 579 <listitem><para>
581 Bazzar (<filename>bzr://</filename>) 580 Bazaar (<filename>bzr://</filename>)
582 </para></listitem> 581 </para></listitem>
583 <listitem><para> 582 <listitem><para>
584 Perforce (<filename>p4://</filename>) 583 Perforce (<filename>p4://</filename>)
diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml
index 6f9ad2049a..d46e823c72 100644
--- a/bitbake/doc/user-manual/user-manual-intro.xml
+++ b/bitbake/doc/user-manual/user-manual-intro.xml
@@ -6,10 +6,10 @@
6 6
7 <para> 7 <para>
8 Welcome to the BitBake User Manual. 8 Welcome to the BitBake User Manual.
9 This manual provides information on BitBake. 9 This manual provides information on the BitBake tool.
10 The information attempts to be as independent as possible regarding 10 The information attempts to be as independent as possible regarding
11 systems that use BitBake, such as the Yocto Project and 11 systems that use BitBake, such as the Yocto Project and
12 OpenEmbeddeded. 12 OpenEmbedded.
13 In some cases, scenarios or examples that within the context of 13 In some cases, scenarios or examples that within the context of
14 a build system are used in the manual to help with understanding. 14 a build system are used in the manual to help with understanding.
15 For these cases, the manual clearly states the context. 15 For these cases, the manual clearly states the context.
@@ -88,7 +88,7 @@
88 an aspiring embedded Linux distribution. 88 an aspiring embedded Linux distribution.
89 All of the build systems used by traditional desktop Linux 89 All of the build systems used by traditional desktop Linux
90 distributions lacked important functionality, and none of the 90 distributions lacked important functionality, and none of the
91 ad-hoc buildroot systems, prevalent in the 91 ad-hoc Buildroot-based systems, prevalent in the
92 embedded space, were scalable or maintainable. 92 embedded space, were scalable or maintainable.
93 </para> 93 </para>
94 94
@@ -216,7 +216,7 @@
216 216
217 <para> 217 <para>
218 Within the context of BitBake, or any project utilizing BitBake 218 Within the context of BitBake, or any project utilizing BitBake
219 as it's build system, files with the <filename>.bb</filename> 219 as its build system, files with the <filename>.bb</filename>
220 extension are referred to as recipes. 220 extension are referred to as recipes.
221 <note> 221 <note>
222 The term "package" is also commonly used to describe recipes. 222 The term "package" is also commonly used to describe recipes.
@@ -282,7 +282,7 @@
282 282
283 <para> 283 <para>
284 To illustrate how you can use layers to keep things modular, 284 To illustrate how you can use layers to keep things modular,
285 consider machine customizations. 285 consider customizations you might make to support a specific target machine.
286 These types of customizations typically reside in a special layer, 286 These types of customizations typically reside in a special layer,
287 rather than a general layer, called a Board Specific Package (BSP) Layer. 287 rather than a general layer, called a Board Specific Package (BSP) Layer.
288 Furthermore, the machine customizations should be isolated from 288 Furthermore, the machine customizations should be isolated from
@@ -343,7 +343,7 @@
343 <filename>busybox_1.3.0.bb</filename>, the append name would not 343 <filename>busybox_1.3.0.bb</filename>, the append name would not
344 match. 344 match.
345 However, if you named the append file 345 However, if you named the append file
346 <filename>busybox_1.%.bb</filename>, then you would have a match. 346 <filename>busybox_1.%.bbappend</filename>, then you would have a match.
347 </para> 347 </para>
348 </section> 348 </section>
349 </section> 349 </section>
@@ -421,20 +421,10 @@
421 <title>The BitBake Command</title> 421 <title>The BitBake Command</title>
422 422
423 <para> 423 <para>
424 BitBake is the underlying piece of the build system. 424 The BitBake command is the primary interface to the BitBake
425 Two excellent examples are the Yocto Project and the OpenEmbedded 425 tool.
426 build systems. 426 This section presents the BitBake command syntax and provides
427 Each provide an environment in which to develop embedded Linux 427 several execution examples.
428 images, and each use BitBake as their underlying build engine.
429 </para>
430
431 <para>
432 BitBake facilitates executing tasks in a single <filename>.bb</filename>
433 file, or executing a given task on a set of multiple
434 <filename>.bb</filename> files, accounting for interdependencies
435 amongst them.
436 This section presents the BitBake syntax and provides some execution
437 examples.
438 </para> 428 </para>
439 429
440 <section id='usage-and-syntax'> 430 <section id='usage-and-syntax'>
@@ -539,17 +529,21 @@ Options:
539 </para> 529 </para>
540 530
541 <para> 531 <para>
542 The following command runs the clean task on the
543 <filename>foo_1.0.bb</filename> recipe file:
544 <literallayout class='monospaced'>
545 $ bitbake -b foo.bb -c clean
546 </literallayout>
547 The following command runs the build task, which is 532 The following command runs the build task, which is
548 the default task, on the <filename>foo_1.0.bb</filename> 533 the default task, on the <filename>foo_1.0.bb</filename>
549 recipe file: 534 recipe file:
550 <literallayout class='monospaced'> 535 <literallayout class='monospaced'>
551 $ bitbake -b foo_1.0.bb 536 $ bitbake -b foo_1.0.bb
552 </literallayout> 537 </literallayout>
538 The following command runs the clean task on the
539 <filename>foo_1.0.bb</filename> recipe file:
540 <literallayout class='monospaced'>
541 $ bitbake -b foo.bb -c clean
542 </literallayout>
543 <note>
544 The "-b" option explicitly does not handle recipe
545 dependencies.
546 </note>
553 </para> 547 </para>
554 </section> 548 </section>
555 549
@@ -573,7 +567,7 @@ Options:
573 567
574 <para> 568 <para>
575 The <filename>bitbake</filename> command, when not using 569 The <filename>bitbake</filename> command, when not using
576 "--buildfile" or "-b" only accepts a "PROVIDER". 570 "--buildfile" or "-b" only accepts a "PROVIDES".
577 You cannot provide anything else. 571 You cannot provide anything else.
578 By default, a recipe file generally "PROVIDES" its 572 By default, a recipe file generally "PROVIDES" its
579 "packagename", "packagename-version", and 573 "packagename", "packagename-version", and
@@ -581,10 +575,6 @@ Options:
581 example: 575 example:
582 <literallayout class='monospaced'> 576 <literallayout class='monospaced'>
583 $ bitbake foo 577 $ bitbake foo
584
585 $ bitbake foo-1.0
586
587 $ bitbake foo-1.0-r0
588 </literallayout> 578 </literallayout>
589 This next example "PROVIDES" the package name and also uses 579 This next example "PROVIDES" the package name and also uses
590 the "-c" option to tell BitBake to just execute the 580 the "-c" option to tell BitBake to just execute the
@@ -600,22 +590,35 @@ Options:
600 590
601 <para> 591 <para>
602 BitBake is able to generate dependency graphs using 592 BitBake is able to generate dependency graphs using
603 the dot syntax. 593 the <filename>dot</filename> syntax.
604 You can convert these graphs into images using the dot 594 You can convert these graphs into images using the
605 application from 595 <filename>dot</filename> tool from
606 <ulink url='http://www.graphviz.org'>Graphviz</ulink>. 596 <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
607 </para> 597 </para>
608 598
609 <para> 599 <para>
610 When you generate a dependency graph, BitBake writes two files 600 When you generate a dependency graph, BitBake writes four files
611 to the current working directory: 601 to the current working directory:
612 <filename>depends.dot</filename>, which contains dependency information 602 <itemizedlist>
613 at the package level, and <filename>task-depends.dot</filename>, 603 <listitem><para><emphasis><filename>package-depends.dot</filename>:</emphasis>
614 which contains a breakdown of the dependencies at the task level. 604 Shows BitBake's knowledge of dependencies between
605 runtime targets.
606 </para></listitem>
607 <listitem><para><emphasis><filename>pn-depends.dot</filename>:</emphasis>
608 Shows dependencies between build-time targets
609 (i.e. recipes).
610 </para></listitem>
611 <listitem><para><emphasis><filename>task-depends.dot</filename>:</emphasis>
612 Shows dependencies between tasks.
613 </para></listitem>
614 <listitem><para><emphasis><filename>pn-buildlist</filename>:</emphasis>
615 Shows a simple list of targets that are to be built.
616 </para></listitem>
617 </itemizedlist>
615 </para> 618 </para>
616 619
617 <para> 620 <para>
618 To stop depending on common depends, use use the "-I" depend 621 To stop depending on common depends, use the "-I" depend
619 option and BitBake omits them from the graph. 622 option and BitBake omits them from the graph.
620 Leaving this information out can produce more readable graphs. 623 Leaving this information out can produce more readable graphs.
621 This way, you can remove from the graph 624 This way, you can remove from the graph
@@ -629,7 +632,7 @@ Options:
629 <literallayout class='monospaced'> 632 <literallayout class='monospaced'>
630 $ bitbake -g foo 633 $ bitbake -g foo
631 634
632 $ bitbake -g -I virtual/whatever -I bloom foo 635 $ bitbake -g -I virtual/kernel -I eglibc foo
633 </literallayout> 636 </literallayout>
634 </para> 637 </para>
635 </section> 638 </section>
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 748b959d98..3a19b96303 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -40,12 +40,15 @@
40 BitBake supports variables referencing one another's 40 BitBake supports variables referencing one another's
41 contents using a syntax that is similar to shell scripting. 41 contents using a syntax that is similar to shell scripting.
42 Following is an example that results in <filename>A</filename> 42 Following is an example that results in <filename>A</filename>
43 containing "aval" and <filename>B</filename> containing 43 containing "aval" and <filename>B</filename> evaluating to
44 "preavalpost". 44 "preavalpost".
45 <literallayout class='monospaced'> 45 <literallayout class='monospaced'>
46 A = "aval" 46 A = "aval"
47 B = "pre${A}post" 47 B = "pre${A}post"
48 </literallayout> 48 </literallayout>
49 Because the expansion happens later, the value of
50 <filename>B</filename> expands differently if the value
51 of <filename>A</filename> changes.
49 </para> 52 </para>
50 </section> 53 </section>
51 54
@@ -79,7 +82,7 @@
79 <title>Setting a weak default value (??=)</title> 82 <title>Setting a weak default value (??=)</title>
80 83
81 <para> 84 <para>
82 It is possible to use a "weaker" assignment that in the 85 It is possible to use a "weaker" assignment than in the
83 previous section by using the "??=" operator. 86 previous section by using the "??=" operator.
84 This assignment behaves identical to "?=" except that the 87 This assignment behaves identical to "?=" except that the
85 assignment is made at the end of the parsing process rather 88 assignment is made at the end of the parsing process rather
@@ -197,6 +200,13 @@
197 override syntax. 200 override syntax.
198 </note> 201 </note>
199 </para> 202 </para>
203
204 <para>
205 The operators "_append" and "_prepend" differ from
206 the operators ".=" and "=." in that they are deferred
207 until after parsing completes rather than being immediately
208 applied.
209 </para>
200 </section> 210 </section>
201 211
202 <section id='removing-override-style-syntax'> 212 <section id='removing-override-style-syntax'>
@@ -519,7 +529,7 @@
519 recipes require. 529 recipes require.
520 For example, you can easily abstract out the tasks involved in 530 For example, you can easily abstract out the tasks involved in
521 building a package that uses Autoconf and Automake and put 531 building a package that uses Autoconf and Automake and put
522 those tasks into a class file that can be used by your package. 532 those tasks into a class file that can be used by your recipe.
523 </para> 533 </para>
524 534
525 <para> 535 <para>
@@ -549,9 +559,10 @@
549 directive. 559 directive.
550 This directive causes BitBake to parse whatever file you specify, 560 This directive causes BitBake to parse whatever file you specify,
551 and to insert that file at that location. 561 and to insert that file at that location.
552 The directive is much like Make except that if the path specified 562 The directive is much like its equivalent in Make except
553 on the include line is a relative path, BitBake locates 563 that if the path specified on the include line is a relative
554 the first file it can find within <filename>BBPATH</filename>. 564 path, BitBake locates the first file it can find
565 within <filename>BBPATH</filename>.
555 </para> 566 </para>
556 567
557 <para> 568 <para>
@@ -588,7 +599,7 @@
588 </para> 599 </para>
589 600
590 <para> 601 <para>
591 Similar to how BitBake uses 602 Similar to how BitBake handles
592 <link linkend='include-directive'><filename>include</filename></link>, 603 <link linkend='include-directive'><filename>include</filename></link>,
593 if the path specified 604 if the path specified
594 on the require line is a relative path, BitBake locates 605 on the require line is a relative path, BitBake locates
@@ -776,16 +787,17 @@
776 Tasks are only supported in recipe (<filename>.bb</filename> 787 Tasks are only supported in recipe (<filename>.bb</filename>
777 or <filename>.inc</filename>) and class 788 or <filename>.inc</filename>) and class
778 (<filename>.bbclass</filename>) files. 789 (<filename>.bbclass</filename>) files.
779 By convention, tasks begin with the string "do_". 790 By convention, task names begin with the string "do_".
780 </para> 791 </para>
781 792
782 <para> 793 <para>
783 Here is an example of a task that prints out the date: 794 Here is an example of a task that prints out the date:
784 <literallayout class='monospaced'> 795 <literallayout class='monospaced'>
785 python do_printdate () { 796 python do_printdate () {
786 import time print 797 import time
787 time.strftime('%Y%m%d', time.gmtime()) 798 print time.strftime('%Y%m%d', time.gmtime())
788 } 799 }
800 addtask printdate after do_fetch before do_build
789 </literallayout> 801 </literallayout>
790 </para> 802 </para>
791 803
@@ -802,8 +814,8 @@
802 and defining some dependencies: 814 and defining some dependencies:
803 <literallayout class='monospaced'> 815 <literallayout class='monospaced'>
804 python do_printdate () { 816 python do_printdate () {
805 import time print 817 import time
806 time.strftime('%Y%m%d', time.gmtime()) 818 print time.strftime('%Y%m%d', time.gmtime())
807 } 819 }
808 addtask printdate after do_fetch before do_build 820 addtask printdate after do_fetch before do_build
809 </literallayout> 821 </literallayout>
@@ -942,11 +954,6 @@
942 <para> 954 <para>
943 BitBake has a defined set of varflags available for recipes and 955 BitBake has a defined set of varflags available for recipes and
944 classes. 956 classes.
945 You can discover the complete set by using <filename>grep</filename>
946 within a shell and search on the string "VarFlags".
947 </para>
948
949 <para>
950 Tasks support a number of these flags which control various 957 Tasks support a number of these flags which control various
951 functionality of the task: 958 functionality of the task:
952 <itemizedlist> 959 <itemizedlist>
@@ -958,12 +965,13 @@
958 </para></listitem> 965 </para></listitem>
959 <listitem><para><emphasis>noexec:</emphasis> 966 <listitem><para><emphasis>noexec:</emphasis>
960 Marks the tasks as being empty and no execution required. 967 Marks the tasks as being empty and no execution required.
961 These flags are used as dependency placeholders or used when 968 The <filename>noexec</filename> flag can be used to set up
962 added tasks need to be subsequently disabled. 969 tasks as dependency placeholders, or to disable tasks defined
970 elsewhere that are not needed in a particular recipe.
963 </para></listitem> 971 </para></listitem>
964 <listitem><para><emphasis>nostamp:</emphasis> 972 <listitem><para><emphasis>nostamp:</emphasis>
965 Tells BitBake to not generate a stamp file for a task, 973 Tells BitBake to not generate a stamp file for a task,
966 which implies the task is always executed. 974 which implies the task should always be executed.
967 </para></listitem> 975 </para></listitem>
968 <listitem><para><emphasis>fakeroot:</emphasis> 976 <listitem><para><emphasis>fakeroot:</emphasis>
969 Causes a task to be run in a fakeroot environment, 977 Causes a task to be run in a fakeroot environment,
@@ -1027,7 +1035,7 @@
1027 List of functions to call before the task executes. 1035 List of functions to call before the task executes.
1028 </para></listitem> 1036 </para></listitem>
1029 <listitem><para><emphasis>stamp-extra-info:</emphasis> 1037 <listitem><para><emphasis>stamp-extra-info:</emphasis>
1030 Extra stamp information to append to the task's stamp 1038 Extra stamp information to append to the task's stamp.
1031 As an example, OpenEmbedded uses this flag to allow 1039 As an example, OpenEmbedded uses this flag to allow
1032 machine-specific tasks. 1040 machine-specific tasks.
1033 </para></listitem> 1041 </para></listitem>
@@ -1380,15 +1388,18 @@
1380 </row> 1388 </row>
1381 <row> 1389 <row>
1382 <entry align="left"><filename>d.setVar("X", value)</filename></entry> 1390 <entry align="left"><filename>d.setVar("X", value)</filename></entry>
1383 <entry align="left">Sets the variable "X" to "value".</entry> 1391 <entry align="left">Sets the variable "X" to the value of the Python
1392 variable called "value".</entry>
1384 </row> 1393 </row>
1385 <row> 1394 <row>
1386 <entry align="left"><filename>d.appendVar("X", value)</filename></entry> 1395 <entry align="left"><filename>d.appendVar("X", value)</filename></entry>
1387 <entry align="left">Adds "value" to the end of the variable "X".</entry> 1396 <entry align="left">Adds the value of the Python variable called
1397 "value" to the end of the variable "X".</entry>
1388 </row> 1398 </row>
1389 <row> 1399 <row>
1390 <entry align="left"><filename>d.prependVar("X", value)</filename></entry> 1400 <entry align="left"><filename>d.prependVar("X", value)</filename></entry>
1391 <entry align="left">Adds "value" to the start of the variable "X".</entry> 1401 <entry align="left">Adds the value of the Python variable called
1402 "value" to the start of the variable "X".</entry>
1392 </row> 1403 </row>
1393 <row> 1404 <row>
1394 <entry align="left"><filename>d.delVar("X")</filename></entry> 1405 <entry align="left"><filename>d.delVar("X")</filename></entry>
@@ -1400,40 +1411,44 @@
1400 </row> 1411 </row>
1401 <row> 1412 <row>
1402 <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry> 1413 <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
1403 <entry align="left">Gets "flag" from the variable "X". 1414 <entry align="left">Gets then named flag from the variable "X".
1404 Using "expand=True" expands the flag.</entry> 1415 Using "expand=True" expands the named flag.</entry>
1405 </row> 1416 </row>
1406 <row> 1417 <row>
1407 <entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry> 1418 <entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry>
1408 <entry align="left">Sets "flag" for variable "X" to "value". 1419 <entry align="left">Sets the named flag for variable "X" to the value
1409 <filename>setVarFlags</filename> does not clear previous flags. 1420 of the Python variable called "value".</entry>
1410 Think of this operation as <filename>addVarFlags</filename>.</entry>
1411 </row> 1421 </row>
1412 <row> 1422 <row>
1413 <entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry> 1423 <entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry>
1414 <entry align="left">Need description.</entry> 1424 <entry align="left">Appends a value to the named flag on the
1425 variable "X".</entry>
1415 </row> 1426 </row>
1416 <row> 1427 <row>
1417 <entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry> 1428 <entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry>
1418 <entry align="left">Need description.</entry> 1429 <entry align="left">Prepends a value to the named flag on
1430 the variable "X".</entry>
1419 </row> 1431 </row>
1420 <row> 1432 <row>
1421 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry> 1433 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
1422 <entry align="left">Need description.</entry> 1434 <entry align="left">Deletes the named flag on the variable
1435 "X" from the datastore.</entry>
1423 </row> 1436 </row>
1424 <row> 1437 <row>
1425 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry> 1438 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
1426 <entry align="left">Sets the flags specified in 1439 <entry align="left">Sets the flags specified in
1427 the <filename>dict()</filename> parameter.</entry> 1440 the <filename>flagsdict()</filename> parameter.
1441 <filename>setVarFlags</filename> does not clear previous flags.
1442 Think of this operation as <filename>addVarFlags</filename>.</entry>
1428 </row> 1443 </row>
1429 <row> 1444 <row>
1430 <entry align="left"><filename>d.getVarFlags("X")</filename></entry> 1445 <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
1431 <entry align="left">Returns a <filename>dict</filename> of the flags for 1446 <entry align="left">Returns a <filename>flagsdict</filename> of the flags for
1432 the variable "X".</entry> 1447 the variable "X".</entry>
1433 </row> 1448 </row>
1434 <row> 1449 <row>
1435 <entry align="left"><filename>d.delVarFlags</filename></entry> 1450 <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
1436 <entry align="left">Deletes all the flags for a variable.</entry> 1451 <entry align="left">Deletes all the flags for the variable "X".</entry>
1437 </row> 1452 </row>
1438 </tbody> 1453 </tbody>
1439 </tgroup> 1454 </tgroup>