summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual
diff options
context:
space:
mode:
authorTudor Florea <tudor.florea@enea.com>2015-10-09 22:59:03 +0200
committerTudor Florea <tudor.florea@enea.com>2015-10-09 22:59:03 +0200
commit972dcfcdbfe75dcfeb777150c136576cf1a71e99 (patch)
tree97a61cd7e293d7ae9d56ef7ed0f81253365bb026 /bitbake/doc/bitbake-user-manual
downloadpoky-972dcfcdbfe75dcfeb777150c136576cf1a71e99.tar.gz
initial commit for Enea Linux 5.0 arm
Signed-off-by: Tudor Florea <tudor.florea@enea.com>
Diffstat (limited to 'bitbake/doc/bitbake-user-manual')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl21
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml910
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml738
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml506
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml685
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml1790
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml2152
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css984
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml88
-rw-r--r--bitbake/doc/bitbake-user-manual/figures/bitbake-title.pngbin0 -> 5086 bytes
-rw-r--r--bitbake/doc/bitbake-user-manual/html.css281
11 files changed, 8155 insertions, 0 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl
new file mode 100644
index 0000000000..ebfa5404c2
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl
@@ -0,0 +1,21 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
5
6 <xsl:include href="../template/permalinks.xsl"/>
7 <xsl:include href="../template/section.title.xsl"/>
8 <xsl:include href="../template/component.title.xsl"/>
9 <xsl:include href="../template/division.title.xsl"/>
10 <xsl:include href="../template/formal.object.heading.xsl"/>
11 <xsl:include href="../template/gloss-permalinks.xsl"/>
12
13 <xsl:param name="html.stylesheet" select="'user-manual-style.css'" />
14 <xsl:param name="chapter.autolabel" select="1" />
15 <xsl:param name="section.autolabel" select="1" />
16 <xsl:param name="section.label.includes.component.label" select="1" />
17 <xsl:param name="appendix.autolabel">A</xsl:param>
18
19<!-- <xsl:param name="generate.toc" select="'article nop'"></xsl:param> -->
20
21</xsl:stylesheet>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
new file mode 100644
index 0000000000..571424b99f
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
@@ -0,0 +1,910 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id="bitbake-user-manual-execution">
5 <title>Execution</title>
6
7 <para>
8 The primary purpose for running BitBake is to produce some kind
9 of output such as a single installable package, a kernel, a software
10 development kit, or even a full, board-specific bootable Linux image,
11 complete with bootloader, kernel, and root filesystem.
12 Of course, you can execute the <filename>bitbake</filename>
13 command with options that cause it to execute single tasks,
14 compile single recipe files, capture or clear data, or simply
15 return information about the execution environment.
16 </para>
17
18 <para>
19 This chapter describes BitBake's execution process from start
20 to finish when you use it to create an image.
21 The execution process is launched using the following command
22 form:
23 <literallayout class='monospaced'>
24 $ bitbake &lt;target&gt;
25 </literallayout>
26 For information on the BitBake command and its options,
27 see
28 "<link linkend='bitbake-user-manual-command'>The BitBake Command</link>"
29 section.
30 <note>
31 <para>
32 Prior to executing BitBake, you should take advantage of available
33 parallel thread execution on your build host by setting the
34 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
35 variable in your project's <filename>local.conf</filename>
36 configuration file.
37 </para>
38
39 <para>
40 A common way to determine this value for your build host is to run:
41 <literallayout class='monospaced'>
42 $ grep processor /proc/cpuinfo
43 </literallayout>
44 and count the number of processors displayed. Note that the number of
45 processors will take into account hyper-threading, so that a quad-core
46 build host with hyper-threading will most likely show eight processors,
47 which is the value you would then assign to that variable.
48 </para>
49
50 <para>
51 A possibly simpler solution is that some Linux distributions
52 (e.g. Debian and Ubuntu) provide the <filename>ncpus</filename> command.
53 </para>
54 </note>
55 </para>
56
57 <section id='parsing-the-base-configuration-metadata'>
58 <title>Parsing the Base Configuration Metadata</title>
59
60 <para>
61 The first thing BitBake does is parse base configuration
62 metadata.
63 Base configuration metadata consists of your project's
64 <filename>bblayers.conf</filename> file to determine what
65 layers BitBake needs to recognize, all necessary
66 <filename>layer.conf</filename> files (one from each layer),
67 and <filename>bitbake.conf</filename>.
68 The data itself is of various types:
69 <itemizedlist>
70 <listitem><para><emphasis>Recipes:</emphasis>
71 Details about particular pieces of software.
72 </para></listitem>
73 <listitem><para><emphasis>Class Data:</emphasis>
74 An abstraction of common build information
75 (e.g. how to build a Linux kernel).
76 </para></listitem>
77 <listitem><para><emphasis>Configuration Data:</emphasis>
78 Machine-specific settings, policy decisions,
79 and so forth.
80 Configuration data acts as the glue to bind everything
81 together.</para></listitem>
82 </itemizedlist>
83 </para>
84
85 <para>
86 The <filename>layer.conf</filename> files are used to
87 construct key variables such as
88 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
89 and
90 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>.
91 <filename>BBPATH</filename> is used to search for
92 configuration and class files under the
93 <filename>conf</filename> and <filename>classes</filename>
94 directories, respectively.
95 <filename>BBFILES</filename> is used to locate both recipe
96 and recipe append files
97 (<filename>.bb</filename> and <filename>.bbappend</filename>).
98 If there is no <filename>bblayers.conf</filename> file,
99 it is assumed the user has set the <filename>BBPATH</filename>
100 and <filename>BBFILES</filename> directly in the environment.
101 </para>
102
103 <para>
104 Next, the <filename>bitbake.conf</filename> file is located
105 using the <filename>BBPATH</filename> variable that was
106 just constructed.
107 The <filename>bitbake.conf</filename> file may also include other
108 configuration files using the
109 <filename>include</filename> or
110 <filename>require</filename> directives.
111 </para>
112
113 <para>
114 Prior to parsing configuration files, Bitbake looks
115 at certain variables, including:
116 <itemizedlist>
117 <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
118 <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
119 <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
120 <listitem><para>
121 <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
122 </para></listitem>
123 </itemizedlist>
124 You can find information on how to pass environment variables into the BitBake
125 execution environment in the
126 "<link linkend='passing-information-into-the-build-task-environment'>Passing Information Into the Build Task Environment</link>" section.
127 </para>
128
129 <para>
130 The base configuration metadata is global
131 and therefore affects all recipes and tasks that are executed.
132 </para>
133
134 <para>
135 BitBake first searches the current working directory for an
136 optional <filename>conf/bblayers.conf</filename> configuration file.
137 This file is expected to contain a
138 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
139 variable that is a space-delimited list of 'layer' directories.
140 Recall that if BitBake cannot find a <filename>bblayers.conf</filename>
141 file, then it is assumed the user has set the <filename>BBPATH</filename>
142 and <filename>BBFILES</filename> variables directly in the environment.
143 </para>
144
145 <para>
146 For each directory (layer) in this list, a <filename>conf/layer.conf</filename>
147 file is located and parsed with the
148 <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
149 variable being set to the directory where the layer was found.
150 The idea is these files automatically set up
151 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
152 and other variables correctly for a given build directory.
153 </para>
154
155 <para>
156 BitBake then expects to find the <filename>conf/bitbake.conf</filename>
157 file somewhere in the user-specified <filename>BBPATH</filename>.
158 That configuration file generally has include directives to pull
159 in any other metadata such as files specific to the architecture,
160 the machine, the local environment, and so forth.
161 </para>
162
163 <para>
164 Only variable definitions and include directives are allowed
165 in BitBake <filename>.conf</filename> files.
166 Some variables directly influence BitBake's behavior.
167 These variables might have been set from the environment
168 depending on the environment variables previously
169 mentioned or set in the configuration files.
170 The
171 "<link linkend='ref-variables-glos'>Variables Glossary</link>"
172 chapter presents a full list of variables.
173 </para>
174
175 <para>
176 After parsing configuration files, BitBake uses its rudimentary
177 inheritance mechanism, which is through class files, to inherit
178 some standard classes.
179 BitBake parses a class when the inherit directive responsible
180 for getting that class is encountered.
181 </para>
182
183 <para>
184 The <filename>base.bbclass</filename> file is always included.
185 Other classes that are specified in the configuration using the
186 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
187 variable are also included.
188 BitBake searches for class files in a
189 <filename>classes</filename> subdirectory under
190 the paths in <filename>BBPATH</filename> in the same way as
191 configuration files.
192 </para>
193
194 <para>
195 A good way to get an idea of the configuration files and
196 the class files used in your execution environment is to
197 run the following BitBake command:
198 <literallayout class='monospaced'>
199 $ bitbake -e > mybb.log
200 </literallayout>
201 Examining the top of the <filename>mybb.log</filename>
202 shows you the many configuration files and class files
203 used in your execution environment.
204 </para>
205
206 <note>
207 <para>
208 You need to be aware of how BitBake parses curly braces.
209 If a recipe uses a closing curly brace within the function and
210 the character has no leading spaces, BitBake produces a parsing
211 error.
212 If you use a pair of curly braces in a shell function, the
213 closing curly brace must not be located at the start of the line
214 without leading spaces.
215 </para>
216
217 <para>
218 Here is an example that causes BitBake to produce a parsing
219 error:
220 <literallayout class='monospaced'>
221 fakeroot create_shar() {
222 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
223 usage()
224 {
225 echo "test"
226 ###### The following "}" at the start of the line causes a parsing error ######
227 }
228 EOF
229 }
230 </literallayout>
231 Writing the recipe this way avoids the error:
232 <literallayout class='monospaced'>
233 fakeroot create_shar() {
234 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
235 usage()
236 {
237 echo "test"
238 ######The following "}" with a leading space at the start of the line avoids the error ######
239 }
240 EOF
241 }
242 </literallayout>
243 </para>
244 </note>
245 </section>
246
247 <section id='locating-and-parsing-recipes'>
248 <title>Locating and Parsing Recipes</title>
249
250 <para>
251 During the configuration phase, BitBake will have set
252 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>.
253 BitBake now uses it to construct a list of recipes to parse,
254 along with any append files (<filename>.bbappend</filename>)
255 to apply.
256 <filename>BBFILES</filename> is a space-separated list of
257 available files and supports wildcards.
258 An example would be:
259 <literallayout class='monospaced'>
260 BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
261 </literallayout>
262 BitBake parses each recipe and append file located
263 with <filename>BBFILES</filename> and stores the values of
264 various variables into the datastore.
265 <note>
266 Append files are applied in the order they are encountered in
267 <filename>BBFILES</filename>.
268 </note>
269 For each file, a fresh copy of the base configuration is
270 made, then the recipe is parsed line by line.
271 Any inherit statements cause BitBake to find and
272 then parse class files (<filename>.bbclass</filename>)
273 using
274 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
275 as the search path.
276 Finally, BitBake parses in order any append files found in
277 <filename>BBFILES</filename>.
278 </para>
279
280 <para>
281 One common convention is to use the recipe filename to define
282 pieces of metadata.
283 For example, in <filename>bitbake.conf</filename> the recipe
284 name and version are used to set the variables
285 <link linkend='var-PN'><filename>PN</filename></link> and
286 <link linkend='var-PV'><filename>PV</filename></link>:
287 <literallayout class='monospaced'>
288 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[0] or 'defaultpkgname'}"
289 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[1] or '1.0'}"
290 </literallayout>
291 In this example, a recipe called "something_1.2.3.bb" would set
292 <filename>PN</filename> to "something" and
293 <filename>PV</filename> to "1.2.3".
294 </para>
295
296 <para>
297 By the time parsing is complete for a recipe, BitBake
298 has a list of tasks that the recipe defines and a set of
299 data consisting of keys and values as well as
300 dependency information about the tasks.
301 </para>
302
303 <para>
304 BitBake does not need all of this information.
305 It only needs a small subset of the information to make
306 decisions about the recipe.
307 Consequently, BitBake caches the values in which it is
308 interested and does not store the rest of the information.
309 Experience has shown it is faster to re-parse the metadata than to
310 try and write it out to the disk and then reload it.
311 </para>
312
313 <para>
314 Where possible, subsequent BitBake commands reuse this cache of
315 recipe information.
316 The validity of this cache is determined by first computing a
317 checksum of the base configuration data (see
318 <link linkend='var-BB_HASHCONFIG_WHITELIST'><filename>BB_HASHCONFIG_WHITELIST</filename></link>)
319 and then checking if the checksum matches.
320 If that checksum matches what is in the cache and the recipe
321 and class files have not changed, Bitbake is able to use
322 the cache.
323 BitBake then reloads the cached information about the recipe
324 instead of reparsing it from scratch.
325 </para>
326
327 <para>
328 Recipe file collections exist to allow the user to
329 have multiple repositories of
330 <filename>.bb</filename> files that contain the same
331 exact package.
332 For example, one could easily use them to make one's
333 own local copy of an upstream repository, but with
334 custom modifications that one does not want upstream.
335 Here is an example:
336 <literallayout class='monospaced'>
337 BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
338 BBFILE_COLLECTIONS = "upstream local"
339 BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
340 BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
341 BBFILE_PRIORITY_upstream = "5"
342 BBFILE_PRIORITY_local = "10"
343 </literallayout>
344 <note>
345 The layers mechanism is now the preferred method of collecting
346 code.
347 While the collections code remains, its main use is to set layer
348 priorities and to deal with overlap (conflicts) between layers.
349 </note>
350 </para>
351 </section>
352
353 <section id='bb-bitbake-providers'>
354 <title>Providers</title>
355
356 <para>
357 Assuming BitBake has been instructed to execute a target
358 and that all the recipe files have been parsed, BitBake
359 starts to figure out how to build the target.
360 BitBake looks through the <filename>PROVIDES</filename> list
361 for each of the recipes.
362 A <filename>PROVIDES</filename> list is the list of names by which
363 the recipe can be known.
364 Each recipe's <filename>PROVIDES</filename> list is created
365 implicitly through the recipe's
366 <link linkend='var-PN'><filename>PN</filename></link> variable
367 and explicitly through the recipe's
368 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
369 variable, which is optional.
370 </para>
371
372 <para>
373 When a recipe uses <filename>PROVIDES</filename>, that recipe's
374 functionality can be found under an alternative name or names other
375 than the implicit <filename>PN</filename> name.
376 As an example, suppose a recipe named <filename>keyboard_1.0.bb</filename>
377 contained the following:
378 <literallayout class='monospaced'>
379 PROVIDES += "fullkeyboard"
380 </literallayout>
381 The <filename>PROVIDES</filename> list for this recipe becomes
382 "keyboard", which is implicit, and "fullkeyboard", which is explicit.
383 Consequently, the functionality found in
384 <filename>keyboard_1.0.bb</filename> can be found under two
385 different names.
386 </para>
387 </section>
388
389 <section id='bb-bitbake-preferences'>
390 <title>Preferences</title>
391
392 <para>
393 The <filename>PROVIDES</filename> list is only part of the solution
394 for figuring out a target's recipes.
395 Because targets might have multiple providers, BitBake needs
396 to prioritize providers by determining provider preferences.
397 </para>
398
399 <para>
400 A common example in which a target has multiple providers
401 is "virtual/kernel", which is on the
402 <filename>PROVIDES</filename> list for each kernel recipe.
403 Each machine often selects the best kernel provider by using a
404 line similar to the following in the machine configuration file:
405 <literallayout class='monospaced'>
406 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
407 </literallayout>
408 The default
409 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
410 is the provider with the same name as the target.
411 Bitbake iterates through each target it needs to build and
412 resolves them and their dependencies using this process.
413 </para>
414
415 <para>
416 Understanding how providers are chosen is made complicated by the fact
417 that multiple versions might exist for a given provider.
418 BitBake defaults to the highest version of a provider.
419 Version comparisons are made using the same method as Debian.
420 You can use the
421 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
422 variable to specify a particular version.
423 You can influence the order by using the
424 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
425 variable.
426 </para>
427
428 <para>
429 By default, files have a preference of "0".
430 Setting <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
431 recipe unlikely to be used unless it is explicitly referenced.
432 Setting <filename>DEFAULT_PREFERENCE</filename> to "1" makes it
433 likely the recipe is used.
434 <filename>PREFERRED_VERSION</filename> overrides any
435 <filename>DEFAULT_PREFERENCE</filename> setting.
436 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer
437 and more experimental recipe versions until they have undergone
438 sufficient testing to be considered stable.
439 </para>
440
441 <para>
442 When there are multiple “versions†of a given recipe,
443 BitBake defaults to selecting the most recent
444 version, unless otherwise specified.
445 If the recipe in question has a
446 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
447 set lower than the other recipes (default is 0), then
448 it will not be selected.
449 This allows the person or persons maintaining
450 the repository of recipe files to specify
451 their preference for the default selected version.
452 Additionally, the user can specify their preferred version.
453 </para>
454
455 <para>
456 If the first recipe is named <filename>a_1.1.bb</filename>, then the
457 <link linkend='var-PN'><filename>PN</filename></link> variable
458 will be set to “aâ€, and the
459 <link linkend='var-PV'><filename>PV</filename></link>
460 variable will be set to 1.1.
461 </para>
462
463 <para>
464 Thus, if a recipe named <filename>a_1.2.bb</filename> exists, BitBake
465 will choose 1.2 by default.
466 However, if you define the following variable in a
467 <filename>.conf</filename> file that BitBake parses, you
468 can change that preference:
469 <literallayout class='monospaced'>
470 PREFERRED_VERSION_a = "1.1"
471 </literallayout>
472 </para>
473
474 <note>
475 <para>
476 It is common for a recipe to provide two versions -- a stable,
477 numbered (and preferred) version, and a version that is
478 automatically checked out from a source code repository that
479 is considered more "bleeding edge" but can be selected only
480 explicitly.
481 </para>
482
483 <para>
484 For example, in the OpenEmbedded codebase, there is a standard,
485 versioned recipe file for BusyBox,
486 <filename>busybox_1.22.1.bb</filename>,
487 but there is also a Git-based version,
488 <filename>busybox_git.bb</filename>, which explicitly contains the line
489 <literallayout class='monospaced'>
490 DEFAULT_PREFERENCE = "-1"
491 </literallayout>
492 to ensure that the numbered, stable version is always preferred
493 unless the developer selects otherwise.
494 </para>
495 </note>
496 </section>
497
498 <section id='bb-bitbake-dependencies'>
499 <title>Dependencies</title>
500
501 <para>
502 Each target BitBake builds consists of multiple tasks such as
503 <filename>fetch</filename>, <filename>unpack</filename>,
504 <filename>patch</filename>, <filename>configure</filename>,
505 and <filename>compile</filename>.
506 For best performance on multi-core systems, BitBake considers each
507 task as an independent
508 entity with its own set of dependencies.
509 </para>
510
511 <para>
512 Dependencies are defined through several variables.
513 You can find information about variables BitBake uses in
514 the <link linkend='ref-variables-glos'>Variables Glossary</link>
515 near the end of this manual.
516 At a basic level, it is sufficient to know that BitBake uses the
517 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> and
518 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> variables when
519 calculating dependencies.
520 </para>
521
522 <para>
523 For more information on how BitBake handles dependencies, see the
524 "<link linkend='dependencies'>Dependencies</link>" section.
525 </para>
526 </section>
527
528 <section id='ref-bitbake-tasklist'>
529 <title>The Task List</title>
530
531 <para>
532 Based on the generated list of providers and the dependency information,
533 BitBake can now calculate exactly what tasks it needs to run and in what
534 order it needs to run them.
535 The
536 "<link linkend='executing-tasks'>Executing Tasks</link>" section has more
537 information on how BitBake chooses which task to execute next.
538 </para>
539
540 <para>
541 The build now starts with BitBake forking off threads up to the limit set in the
542 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
543 variable.
544 BitBake continues to fork threads as long as there are tasks ready to run,
545 those tasks have all their dependencies met, and the thread threshold has not been
546 exceeded.
547 </para>
548
549 <para>
550 It is worth noting that you can greatly speed up the build time by properly setting
551 the <filename>BB_NUMBER_THREADS</filename> variable.
552 </para>
553
554 <para>
555 As each task completes, a timestamp is written to the directory specified by the
556 <link linkend='var-STAMP'><filename>STAMP</filename></link> variable.
557 On subsequent runs, BitBake looks in the build directory within
558 <filename>tmp/stamps</filename> and does not rerun
559 tasks that are already completed unless a timestamp is found to be invalid.
560 Currently, invalid timestamps are only considered on a per
561 recipe file basis.
562 So, for example, if the configure stamp has a timestamp greater than the
563 compile timestamp for a given target, then the compile task would rerun.
564 Running the compile task again, however, has no effect on other providers
565 that depend on that target.
566 </para>
567
568 <para>
569 The exact format of the stamps is partly configurable.
570 In modern versions of BitBake, a hash is appended to the
571 stamp so that if the configuration changes, the stamp becomes
572 invalid and the task is automatically rerun.
573 This hash, or signature used, is governed by the signature policy
574 that is configured (see the
575 "<link linkend='checksums'>Checksums (Signatures)</link>"
576 section for information).
577 It is also possible to append extra metadata to the stamp using
578 the "stamp-extra-info" task flag.
579 For example, OpenEmbedded uses this flag to make some tasks machine-specific.
580 </para>
581
582 <note>
583 Some tasks are marked as "nostamp" tasks.
584 No timestamp file is created when these tasks are run.
585 Consequently, "nostamp" tasks are always rerun.
586 </note>
587
588 <para>
589 For more information on tasks, see the
590 "<link linkend='tasks'>Tasks</link>" section.
591 </para>
592 </section>
593
594 <section id='executing-tasks'>
595 <title>Executing Tasks</title>
596
597 <para>
598 Tasks can be either a shell task or a Python task.
599 For shell tasks, BitBake writes a shell script to
600 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/run.do_taskname.pid</filename>
601 and then executes the script.
602 The generated shell script contains all the exported variables,
603 and the shell functions with all variables expanded.
604 Output from the shell script goes to the file
605 <filename>${T}/log.do_taskname.pid</filename>.
606 Looking at the expanded shell functions in the run file and
607 the output in the log files is a useful debugging technique.
608 </para>
609
610 <para>
611 For Python tasks, BitBake executes the task internally and logs
612 information to the controlling terminal.
613 Future versions of BitBake will write the functions to files
614 similar to the way shell tasks are handled.
615 Logging will be handled in a way similar to shell tasks as well.
616 </para>
617
618 <para>
619 The order in which BitBake runs the tasks is controlled by its
620 task scheduler.
621 It is possible to configure the scheduler and define custom
622 implementations for specific use cases.
623 For more information, see these variables that control the
624 behavior:
625 <itemizedlist>
626 <listitem><para>
627 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
628 </para></listitem>
629 <listitem><para>
630 <link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link>
631 </para></listitem>
632 </itemizedlist>
633 It is possible to have functions run before and after a task's main
634 function.
635 This is done using the "prefuncs" and "postfuncs" flags of the task
636 that lists the functions to run.
637 </para>
638 </section>
639
640 <section id='checksums'>
641 <title>Checksums (Signatures)</title>
642
643 <para>
644 A checksum is a unique signature of a task's inputs.
645 The signature of a task can be used to determine if a task
646 needs to be run.
647 Because it is a change in a task's inputs that triggers running
648 the task, BitBake needs to detect all the inputs to a given task.
649 For shell tasks, this turns out to be fairly easy because
650 BitBake generates a "run" shell script for each task and
651 it is possible to create a checksum that gives you a good idea of when
652 the task's data changes.
653 </para>
654
655 <para>
656 To complicate the problem, some things should not be included in
657 the checksum.
658 First, there is the actual specific build path of a given task -
659 the working directory.
660 It does not matter if the working directory changes because it should not
661 affect the output for target packages.
662 The simplistic approach for excluding the working directory is to set
663 it to some fixed value and create the checksum for the "run" script.
664 BitBake goes one step better and uses the
665 <link linkend='var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></link>
666 variable to define a list of variables that should never be included
667 when generating the signatures.
668 </para>
669
670 <para>
671 Another problem results from the "run" scripts containing functions that
672 might or might not get called.
673 The incremental build solution contains code that figures out dependencies
674 between shell functions.
675 This code is used to prune the "run" scripts down to the minimum set,
676 thereby alleviating this problem and making the "run" scripts much more
677 readable as a bonus.
678 </para>
679
680 <para>
681 So far we have solutions for shell scripts.
682 What about Python tasks?
683 The same approach applies even though these tasks are more difficult.
684 The process needs to figure out what variables a Python function accesses
685 and what functions it calls.
686 Again, the incremental build solution contains code that first figures out
687 the variable and function dependencies, and then creates a checksum for the data
688 used as the input to the task.
689 </para>
690
691 <para>
692 Like the working directory case, situations exist where dependencies
693 should be ignored.
694 For these cases, you can instruct the build process to ignore a dependency
695 by using a line like the following:
696 <literallayout class='monospaced'>
697 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
698 </literallayout>
699 This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
700 depend on the value of <filename>MACHINE</filename>, even if it does reference it.
701 </para>
702
703 <para>
704 Equally, there are cases where we need to add dependencies BitBake
705 is not able to find.
706 You can accomplish this by using a line like the following:
707 <literallayout class='monospaced'>
708 PACKAGE_ARCHS[vardeps] = "MACHINE"
709 </literallayout>
710 This example explicitly adds the <filename>MACHINE</filename> variable as a
711 dependency for <filename>PACKAGE_ARCHS</filename>.
712 </para>
713
714 <para>
715 Consider a case with in-line Python, for example, where BitBake is not
716 able to figure out dependencies.
717 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
718 produces output when it discovers something for which it cannot figure out
719 dependencies.
720 </para>
721
722 <para>
723 Thus far, this section has limited discussion to the direct inputs into a task.
724 Information based on direct inputs is referred to as the "basehash" in the
725 code.
726 However, there is still the question of a task's indirect inputs - the
727 things that were already built and present in the build directory.
728 The checksum (or signature) for a particular task needs to add the hashes
729 of all the tasks on which the particular task depends.
730 Choosing which dependencies to add is a policy decision.
731 However, the effect is to generate a master checksum that combines the basehash
732 and the hashes of the task's dependencies.
733 </para>
734
735 <para>
736 At the code level, there are a variety of ways both the basehash and the
737 dependent task hashes can be influenced.
738 Within the BitBake configuration file, we can give BitBake some extra information
739 to help it construct the basehash.
740 The following statement effectively results in a list of global variable
741 dependency excludes - variables never included in any checksum.
742 This example uses variables from OpenEmbedded to help illustrate
743 the concept:
744 <literallayout class='monospaced'>
745 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
746 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
747 USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
748 PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
749 CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
750 </literallayout>
751 The previous example excludes the work directory, which is part of
752 <filename>TMPDIR</filename>.
753 </para>
754
755 <para>
756 The rules for deciding which hashes of dependent tasks to include through
757 dependency chains are more complex and are generally accomplished with a
758 Python function.
759 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
760 of this and also illustrates how you can insert your own policy into the system
761 if so desired.
762 This file defines the two basic signature generators OpenEmbedded Core
763 uses: "OEBasic" and "OEBasicHash".
764 By default, there is a dummy "noop" signature handler enabled in BitBake.
765 This means that behavior is unchanged from previous versions.
766 <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
767 through this setting in the <filename>bitbake.conf</filename> file:
768 <literallayout class='monospaced'>
769 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
770 </literallayout>
771 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
772 "OEBasic" version but adds the task hash to the stamp files.
773 This results in any metadata change that changes the task hash, automatically
774 causing the task to be run again.
775 This removes the need to bump
776 <link linkend='var-PR'><filename>PR</filename></link>
777 values, and changes to metadata automatically ripple across the build.
778 </para>
779
780 <para>
781 It is also worth noting that the end result of these signature generators is to
782 make some dependency and hash information available to the build.
783 This information includes:
784 <itemizedlist>
785 <listitem><para><filename>BB_BASEHASH_task-&lt;taskname&gt;</filename>:
786 The base hashes for each task in the recipe.
787 </para></listitem>
788 <listitem><para><filename>BB_BASEHASH_&lt;filename:taskname&gt;</filename>:
789 The base hashes for each dependent task.
790 </para></listitem>
791 <listitem><para><filename>BBHASHDEPS_&lt;filename:taskname&gt;</filename>:
792 The task dependencies for each task.
793 </para></listitem>
794 <listitem><para><filename>BB_TASKHASH</filename>:
795 The hash of the currently running task.
796 </para></listitem>
797 </itemizedlist>
798 </para>
799
800 <para>
801 It is worth noting that BitBake's "-S" option lets you
802 debug Bitbake's processing of signatures.
803 The options passed to -S allow different debugging modes
804 to be used, either using BitBake's own debug functions
805 or possibly those defined in the metadata/signature handler
806 itself.
807 The simplest parameter to pass is "none", which causes a
808 set of signature information to be written out into
809 <filename>STAMP_DIR</filename>
810 corresponding to the targets specified.
811 The other currently available parameter is "printdiff",
812 which causes BitBake to try to establish the closest
813 signature match it can (e.g. in the sstate cache) and then
814 run <filename>bitbake-diffsigs</filename> over the matches
815 to determine the stamps and delta where these two
816 stamp trees diverge.
817 <note>
818 It is likely that future versions of BitBake will
819 provide other signature handlers triggered through
820 additional "-S" parameters.
821 </note>
822 </para>
823
824 <para>
825 You can find more information on checksum metadata in the
826 "<link linkend='task-checksums-and-setscene'>Task Checksums and Setscene</link>"
827 section.
828 </para>
829 </section>
830
831 <section id='setscene'>
832 <title>Setscene</title>
833
834 <para>
835 The setscene process enables BitBake to handle "pre-built" artifacts.
836 The ability to handle and reuse these artifacts allows BitBake
837 the luxury of not having to build something from scratch every time.
838 Instead, BitBake can use, when possible, existing build artifacts.
839 </para>
840
841 <para>
842 BitBake needs to have reliable data indicating whether or not an
843 artifact is compatible.
844 Signatures, described in the previous section, provide an ideal
845 way of representing whether an artifact is compatible.
846 If a signature is the same, an object can be reused.
847 </para>
848
849 <para>
850 If an object can be reused, the problem then becomes how to
851 replace a given task or set of tasks with the pre-built artifact.
852 BitBake solves the problem with the "setscene" process.
853 </para>
854
855 <para>
856 When BitBake is asked to build a given target, before building anything,
857 it first asks whether cached information is available for any of the
858 targets it's building, or any of the intermediate targets.
859 If cached information is available, BitBake uses this information instead of
860 running the main tasks.
861 </para>
862
863 <para>
864 BitBake first calls the function defined by the
865 <link linkend='var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>
866 variable with a list of tasks and corresponding
867 hashes it wants to build.
868 This function is designed to be fast and returns a list
869 of the tasks for which it believes in can obtain artifacts.
870 </para>
871
872 <para>
873 Next, for each of the tasks that were returned as possibilities,
874 BitBake executes a setscene version of the task that the possible
875 artifact covers.
876 Setscene versions of a task have the string "_setscene" appended to the
877 task name.
878 So, for example, the task with the name <filename>xxx</filename> has
879 a setscene task named <filename>xxx_setscene</filename>.
880 The setscene version of the task executes and provides the necessary
881 artifacts returning either success or failure.
882 </para>
883
884 <para>
885 As previously mentioned, an artifact can cover more than one task.
886 For example, it is pointless to obtain a compiler if you
887 already have the compiled binary.
888 To handle this, BitBake calls the
889 <link linkend='var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>
890 function for each successful setscene task to know whether or not it needs
891 to obtain the dependencies of that task.
892 </para>
893
894 <para>
895 Finally, after all the setscene tasks have executed, BitBake calls the
896 function listed in
897 <link linkend='var-BB_SETSCENE_VERIFY_FUNCTION'><filename>BB_SETSCENE_VERIFY_FUNCTION</filename></link>
898 with the list of tasks BitBake thinks has been "covered".
899 The metadata can then ensure that this list is correct and can
900 inform BitBake that it wants specific tasks to be run regardless
901 of the setscene result.
902 </para>
903
904 <para>
905 You can find more information on setscene metadata in the
906 "<link linkend='task-checksums-and-setscene'>Task Checksums and Setscene</link>"
907 section.
908 </para>
909 </section>
910</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
new file mode 100644
index 0000000000..0dff736dea
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
@@ -0,0 +1,738 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter>
5<title>File Download Support</title>
6
7 <para>
8 BitBake's fetch module is a standalone piece of library code
9 that deals with the intricacies of downloading source code
10 and files from remote systems.
11 Fetching source code is one of the cornerstones of building software.
12 As such, this module forms an important part of BitBake.
13 </para>
14
15 <para>
16 The current fetch module is called "fetch2" and refers to the
17 fact that it is the second major version of the API.
18 The original version is obsolete and has been removed from the codebase.
19 Thus, in all cases, "fetch" refers to "fetch2" in this
20 manual.
21 </para>
22
23 <section id='the-download-fetch'>
24 <title>The Download (Fetch)</title>
25
26 <para>
27 BitBake takes several steps when fetching source code or files.
28 The fetcher codebase deals with two distinct processes in order:
29 obtaining the files from somewhere (cached or otherwise)
30 and then unpacking those files into a specific location and
31 perhaps in a specific way.
32 Getting and unpacking the files is often optionally followed
33 by patching.
34 Patching, however, is not covered by this module.
35 </para>
36
37 <para>
38 The code to execute the first part of this process, a fetch,
39 looks something like the following:
40 <literallayout class='monospaced'>
41 src_uri = (d.getVar('SRC_URI', True) or "").split()
42 fetcher = bb.fetch2.Fetch(src_uri, d)
43 fetcher.download()
44 </literallayout>
45 This code sets up an instance of the fetch class.
46 The instance uses a space-separated list of URLs from the
47 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
48 variable and then calls the <filename>download</filename>
49 method to download the files.
50 </para>
51
52 <para>
53 The instantiation of the fetch class is usually followed by:
54 <literallayout class='monospaced'>
55 rootdir = l.getVar('WORKDIR', True)
56 fetcher.unpack(rootdir)
57 </literallayout>
58 This code unpacks the downloaded files to the
59 specified by <filename>WORKDIR</filename>.
60 <note>
61 For convenience, the naming in these examples matches
62 the variables used by OpenEmbedded.
63 If you want to see the above code in action, examine
64 the OpenEmbedded class file <filename>base.bbclass</filename>.
65 </note>
66 The <filename>SRC_URI</filename> and <filename>WORKDIR</filename>
67 variables are not hardcoded into the fetcher, since those fetcher
68 methods can be (and are) called with different variable names.
69 In OpenEmbedded for example, the shared state (sstate) code uses
70 the fetch module to fetch the sstate files.
71 </para>
72
73 <para>
74 When the <filename>download()</filename> method is called,
75 BitBake tries to resolve the URLs by looking for source files
76 in a specific search order:
77 <itemizedlist>
78 <listitem><para><emphasis>Pre-mirror Sites:</emphasis>
79 BitBake first uses pre-mirrors to try and find source files.
80 These locations are defined using the
81 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
82 variable.
83 </para></listitem>
84 <listitem><para><emphasis>Source URI:</emphasis>
85 If pre-mirrors fail, BitBake uses the original URL (e.g from
86 <filename>SRC_URI</filename>).
87 </para></listitem>
88 <listitem><para><emphasis>Mirror Sites:</emphasis>
89 If fetch failures occur, BitBake next uses mirror locations as
90 defined by the
91 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
92 variable.
93 </para></listitem>
94 </itemizedlist>
95 </para>
96
97 <para>
98 For each URL passed to the fetcher, the fetcher
99 calls the submodule that handles that particular URL type.
100 This behavior can be the source of some confusion when you
101 are providing URLs for the <filename>SRC_URI</filename>
102 variable.
103 Consider the following two URLs:
104 <literallayout class='monospaced'>
105 http://git.yoctoproject.org/git/poky;protocol=git
106 git://git.yoctoproject.org/git/poky;protocol=http
107 </literallayout>
108 In the former case, the URL is passed to the
109 <filename>wget</filename> fetcher, which does not
110 understand "git".
111 Therefore, the latter case is the correct form since the
112 Git fetcher does know how to use HTTP as a transport.
113 </para>
114
115 <para>
116 Here are some examples that show commonly used mirror
117 definitions:
118 <literallayout class='monospaced'>
119 PREMIRRORS ?= "\
120 bzr://.*/.* http://somemirror.org/sources/ \n \
121 cvs://.*/.* http://somemirror.org/sources/ \n \
122 git://.*/.* http://somemirror.org/sources/ \n \
123 hg://.*/.* http://somemirror.org/sources/ \n \
124 osc://.*/.* http://somemirror.org/sources/ \n \
125 p4://.*/.* http://somemirror.org/sources/ \n \
126 svn://.*/.* http://somemirror.org/sources/ \n"
127
128 MIRRORS =+ "\
129 ftp://.*/.* http://somemirror.org/sources/ \n \
130 http://.*/.* http://somemirror.org/sources/ \n \
131 https://.*/.* http://somemirror.org/sources/ \n"
132 </literallayout>
133 It is useful to note that BitBake supports
134 cross-URLs.
135 It is possible to mirror a Git repository on an HTTP
136 server as a tarball.
137 This is what the <filename>git://</filename> mapping in
138 the previous example does.
139 </para>
140
141 <para>
142 Since network accesses are slow, Bitbake maintains a
143 cache of files downloaded from the network.
144 Any source files that are not local (i.e.
145 downloaded from the Internet) are placed into the download
146 directory, which is specified by the
147 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
148 variable.
149 </para>
150
151 <para>
152 File integrity is of key importance for reproducing builds.
153 For non-local archive downloads, the fetcher code can verify
154 SHA-256 and MD5 checksums to ensure the archives have been
155 downloaded correctly.
156 You can specify these checksums by using the
157 <filename>SRC_URI</filename> variable with the appropriate
158 varflags as follows:
159 <literallayout class='monospaced'>
160 SRC_URI[md5sum] = "value"
161 SRC_URI[sha256sum] = "value"
162 </literallayout>
163 You can also specify the checksums as parameters on the
164 <filename>SRC_URI</filename> as shown below:
165 <literallayout class='monospaced'>
166 SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
167 </literallayout>
168 If multiple URIs exist, you can specify the checksums either
169 directly as in the previous example, or you can name the URLs.
170 The following syntax shows how you name the URIs:
171 <literallayout class='monospaced'>
172 SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
173 SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
174 </literallayout>
175 After a file has been downloaded and has had its checksum checked,
176 a ".done" stamp is placed in <filename>DL_DIR</filename>.
177 BitBake uses this stamp during subsequent builds to avoid
178 downloading or comparing a checksum for the file again.
179 <note>
180 It is assumed that local storage is safe from data corruption.
181 If this were not the case, there would be bigger issues to worry about.
182 </note>
183 </para>
184
185 <para>
186 If
187 <link linkend='var-BB_STRICT_CHECKSUM'><filename>BB_STRICT_CHECKSUM</filename></link>
188 is set, any download without a checksum triggers an
189 error message.
190 The
191 <link linkend='var-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link>
192 variable can be used to make any attempted network access a fatal
193 error, which is useful for checking that mirrors are complete
194 as well as other things.
195 </para>
196 </section>
197
198 <section id='bb-the-unpack'>
199 <title>The Unpack</title>
200
201 <para>
202 The unpack process usually immediately follows the download.
203 For all URLs except Git URLs, BitBake uses the common
204 <filename>unpack</filename> method.
205 </para>
206
207 <para>
208 A number of parameters exist that you can specify within the
209 URL to govern the behavior of the unpack stage:
210 <itemizedlist>
211 <listitem><para><emphasis>unpack:</emphasis>
212 Controls whether the URL components are unpacked.
213 If set to "1", which is the default, the components
214 are unpacked.
215 If set to "0", the unpack stage leaves the file alone.
216 This parameter is useful when you want an archive to be
217 copied in and not be unpacked.
218 </para></listitem>
219 <listitem><para><emphasis>dos:</emphasis>
220 Applies to <filename>.zip</filename> and
221 <filename>.jar</filename> files and specifies whether to
222 use DOS line ending conversion on text files.
223 </para></listitem>
224 <listitem><para><emphasis>basepath:</emphasis>
225 Instructs the unpack stage to strip the specified
226 directories from the source path when unpacking.
227 </para></listitem>
228 <listitem><para><emphasis>subdir:</emphasis>
229 Unpacks the specific URL to the specified subdirectory
230 within the root directory.
231 </para></listitem>
232 </itemizedlist>
233 The unpack call automatically decompresses and extracts files
234 with ".Z", ".z", ".gz", ".xz", ".zip", ".jar", ".ipk", ".rpm".
235 ".srpm", ".deb" and ".bz2" extensions as well as various combinations
236 of tarball extensions.
237 </para>
238
239 <para>
240 As mentioned, the Git fetcher has its own unpack method that
241 is optimized to work with Git trees.
242 Basically, this method works by cloning the tree into the final
243 directory.
244 The process is completed using references so that there is
245 only one central copy of the Git metadata needed.
246 </para>
247 </section>
248
249 <section id='bb-fetchers'>
250 <title>Fetchers</title>
251
252 <para>
253 As mentioned earlier, the URL prefix determines which
254 fetcher submodule BitBake uses.
255 Each submodule can support different URL parameters,
256 which are described in the following sections.
257 </para>
258
259 <section id='local-file-fetcher'>
260 <title>Local file fetcher (<filename>file://</filename>)</title>
261
262 <para>
263 This submodule handles URLs that begin with
264 <filename>file://</filename>.
265 The filename you specify within the URL can be
266 either an absolute or relative path to a file.
267 If the filename is relative, the contents of the
268 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
269 variable is used in the same way
270 <filename>PATH</filename> is used to find executables.
271 Failing that,
272 <link linkend='var-FILESDIR'><filename>FILESDIR</filename></link>
273 is used to find the appropriate relative file.
274 <note>
275 <filename>FILESDIR</filename> is deprecated and can
276 be replaced with <filename>FILESPATH</filename>.
277 Because <filename>FILESDIR</filename> is likely to be
278 removed, you should not use this variable in any new code.
279 </note>
280 If the file cannot be found, it is assumed that it is available in
281 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
282 by the time the <filename>download()</filename> method is called.
283 </para>
284
285 <para>
286 If you specify a directory, the entire directory is
287 unpacked.
288 </para>
289
290 <para>
291 Here are a couple of example URLs, the first relative and
292 the second absolute:
293 <literallayout class='monospaced'>
294 SRC_URI = "file://relativefile.patch"
295 SRC_URI = "file:///Users/ich/very_important_software"
296 </literallayout>
297 </para>
298 </section>
299
300 <section id='http-ftp-fetcher'>
301 <title>HTTP/FTP wget fetcher (<filename>http://</filename>, <filename>ftp://</filename>, <filename>https://</filename>)</title>
302
303 <para>
304 This fetcher obtains files from web and FTP servers.
305 Internally, the fetcher uses the wget utility.
306 </para>
307
308 <para>
309 The executable and parameters used are specified by the
310 <filename>FETCHCMD_wget</filename> variable, which defaults
311 to sensible values.
312 The fetcher supports a parameter "downloadfilename" that
313 allows the name of the downloaded file to be specified.
314 Specifying the name of the downloaded file is useful
315 for avoiding collisions in
316 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
317 when dealing with multiple files that have the same name.
318 </para>
319
320 <para>
321 Some example URLs are as follows:
322 <literallayout class='monospaced'>
323 SRC_URI = "http://oe.handhelds.org/not_there.aac"
324 SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
325 SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
326 </literallayout>
327 </para>
328 </section>
329
330 <section id='cvs-fetcher'>
331 <title>CVS fetcher (<filename>(cvs://</filename>)</title>
332
333 <para>
334 This submodule handles checking out files from the
335 CVS version control system.
336 You can configure it using a number of different variables:
337 <itemizedlist>
338 <listitem><para><emphasis><filename>FETCHCMD_cvs</filename>:</emphasis>
339 The name of the executable to use when running
340 the <filename>cvs</filename> command.
341 This name is usually "cvs".
342 </para></listitem>
343 <listitem><para><emphasis><filename>SRCDATE</filename>:</emphasis>
344 The date to use when fetching the CVS source code.
345 A special value of "now" causes the checkout to
346 be updated on every build.
347 </para></listitem>
348 <listitem><para><emphasis><filename>CVSDIR</filename>:</emphasis>
349 Specifies where a temporary checkout is saved.
350 The location is often <filename>DL_DIR/cvs</filename>.
351 </para></listitem>
352 <listitem><para><emphasis><filename>CVS_PROXY_HOST</filename>:</emphasis>
353 The name to use as a "proxy=" parameter to the
354 <filename>cvs</filename> command.
355 </para></listitem>
356 <listitem><para><emphasis><filename>CVS_PROXY_PORT</filename>:</emphasis>
357 The port number to use as a "proxyport=" parameter to
358 the <filename>cvs</filename> command.
359 </para></listitem>
360 </itemizedlist>
361 As well as the standard username and password URL syntax,
362 you can also configure the fetcher with various URL parameters:
363 </para>
364
365 <para>
366 The supported parameters are as follows:
367 <itemizedlist>
368 <listitem><para><emphasis>"method":</emphasis>
369 The protocol over which to communicate with the CVS server.
370 By default, this protocol is "pserver".
371 If "method" is set to "ext", BitBake examines the
372 "rsh" parameter and sets <filename>CVS_RSH</filename>.
373 You can use "dir" for local directories.
374 </para></listitem>
375 <listitem><para><emphasis>"module":</emphasis>
376 Specifies the module to check out.
377 You must supply this parameter.
378 </para></listitem>
379 <listitem><para><emphasis>"tag":</emphasis>
380 Describes which CVS TAG should be used for
381 the checkout.
382 By default, the TAG is empty.
383 </para></listitem>
384 <listitem><para><emphasis>"date":</emphasis>
385 Specifies a date.
386 If no "date" is specified, the
387 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
388 of the configuration is used to checkout a specific date.
389 The special value of "now" causes the checkout to be
390 updated on every build.
391 </para></listitem>
392 <listitem><para><emphasis>"localdir":</emphasis>
393 Used to rename the module.
394 Effectively, you are renaming the output directory
395 to which the module is unpacked.
396 You are forcing the module into a special
397 directory relative to <filename>CVSDIR</filename>.
398 </para></listitem>
399 <listitem><para><emphasis>"rsh"</emphasis>
400 Used in conjunction with the "method" parameter.
401 </para></listitem>
402 <listitem><para><emphasis>"scmdata":</emphasis>
403 Causes the CVS metadata to be maintained in the tarball
404 the fetcher creates when set to "keep".
405 The tarball is expanded into the work directory.
406 By default, the CVS metadata is removed.
407 </para></listitem>
408 <listitem><para><emphasis>"fullpath":</emphasis>
409 Controls whether the resulting checkout is at the
410 module level, which is the default, or is at deeper
411 paths.
412 </para></listitem>
413 <listitem><para><emphasis>"norecurse":</emphasis>
414 Causes the fetcher to only checkout the specified
415 directory with no recurse into any subdirectories.
416 </para></listitem>
417 <listitem><para><emphasis>"port":</emphasis>
418 The port to which the CVS server connects.
419 </para></listitem>
420 </itemizedlist>
421 Some example URLs are as follows:
422 <literallayout class='monospaced'>
423 SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
424 SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
425 </literallayout>
426 </para>
427 </section>
428
429 <section id='svn-fetcher'>
430 <title>Subversion (SVN) Fetcher (<filename>svn://</filename>)</title>
431
432 <para>
433 This fetcher submodule fetches code from the
434 Subversion source control system.
435 The executable used is specified by
436 <filename>FETCHCMD_svn</filename>, which defaults
437 to "svn".
438 The fetcher's temporary working directory is set
439 by <filename>SVNDIR</filename>, which is usually
440 <filename>DL_DIR/svn</filename>.
441 </para>
442
443 <para>
444 The supported parameters are as follows:
445 <itemizedlist>
446 <listitem><para><emphasis>"module":</emphasis>
447 The name of the svn module to checkout.
448 You must provide this parameter.
449 You can think of this parameter as the top-level
450 directory of the repository data you want.
451 </para></listitem>
452 <listitem><para><emphasis>"protocol":</emphasis>
453 The protocol to use, which defaults to "svn".
454 Other options are "svn+ssh" and "rsh".
455 For "rsh", the "rsh" parameter is also used.
456 </para></listitem>
457 <listitem><para><emphasis>"rev":</emphasis>
458 The revision of the source code to checkout.
459 </para></listitem>
460 <listitem><para><emphasis>"date":</emphasis>
461 The date of the source code to checkout.
462 Specific revisions are generally much safer to checkout
463 rather than by date as they do not involve timezones
464 (e.g. they are much more deterministic).
465 </para></listitem>
466 <listitem><para><emphasis>"scmdata":</emphasis>
467 Causes the “.svn†directories to be available during
468 compile-time when set to "keep".
469 By default, these directories are removed.
470 </para></listitem>
471 <listitem><para><emphasis>"transportuser":</emphasis>
472 When required, sets the username for the transport.
473 By default, this parameter is empty.
474 The transport username is different than the username
475 used in the main URL, which is passed to the subversion
476 command.
477 </para></listitem>
478 </itemizedlist>
479 Following are two examples using svn:
480 <literallayout class='monospaced'>
481 SRC_URI = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
482 SRC_URI = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
483 </literallayout>
484 </para>
485 </section>
486
487 <section id='git-fetcher'>
488 <title>Git Fetcher (<filename>git://</filename>)</title>
489
490 <para>
491 This fetcher submodule fetches code from the Git
492 source control system.
493 The fetcher works by creating a bare clone of the
494 remote into <filename>GITDIR</filename>, which is
495 usually <filename>DL_DIR/git2</filename>.
496 This bare clone is then cloned into the work directory during the
497 unpack stage when a specific tree is checked out.
498 This is done using alternates and by reference to
499 minimize the amount of duplicate data on the disk and
500 make the unpack process fast.
501 The executable used can be set with
502 <filename>FETCHCMD_git</filename>.
503 </para>
504
505 <para>
506 This fetcher supports the following parameters:
507 <itemizedlist>
508 <listitem><para><emphasis>"protocol":</emphasis>
509 The protocol used to fetch the files.
510 The default is "git" when a hostname is set.
511 If a hostname is not set, the Git protocol is "file".
512 You can also use "http", "https", "ssh" and "rsync".
513 </para></listitem>
514 <listitem><para><emphasis>"nocheckout":</emphasis>
515 Tells the fetcher to not checkout source code when
516 unpacking when set to "1".
517 Set this option for the URL where there is a custom
518 routine to checkout code.
519 The default is "0".
520 </para></listitem>
521 <listitem><para><emphasis>"rebaseable":</emphasis>
522 Indicates that the upstream Git repository can be rebased.
523 You should set this parameter to "1" if
524 revisions can become detached from branches.
525 In this case, the source mirror tarball is done per
526 revision, which has a loss of efficiency.
527 Rebasing the upstream Git repository could cause the
528 current revision to disappear from the upstream repository.
529 This option reminds the fetcher to preserve the local cache
530 carefully for future use.
531 The default value for this parameter is "0".
532 </para></listitem>
533 <listitem><para><emphasis>"nobranch":</emphasis>
534 Tells the fetcher to not check the SHA validation
535 for the branch when set to "1".
536 The default is "0".
537 Set this option for the recipe that refers to
538 the commit that is valid for a tag instead of
539 the branch.
540 </para></listitem>
541 <listitem><para><emphasis>"bareclone":</emphasis>
542 Tells the fetcher to clone a bare clone into the
543 destination directory without checking out a working tree.
544 Only the raw Git metadata is provided.
545 This parameter implies the "nocheckout" parameter as well.
546 </para></listitem>
547 <listitem><para><emphasis>"branch":</emphasis>
548 The branch(es) of the Git tree to clone.
549 If unset, this is assumed to be "master".
550 The number of branch parameters much match the number of
551 name parameters.
552 </para></listitem>
553 <listitem><para><emphasis>"rev":</emphasis>
554 The revision to use for the checkout.
555 The default is "master".
556 </para></listitem>
557 <listitem><para><emphasis>"tag":</emphasis>
558 Specifies a tag to use for the checkout.
559 To correctly resolve tags, BitBake must access the
560 network.
561 For that reason, tags are often not used.
562 As far as Git is concerned, the "tag" parameter behaves
563 effectively the same as the "rev" parameter.
564 </para></listitem>
565 <listitem><para><emphasis>"subpath":</emphasis>
566 Limits the checkout to a specific subpath of the tree.
567 By default, the whole tree is checked out.
568 </para></listitem>
569 <listitem><para><emphasis>"destsuffix":</emphasis>
570 The name of the path in which to place the checkout.
571 By default, the path is <filename>git/</filename>.
572 </para></listitem>
573 </itemizedlist>
574 Here are some example URLs:
575 <literallayout class='monospaced'>
576 SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
577 SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
578 </literallayout>
579 </para>
580 </section>
581
582 <section id='gitsm-fetcher'>
583 <title>Git Submodule Fetcher (<filename>gitsm://</filename>)</title>
584
585 <para>
586 This fetcher submodule inherits from the
587 <link linkend='git-fetcher'>Git fetcher</link> and extends
588 that fetcher's behavior by fetching a repository's submodules.
589 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
590 is passed to the Git fetcher as described in the
591 "<link linkend='git-fetcher'>Git Fetcher (<filename>git://</filename>)</link>"
592 section.
593 <note>
594 <title>Notes and Warnings</title>
595 <para>
596 You must clean a recipe when switching between
597 '<filename>git://</filename>' and
598 '<filename>gitsm://</filename>' URLs.
599 </para>
600
601 <para>
602 The Git Submodules fetcher is not a complete fetcher
603 implementation.
604 The fetcher has known issues where it does not use the
605 normal source mirroring infrastructure properly.
606 </para>
607 </note>
608 </para>
609 </section>
610
611 <section id='clearcase-fetcher'>
612 <title>ClearCase Fetcher (<filename>ccrc://</filename>)</title>
613
614 <para>
615 This fetcher submodule fetches code from a
616 <ulink url='http://en.wikipedia.org/wiki/Rational_ClearCase'>ClearCase</ulink>
617 repository.
618 </para>
619
620 <para>
621 To use this fetcher, make sure your recipe has proper
622 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
623 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>, and
624 <link linkend='var-PV'><filename>PV</filename></link> settings.
625 Here is an example:
626 <literallayout class='monospaced'>
627 SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
628 SRCREV = "EXAMPLE_CLEARCASE_TAG"
629 PV = "${@d.getVar("SRCREV").replace("/", "+")}"
630 </literallayout>
631 The fetcher uses the <filename>rcleartool</filename> or
632 <filename>cleartool</filename> remote client, depending on
633 which one is available.
634 </para>
635
636 <para>
637 Following are options for the <filename>SRC_URI</filename>
638 statement:
639 <itemizedlist>
640 <listitem><para><emphasis><filename>vob</filename></emphasis>:
641 The name, which must include the
642 prepending "/" character, of the ClearCase VOB.
643 This option is required.
644 </para></listitem>
645 <listitem><para><emphasis><filename>module</filename></emphasis>:
646 The module, which must include the
647 prepending "/" character, in the selected VOB
648 The <filename>module</filename> and <filename>vob</filename>
649 options are combined to create the following load rule in
650 the view config spec:
651 <literallayout class='monospaced'>
652 load &lt;vob&gt;&lt;module&gt;
653 </literallayout>
654 </para></listitem>
655 <listitem><para><emphasis><filename>proto</filename></emphasis>:
656 The protocol, which can be either <filename>http</filename> or
657 <filename>https</filename>.
658 </para></listitem>
659 </itemizedlist>
660 </para>
661
662 <para>
663 By default, the fetcher creates a configuration specification.
664 If you want this specification written to an area other than the default,
665 use the <filename>CCASE_CUSTOM_CONFIG_SPEC</filename> variable
666 in your recipe to define where the specification is written.
667 <note>
668 the <filename>SRCREV</filename> loses its functionality if you
669 specify this variable.
670 However, <filename>SRCREV</filename> is still used to label the
671 archive after a fetch even though it does not define what is
672 fetched.
673 </note>
674 </para>
675
676 <para>
677 Here are a couple of other behaviors worth mentioning:
678 <itemizedlist>
679 <listitem><para>
680 When using <filename>cleartool</filename>, the login of
681 <filename>cleartool</filename> is handled by the system.
682 The login require no special steps.
683 </para></listitem>
684 <listitem><para>
685 In order to use <filename>rcleartool</filename> with authenticated
686 users, an "rcleartool login" is necessary before using the fetcher.
687 </para></listitem>
688 </itemizedlist>
689 </para>
690 </section>
691
692 <section id='other-fetchers'>
693 <title>Other Fetchers</title>
694
695 <para>
696 Fetch submodules also exist for the following:
697 <itemizedlist>
698 <listitem><para>
699 Bazaar (<filename>bzr://</filename>)
700 </para></listitem>
701 <listitem><para>
702 Perforce (<filename>p4://</filename>)
703 </para></listitem>
704 <listitem><para>
705 Trees using Git Annex (<filename>gitannex://</filename>)
706 </para></listitem>
707 <listitem><para>
708 Secure FTP (<filename>sftp://</filename>)
709 </para></listitem>
710 <listitem><para>
711 Secure Shell (<filename>ssh://</filename>)
712 </para></listitem>
713 <listitem><para>
714 Repo (<filename>repo://</filename>)
715 </para></listitem>
716 <listitem><para>
717 OSC (<filename>osc://</filename>)
718 </para></listitem>
719 <listitem><para>
720 Mercurial (<filename>hg://</filename>)
721 </para></listitem>
722 </itemizedlist>
723 No documentation currently exists for these lesser used
724 fetcher submodules.
725 However, you might find the code helpful and readable.
726 </para>
727 </section>
728 </section>
729
730 <section id='auto-revisions'>
731 <title>Auto Revisions</title>
732
733 <para>
734 We need to document <filename>AUTOREV</filename> and
735 <filename>SRCREV_FORMAT</filename> here.
736 </para>
737 </section>
738</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
new file mode 100644
index 0000000000..4ce7ed9f8c
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
@@ -0,0 +1,506 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='hello-world-example'>
5 <title>Hello World Example</title>
6
7 <section id='bitbake-hello-world'>
8 <title>BitBake Hello World</title>
9
10 <para>
11 The simplest example commonly used to demonstrate any new
12 programming language or tool is the
13 "<ulink url="http://en.wikipedia.org/wiki/Hello_world_program">Hello World</ulink>"
14 example.
15 This appendix demonstrates, in tutorial form, Hello
16 World within the context of BitBake.
17 The tutorial describes how to create a new project
18 and the applicable metadata files necessary to allow
19 BitBake to build it.
20 </para>
21 </section>
22
23 <section id='example-obtaining-bitbake'>
24 <title>Obtaining BitBake</title>
25
26 <para>
27 See the
28 "<link linkend='obtaining-bitbake'>Obtaining BitBake</link>"
29 section for information on how to obtain BitBake.
30 Once you have the source code on your machine, the BitBake directory
31 appears as follows:
32 <literallayout class='monospaced'>
33 $ ls -al
34 total 100
35 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 .
36 drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 ..
37 -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
38 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin
39 drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build
40 -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
41 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes
42 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf
43 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib
44 -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
45 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc
46 -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore
47 -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
48 drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib
49 -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in
50 -rwxrwxr-x. 1 wmat wmat 3195 Jan 31 11:57 setup.py
51 -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO
52 </literallayout>
53 </para>
54
55 <para>
56 At this point, you should have BitBake cloned to
57 a directory that matches the previous listing except for
58 dates and user names.
59 </para>
60 </section>
61
62 <section id='setting-up-the-bitbake-environment'>
63 <title>Setting Up the BitBake Environment</title>
64
65 <para>
66 First, you need to be sure that you can run BitBake.
67 Set your working directory to where your local BitBake
68 files are and run the following command:
69 <literallayout class='monospaced'>
70 $ ./bin/bitbake --version
71 BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
72 </literallayout>
73 The console output tells you what version you are running.
74 </para>
75
76 <para>
77 The recommended method to run BitBake is from a directory of your
78 choice.
79 To be able to run BitBake from any directory, you need to add the
80 executable binary to your binary to your shell's environment
81 <filename>PATH</filename> variable.
82 First, look at your current <filename>PATH</filename> variable
83 by entering the following:
84 <literallayout class='monospaced'>
85 $ echo $PATH
86 </literallayout>
87 Next, add the directory location for the BitBake binary to the
88 <filename>PATH</filename>.
89 Here is an example that adds the
90 <filename>/home/scott-lenovo/bitbake/bin</filename> directory
91 to the front of the <filename>PATH</filename> variable:
92 <literallayout class='monospaced'>
93 $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
94 </literallayout>
95 You should now be able to enter the <filename>bitbake</filename>
96 command from the command line while working from any directory.
97 </para>
98 </section>
99
100 <section id='the-hello-world-example'>
101 <title>The Hello World Example</title>
102
103 <para>
104 The overall goal of this exercise is to build a
105 complete "Hello World" example utilizing task and layer
106 concepts.
107 Because this is how modern projects such as OpenEmbedded and
108 the Yocto Project utilize BitBake, the example
109 provides an excellent starting point for understanding
110 BitBake.
111 </para>
112
113 <para>
114 To help you understand how to use BitBake to build targets,
115 the example starts with nothing but the <filename>bitbake</filename>
116 command, which causes BitBake to fail and report problems.
117 The example progresses by adding pieces to the build to
118 eventually conclude with a working, minimal "Hello World"
119 example.
120 </para>
121
122 <para>
123 While every attempt is made to explain what is happening during
124 the example, the descriptions cannot cover everything.
125 You can find further information throughout this manual.
126 Also, you can actively participate in the
127 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'></ulink>
128 discussion mailing list about the BitBake build tool.
129 </para>
130
131 <note>
132 This example was inspired by and drew heavily from these sources:
133 <itemizedlist>
134 <listitem><para>
135 <ulink url="http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html">Mailing List post - The BitBake equivalent of "Hello, World!"</ulink>
136 </para></listitem>
137 <listitem><para>
138 <ulink url="http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/">Hambedded Linux blog post - From Bitbake Hello World to an Image</ulink>
139 </para></listitem>
140 </itemizedlist>
141 </note>
142
143 <para>
144 As stated earlier, the goal of this example
145 is to eventually compile "Hello World".
146 However, it is unknown what BitBake needs and what you have
147 to provide in order to achieve that goal.
148 Recall that BitBake utilizes three types of metadata files:
149 <link linkend='configuration-files'>Configuration Files</link>,
150 <link linkend='classes'>Classes</link>, and
151 <link linkend='recipes'>Recipes</link>.
152 But where do they go?
153 How does BitBake find them?
154 BitBake's error messaging helps you answer these types of questions
155 and helps you better understand exactly what is going on.
156 </para>
157
158 <para>
159 Following is the complete "Hello World" example.
160 </para>
161
162 <orderedlist>
163 <listitem><para><emphasis>Create a Project Directory:</emphasis>
164 First, set up a directory for the "Hello World" project.
165 Here is how you can do so in your home directory:
166 <literallayout class='monospaced'>
167 $ mkdir ~/hello
168 $ cd ~/hello
169 </literallayout>
170 This is the directory that BitBake will use to do all of
171 its work.
172 You can use this directory to keep all the metafiles needed
173 by BitBake.
174 Having a project directory is a good way to isolate your
175 project.
176 </para></listitem>
177 <listitem><para><emphasis>Run Bitbake:</emphasis>
178 At this point, you have nothing but a project directory.
179 Run the <filename>bitbake</filename> command and see what
180 it does:
181 <literallayout class='monospaced'>
182 $ bitbake
183 The BBPATH variable is not set and bitbake did not
184 find a conf/bblayers.conf file in the expected location.
185 Maybe you accidentally invoked bitbake from the wrong directory?
186 DEBUG: Removed the following variables from the environment:
187 GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
188 GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
189 XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
190 MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
191 GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
192 XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
193 _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
194 UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
195 </literallayout>
196 The majority of this output is specific to environment variables
197 that are not directly relevant to BitBake.
198 However, the very first message regarding the
199 <filename>BBPATH</filename> variable and the
200 <filename>conf/bblayers.conf</filename> file
201 is relevant.</para>
202 <para>
203 When you run BitBake, it begins looking for metadata files.
204 The
205 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
206 variable is what tells BitBake where to look for those files.
207 <filename>BBPATH</filename> is not set and you need to set it.
208 Without <filename>BBPATH</filename>, Bitbake cannot
209 find any configuration files (<filename>.conf</filename>)
210 or recipe files (<filename>.bb</filename>) at all.
211 BitBake also cannot find the <filename>bitbake.conf</filename>
212 file.
213 </para></listitem>
214 <listitem><para><emphasis>Setting <filename>BBPATH</filename>:</emphasis>
215 For this example, you can set <filename>BBPATH</filename>
216 in the same manner that you set <filename>PATH</filename>
217 earlier in the appendix.
218 You should realize, though, that it is much more flexible to set the
219 <filename>BBPATH</filename> variable up in a configuration
220 file for each project.</para>
221 <para>From your shell, enter the following commands to set and
222 export the <filename>BBPATH</filename> variable:
223 <literallayout class='monospaced'>
224 $ BBPATH="&lt;projectdirectory&gt;"
225 $ export BBPATH
226 </literallayout>
227 Use your actual project directory in the command.
228 BitBake uses that directory to find the metadata it needs for
229 your project.
230 <note>
231 When specifying your project directory, do not use the
232 tilde ("~") character as BitBake does not expand that character
233 as the shell would.
234 </note>
235 </para></listitem>
236 <listitem><para><emphasis>Run Bitbake:</emphasis>
237 Now that you have <filename>BBPATH</filename> defined, run
238 the <filename>bitbake</filename> command again:
239 <literallayout class='monospaced'>
240 $ bitbake
241 ERROR: Traceback (most recent call last):
242 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
243 return func(fn, *args)
244 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
245 return bb.parse.handle(fn, data, include)
246 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
247 return h['handle'](fn, data, include)
248 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
249 abs_fn = resolve_file(fn, data)
250 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
251 raise IOError("file %s not found in %s" % (fn, bbpath))
252 IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
253
254 ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
255 </literallayout>
256 This sample output shows that BitBake could not find the
257 <filename>conf/bitbake.conf</filename> file in the project
258 directory.
259 This file is the first thing BitBake must find in order
260 to build a target.
261 And, since the project directory for this example is
262 empty, you need to provide a <filename>conf/bitbake.conf</filename>
263 file.
264 </para></listitem>
265 <listitem><para><emphasis>Creating <filename>conf/bitbake.conf</filename>:</emphasis>
266 The <filename>conf/bitbake.conf</filename> includes a number of
267 configuration variables BitBake uses for metadata and recipe
268 files.
269 For this example, you need to create the file in your project directory
270 and define some key BitBake variables.
271 For more information on the <filename>bitbake.conf</filename>,
272 see
273 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#an-overview-of-bitbakeconf'></ulink>
274 </para>
275 <para>Use the following commands to create the <filename>conf</filename>
276 directory in the project directory:
277 <literallayout class='monospaced'>
278 $ mkdir conf
279 </literallayout>
280 From within the <filename>conf</filename> directory, use
281 some editor to create the <filename>bitbake.conf</filename>
282 so that it contains the following:
283 <literallayout class='monospaced'>
284 TMPDIR = "${<link linkend='var-TOPDIR'>TOPDIR</link>}/tmp"
285 <link linkend='var-CACHE'>CACHE</link> = "${TMPDIR}/cache"
286 <link linkend='var-STAMP'>STAMP</link> = "${TMPDIR}/stamps"
287 <link linkend='var-T'>T</link> = "${TMPDIR}/work"
288 <link linkend='var-B'>B</link> = "${TMPDIR}"
289 </literallayout>
290 The <filename>TMPDIR</filename> variable establishes a directory
291 that BitBake uses for build output and intermediate files (other
292 than the cached information used by the
293 <link linkend='setscene'>Setscene</link> process.
294 Here, the <filename>TMPDIR</filename> directory is set to
295 <filename>hello/tmp</filename>.
296 <note><title>Tip</title>
297 You can always safely delete the <filename>tmp</filename>
298 directory in order to rebuild a BitBake target.
299 The build process creates the directory for you
300 when you run BitBake.
301 </note></para>
302 <para>For information about each of the other variables defined in this
303 example, click on the links to take you to the definitions in
304 the glossary.
305 </para></listitem>
306 <listitem><para><emphasis>Run Bitbake:</emphasis>
307 After making sure that the <filename>conf/bitbake.conf</filename>
308 file exists, you can run the <filename>bitbake</filename>
309 command again:
310 <literallayout class='monospaced'>
311$ bitbake
312ERROR: Traceback (most recent call last):
313 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
314 return func(fn, *args)
315 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
316 bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
317 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
318 include(fn, file, lineno, d, "inherit")
319 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
320 raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
321ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
322
323ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
324 </literallayout>
325 In the sample output, BitBake could not find the
326 <filename>classes/base.bbclass</filename> file.
327 You need to create that file next.
328 </para></listitem>
329 <listitem><para><emphasis>Creating <filename>classes/base.bbclass</filename>:</emphasis>
330 BitBake uses class files to provide common code and functionality.
331 The minimally required class for BitBake is the
332 <filename>classes/base.bbclass</filename> file.
333 The <filename>base</filename> class is implicitly inherited by
334 every recipe.
335 BitBake looks for the class in the <filename>classes</filename>
336 directory of the project (i.e <filename>hello/classes</filename>
337 in this example).
338 </para>
339 <para>Create the <filename>classes</filename> directory as follows:
340 <literallayout class='monospaced'>
341 $ cd $HOME/hello
342 $ mkdir classes
343 </literallayout>
344 Move to the <filename>classes</filename> directory and then
345 create the <filename>base.bbclass</filename> file by inserting
346 this single line:
347 <literallayout class='monospaced'>
348 addtask build
349 </literallayout>
350 The minimal task that BitBake runs is the
351 <filename>do_build</filename> task.
352 This is all the example needs in order to build the project.
353 Of course, the <filename>base.bbclass</filename> can have much
354 more depending on which build environments BitBake is
355 supporting.
356 For more information on the <filename>base.bbclass</filename> file,
357 you can look at
358 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#tasks'></ulink>.
359 </para></listitem>
360 <listitem><para><emphasis>Run Bitbake:</emphasis>
361 After making sure that the <filename>classes/base.bbclass</filename>
362 file exists, you can run the <filename>bitbake</filename>
363 command again:
364 <literallayout class='monospaced'>
365 $ bitbake
366 Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
367 </literallayout>
368 BitBake is finally reporting no errors.
369 However, you can see that it really does not have anything
370 to do.
371 You need to create a recipe that gives BitBake something to do.
372 </para></listitem>
373 <listitem><para><emphasis>Creating a Layer:</emphasis>
374 While it is not really necessary for such a small example,
375 it is good practice to create a layer in which to keep your
376 code separate from the general metadata used by BitBake.
377 Thus, this example creates and uses a layer called "mylayer".
378 <note>
379 You can find additional information on adding a layer at
380 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#adding-an-example-layer'></ulink>.
381 </note>
382 </para>
383 <para>Minimally, you need a recipe file and a layer configuration
384 file in your layer.
385 The configuration file needs to be in the <filename>conf</filename>
386 directory inside the layer.
387 Use these commands to set up the layer and the <filename>conf</filename>
388 directory:
389 <literallayout class='monospaced'>
390 $ cd $HOME
391 $ mkdir mylayer
392 $ cd mylayer
393 $ mkdir conf
394 </literallayout>
395 Move to the <filename>conf</filename> directory and create a
396 <filename>layer.conf</filename> file that has the following:
397 <literallayout class='monospaced'>
398 BBPATH .= ":${<link linkend='var-LAYERDIR'>LAYERDIR</link>}"
399
400 <link linkend='var-BBFILES'>BBFILES</link> += "${LAYERDIR}/*.bb"
401
402 <link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link> += "mylayer"
403 <link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR}/"
404 </literallayout>
405 For information on these variables, click the links
406 to go to the definitions in the glossary.</para>
407 <para>You need to create the recipe file next.
408 Inside your layer at the top-level, use an editor and create
409 a recipe file named <filename>printhello.bb</filename> that
410 has the following:
411 <literallayout class='monospaced'>
412 <link linkend='var-DESCRIPTION'>DESCRIPTION</link> = "Prints Hello World"
413 <link linkend='var-PN'>PN</link> = 'printhello'
414 <link linkend='var-PV'>PV</link> = '1'
415
416 python do_build() {
417 bb.plain("********************");
418 bb.plain("* *");
419 bb.plain("* Hello, World! *");
420 bb.plain("* *");
421 bb.plain("********************");
422 }
423 </literallayout>
424 The recipe file simply provides a description of the
425 recipe, the name, version, and the <filename>do_build</filename>
426 task, which prints out "Hello World" to the console.
427 For more information on these variables, follow the links
428 to the glossary.
429 </para></listitem>
430 <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
431 Now that a BitBake target exists, run the command and provide
432 that target:
433 <literallayout class='monospaced'>
434 $ cd $HOME/hello
435 $ bitbake printhello
436 ERROR: no recipe files to build, check your BBPATH and BBFILES?
437
438 Summary: There was 1 ERROR message shown, returning a non-zero exit code.
439 </literallayout>
440 We have created the layer with the recipe and the layer
441 configuration file but it still seems that BitBake cannot
442 find the recipe.
443 BitBake needs a <filename>conf/bblayers.conf</filename> that
444 lists the layers for the project.
445 Without this file, BitBake cannot find the recipe.
446 </para></listitem>
447 <listitem><para><emphasis>Creating <filename>conf/bblayers.conf</filename>:</emphasis>
448 BitBake uses the <filename>conf/bblayers.conf</filename> file
449 to locate layers needed for the project.
450 This file must reside in the <filename>conf</filename> directory
451 of the project (i.e. <filename>hello/conf</filename> for this
452 example).</para>
453 <para>Set your working directory to the <filename>hello/conf</filename>
454 directory and then create the <filename>bblayers.conf</filename>
455 file so that it contains the following:
456 <literallayout class='monospaced'>
457 BBLAYERS ?= " \
458 /home/&lt;you&gt;/mylayer \
459 "
460 </literallayout>
461 You need to provide your own information for
462 <filename>you</filename> in the file.
463 </para></listitem>
464 <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
465 Now that you have supplied the <filename>bblayers.conf</filename>
466 file, run the <filename>bitbake</filename> command and provide
467 the target:
468 <literallayout class='monospaced'>
469 $ bitbake printhello
470 Parsing recipes: 100% |##################################################################################|
471 Time: 00:00:00
472 Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
473 NOTE: Resolving any missing task queue dependencies
474 NOTE: Preparing runqueue
475 NOTE: Executing RunQueue Tasks
476 ********************
477 * *
478 * Hello, World! *
479 * *
480 ********************
481 NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
482 </literallayout>
483 BitBake finds the <filename>printhello</filename> recipe and
484 successfully runs the task.
485 <note>
486 After the first execution, re-running
487 <filename>bitbake printhello</filename> again will not
488 result in a BitBake run that prints the same console
489 output.
490 The reason for this is that the first time the
491 <filename>printhello.bb</filename> recipe's
492 <filename>do_build</filename> task executes
493 successfully, BitBake writes a stamp file for the task.
494 Thus, the next time you attempt to run the task
495 using that same <filename>bitbake</filename> command,
496 BitBake notices the stamp and therefore determines
497 that the task does not need to be re-run.
498 If you delete the <filename>tmp</filename> directory
499 or run <filename>bitbake -c clean printhello</filename>
500 and then re-run the build, the "Hello, World!" message will
501 be printed again.
502 </note>
503 </para></listitem>
504 </orderedlist>
505 </section>
506</appendix>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
new file mode 100644
index 0000000000..2188655de3
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
@@ -0,0 +1,685 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id="bitbake-user-manual-intro">
5 <title>Overview</title>
6
7 <para>
8 Welcome to the BitBake User Manual.
9 This manual provides information on the BitBake tool.
10 The information attempts to be as independent as possible regarding
11 systems that use BitBake, such as OpenEmbedded and the
12 Yocto Project.
13 In some cases, scenarios or examples within the context of
14 a build system are used in the manual to help with understanding.
15 For these cases, the manual clearly states the context.
16 </para>
17
18 <section id="intro">
19 <title>Introduction</title>
20
21 <para>
22 Fundamentally, BitBake is a generic task execution
23 engine that allows shell and Python tasks to be run
24 efficiently and in parallel while working within
25 complex inter-task dependency constraints.
26 One of BitBake's main users, OpenEmbedded, takes this core
27 and builds embedded Linux software stacks using
28 a task-oriented approach.
29 </para>
30
31 <para>
32 Conceptually, BitBake is similar to GNU Make in
33 some regards but has significant differences:
34 <itemizedlist>
35 <listitem><para>
36 BitBake executes tasks according to provided
37 metadata that builds up the tasks.
38 Metadata is stored in recipe (<filename>.bb</filename>)
39 and related recipe "append" (<filename>.bbappend</filename>)
40 files, configuration (<filename>.conf</filename>) and
41 underlying include (<filename>.inc</filename>) files, and
42 in class (<filename>.bbclass</filename>) files.
43 The metadata provides
44 BitBake with instructions on what tasks to run and
45 the dependencies between those tasks.
46 </para></listitem>
47 <listitem><para>
48 BitBake includes a fetcher library for obtaining source
49 code from various places such as local files, source control
50 systems, or websites.
51 </para></listitem>
52 <listitem><para>
53 The instructions for each unit to be built (e.g. a piece
54 of software) are known as "recipe" files and
55 contain all the information about the unit
56 (dependencies, source file locations, checksums, description
57 and so on).
58 </para></listitem>
59 <listitem><para>
60 BitBake includes a client/server abstraction and can
61 be used from a command line or used as a service over
62 XML-RPC and has several different user interfaces.
63 </para></listitem>
64 </itemizedlist>
65 </para>
66 </section>
67
68 <section id="history-and-goals">
69 <title>History and Goals</title>
70
71 <para>
72 BitBake was originally a part of the OpenEmbedded project.
73 It was inspired by the Portage package management system
74 used by the Gentoo Linux distribution.
75 On December 7, 2004, OpenEmbedded project team member
76 Chris Larson split the project into two distinct pieces:
77 <itemizedlist>
78 <listitem><para>BitBake, a generic task executor</para></listitem>
79 <listitem><para>OpenEmbedded, a metadata set utilized by
80 BitBake</para></listitem>
81 </itemizedlist>
82 Today, BitBake is the primary basis of the
83 <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>
84 project, which is being used to build and maintain Linux
85 distributions such as the
86 <ulink url='http://www.angstrom-distribution.org/'>Angstrom Distribution</ulink>,
87 and which is also being used as the build tool for Linux projects
88 such as the
89 <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>.
90 </para>
91
92 <para>
93 Prior to BitBake, no other build tool adequately met the needs of
94 an aspiring embedded Linux distribution.
95 All of the build systems used by traditional desktop Linux
96 distributions lacked important functionality, and none of the
97 ad hoc Buildroot-based systems, prevalent in the
98 embedded space, were scalable or maintainable.
99 </para>
100
101 <para>
102 Some important original goals for BitBake were:
103 <itemizedlist>
104 <listitem><para>
105 Handle cross-compilation.
106 </para></listitem>
107 <listitem><para>
108 Handle inter-package dependencies (build time on
109 target architecture, build time on native
110 architecture, and runtime).
111 </para></listitem>
112 <listitem><para>
113 Support running any number of tasks within a given
114 package, including, but not limited to, fetching
115 upstream sources, unpacking them, patching them,
116 configuring them, and so forth.
117 </para></listitem>
118 <listitem><para>
119 Be Linux distribution agnostic for both build and
120 target systems.
121 </para></listitem>
122 <listitem><para>
123 Be architecture agnostic.
124 </para></listitem>
125 <listitem><para>
126 Support multiple build and target operating systems
127 (e.g. Cygwin, the BSDs, and so forth).
128 </para></listitem>
129 <listitem><para>
130 Be self contained, rather than tightly
131 integrated into the build machine's root
132 filesystem.
133 </para></listitem>
134 <listitem><para>
135 Handle conditional metadata on the target architecture,
136 operating system, distribution, and machine.
137 </para></listitem>
138 <listitem><para>
139 Be easy to use the tools to supply local metadata and packages
140 against which to operate.
141 </para></listitem>
142 <listitem><para>
143 Be easy to use BitBake to collaborate between multiple
144 projects for their builds.
145 </para></listitem>
146 <listitem><para>
147 Provide an inheritance mechanism to share
148 common metadata between many packages.
149 </para></listitem>
150 </itemizedlist>
151 Over time it became apparent that some further requirements
152 were necessary:
153 <itemizedlist>
154 <listitem><para>
155 Handle variants of a base recipe (e.g. native, sdk,
156 and multilib).
157 </para></listitem>
158 <listitem><para>
159 Split metadata into layers and allow layers
160 to enhance or override other layers.
161 </para></listitem>
162 <listitem><para>
163 Allow representation of a given set of input variables
164 to a task as a checksum.
165 Based on that checksum, allow acceleration of builds
166 with prebuilt components.
167 </para></listitem>
168 </itemizedlist>
169 BitBake satisfies all the original requirements and many more
170 with extensions being made to the basic functionality to
171 reflect the additional requirements.
172 Flexibility and power have always been the priorities.
173 BitBake is highly extensible and supports embedded Python code and
174 execution of any arbitrary tasks.
175 </para>
176 </section>
177
178 <section id="Concepts">
179 <title>Concepts</title>
180
181 <para>
182 BitBake is a program written in the Python language.
183 At the highest level, BitBake interprets metadata, decides
184 what tasks are required to run, and executes those tasks.
185 Similar to GNU Make, BitBake controls how software is
186 built.
187 GNU Make achieves its control through "makefiles", while
188 BitBake uses "recipes".
189 </para>
190
191 <para>
192 BitBake extends the capabilities of a simple
193 tool like GNU Make by allowing for the definition of much more
194 complex tasks, such as assembling entire embedded Linux
195 distributions.
196 </para>
197
198 <para>
199 The remainder of this section introduces several concepts
200 that should be understood in order to better leverage
201 the power of BitBake.
202 </para>
203
204 <section id='recipes'>
205 <title>Recipes</title>
206
207 <para>
208 BitBake Recipes, which are denoted by the file extension
209 <filename>.bb</filename>, are the most basic metadata files.
210 These recipe files provide BitBake with the following:
211 <itemizedlist>
212 <listitem><para>Descriptive information about the
213 package (author, homepage, license, and so on)</para></listitem>
214 <listitem><para>The version of the recipe</para></listitem>
215 <listitem><para>Existing dependencies (both build
216 and runtime dependencies)</para></listitem>
217 <listitem><para>Where the source code resides and
218 how to fetch it</para></listitem>
219 <listitem><para>Whether the source code requires
220 any patches, where to find them, and how to apply
221 them</para></listitem>
222 <listitem><para>How to configure and compile the
223 source code</para></listitem>
224 <listitem><para>Where on the target machine to install the
225 package or packages created</para></listitem>
226 </itemizedlist>
227 </para>
228
229 <para>
230 Within the context of BitBake, or any project utilizing BitBake
231 as its build system, files with the <filename>.bb</filename>
232 extension are referred to as recipes.
233 <note>
234 The term "package" is also commonly used to describe recipes.
235 However, since the same word is used to describe packaged
236 output from a project, it is best to maintain a single
237 descriptive term - "recipes".
238 Put another way, a single "recipe" file is quite capable
239 of generating a number of related but separately installable
240 "packages".
241 In fact, that ability is fairly common.
242 </note>
243 </para>
244 </section>
245
246 <section id='configuration-files'>
247 <title>Configuration Files</title>
248
249 <para>
250 Configuration files, which are denoted by the
251 <filename>.conf</filename> extension, define
252 various configuration variables that govern the project's build
253 process.
254 These files fall into several areas that define
255 machine configuration options, distribution configuration
256 options, compiler tuning options, general common
257 configuration options, and user configuration options.
258 The main configuration file is the sample
259 <filename>bitbake.conf</filename> file, which is
260 located within the BitBake source tree
261 <filename>conf</filename> directory.
262 </para>
263 </section>
264
265 <section id='classes'>
266 <title>Classes</title>
267
268 <para>
269 Class files, which are denoted by the
270 <filename>.bbclass</filename> extension, contain
271 information that is useful to share between metadata files.
272 The BitBake source tree currently comes with one class metadata file
273 called <filename>base.bbclass</filename>.
274 You can find this file in the
275 <filename>classes</filename> directory.
276 The <filename>base.bbclass</filename> class files is special since it
277 is always included automatically for all recipes
278 and classes.
279 This class contains definitions for standard basic tasks such
280 as fetching, unpacking, configuring (empty by default),
281 compiling (runs any Makefile present), installing (empty by
282 default) and packaging (empty by default).
283 These tasks are often overridden or extended by other classes
284 added during the project development process.
285 </para>
286 </section>
287
288 <section id='layers'>
289 <title>Layers</title>
290
291 <para>
292 Layers allow you to isolate different types of
293 customizations from each other.
294 While you might find it tempting to keep everything in one layer
295 when working on a single project, the more modular you organize
296 your metadata, the easier it is to cope with future changes.
297 </para>
298
299 <para>
300 To illustrate how you can use layers to keep things modular,
301 consider customizations you might make to support a specific target machine.
302 These types of customizations typically reside in a special layer,
303 rather than a general layer, called a Board Support Package (BSP)
304 Layer.
305 Furthermore, the machine customizations should be isolated from
306 recipes and metadata that support a new GUI environment, for
307 example.
308 This situation gives you a couple of layers: one for the machine
309 configurations and one for the GUI environment.
310 It is important to understand, however, that the BSP layer can still
311 make machine-specific additions to recipes within
312 the GUI environment layer without polluting the GUI layer itself
313 with those machine-specific changes.
314 You can accomplish this through a recipe that is a BitBake append
315 (<filename>.bbappend</filename>) file.
316 </para>
317 </section>
318
319 <section id='append-bbappend-files'>
320 <title>Append Files</title>
321
322 <para>
323 Append files, which are files that have the
324 <filename>.bbappend</filename> file extension, extend or
325 override information in an existing recipe file.
326 </para>
327
328 <para>
329 BitBake expects every append file to have a corresponding recipe file.
330 Furthermore, the append file and corresponding recipe file
331 must use the same root filename.
332 The filenames can differ only in the file type suffix used
333 (e.g. <filename>formfactor_0.0.bb</filename> and
334 <filename>formfactor_0.0.bbappend</filename>).
335 </para>
336
337 <para>
338 Information in append files extends or
339 overrides the information in the underlying,
340 similarly-named recipe files.
341 </para>
342
343 <para>
344 When you name an append file, you can use the
345 wildcard character (%) to allow for matching recipe names.
346 For example, suppose you have an append file named
347 as follows:
348 <literallayout class='monospaced'>
349 busybox_1.21.%.bbappend
350 </literallayout>
351 That append file would match any <filename>busybox_1.21.x.bb</filename>
352 version of the recipe.
353 So, the append file would match the following recipe names:
354 <literallayout class='monospaced'>
355 busybox_1.21.1.bb
356 busybox_1.21.2.bb
357 busybox_1.21.3.bb
358 </literallayout>
359 If the <filename>busybox</filename> recipe was updated to
360 <filename>busybox_1.3.0.bb</filename>, the append name would not
361 match.
362 However, if you named the append file
363 <filename>busybox_1.%.bbappend</filename>, then you would have a match.
364 </para>
365
366 <para>
367 In the most general case, you could name the append file something as
368 simple as <filename>busybox_%.bbappend</filename> to be entirely
369 version independent.
370 </para>
371 </section>
372 </section>
373
374 <section id='obtaining-bitbake'>
375 <title>Obtaining BitBake</title>
376
377 <para>
378 You can obtain BitBake several different ways:
379 <itemizedlist>
380 <listitem><para><emphasis>Cloning BitBake:</emphasis>
381 Using Git to clone the BitBake source code repository
382 is the recommended method for obtaining BitBake.
383 Cloning the repository makes it easy to get bug fixes
384 and have access to stable branches and the master
385 branch.
386 Once you have cloned BitBake, you should use
387 the latest stable
388 branch for development since the master branch is for
389 BitBake development and might contain less stable changes.
390 </para>
391 <para>You usually need a version of BitBake
392 that matches the metadata you are using.
393 The metadata is generally backwards compatible but
394 not forward compatible.</para>
395 <para>Here is an example that clones the BitBake repository:
396 <literallayout class='monospaced'>
397 $ git clone git://git.openembedded.org/bitbake
398 </literallayout>
399 This command clones the BitBake Git repository into a
400 directory called <filename>bitbake</filename>.
401 Alternatively, you can
402 designate a directory after the
403 <filename>git clone</filename> command
404 if you want to call the new directory something
405 other than <filename>bitbake</filename>.
406 Here is an example that names the directory
407 <filename>bbdev</filename>:
408 <literallayout class='monospaced'>
409 $ git clone git://git.openembedded.org/bitbake bbdev
410 </literallayout></para></listitem>
411 <listitem><para><emphasis>Installation using your Distribution
412 Package Management System:</emphasis>
413 This method is not
414 recommended because the BitBake version that is
415 provided by your distribution, in most cases,
416 is several
417 releases behind a snapshot of the BitBake repository.
418 </para></listitem>
419 <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
420 Downloading a snapshot of BitBake from the
421 source code repository gives you access to a known
422 branch or release of BitBake.
423 <note>
424 Cloning the Git repository, as described earlier,
425 is the preferred method for getting BitBake.
426 Cloning the repository makes it easier to update as
427 patches are added to the stable branches.
428 </note></para>
429 <para>The following example downloads a snapshot of
430 BitBake version 1.17.0:
431 <literallayout class='monospaced'>
432 $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
433 $ tar zxpvf bitbake-1.17.0.tar.gz
434 </literallayout>
435 After extraction of the tarball using the tar utility,
436 you have a directory entitled
437 <filename>bitbake-1.17.0</filename>.
438 </para></listitem>
439 <listitem><para><emphasis>Using the BitBake that Comes With Your
440 Build Checkout:</emphasis>
441 A final possibility for getting a copy of BitBake is that it
442 already comes with your checkout of a larger Bitbake-based build
443 system, such as Poky or Yocto Project.
444 Rather than manually checking out individual layers and
445 gluing them together yourself, you can check
446 out an entire build system.
447 The checkout will already include a version of BitBake that
448 has been thoroughly tested for compatibility with the other
449 components.
450 For information on how to check out a particular BitBake-based
451 build system, consult that build system's supporting documentation.
452 </para></listitem>
453 </itemizedlist>
454 </para>
455 </section>
456
457 <section id="bitbake-user-manual-command">
458 <title>The BitBake Command</title>
459
460 <para>
461 The <filename>bitbake</filename> command is the primary interface
462 to the BitBake tool.
463 This section presents the BitBake command syntax and provides
464 several execution examples.
465 </para>
466
467 <section id='usage-and-syntax'>
468 <title>Usage and syntax</title>
469
470 <para>
471 Following is the usage and syntax for BitBake:
472 <literallayout class='monospaced'>
473 $ bitbake -h
474 Usage: bitbake [options] [recipename/target ...]
475
476 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
477 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
478 will provide the layer, BBFILES and other configuration information.
479
480 Options:
481 --version show program's version number and exit
482 -h, --help show this help message and exit
483 -b BUILDFILE, --buildfile=BUILDFILE
484 Execute tasks from a specific .bb recipe directly.
485 WARNING: Does not handle any dependencies from other
486 recipes.
487 -k, --continue Continue as much as possible after an error. While the
488 target that failed and anything depending on it cannot
489 be built, as much as possible will be built before
490 stopping.
491 -a, --tryaltconfigs Continue with builds by trying to use alternative
492 providers where possible.
493 -f, --force Force the specified targets/task to run (invalidating
494 any existing stamp file).
495 -c CMD, --cmd=CMD Specify the task to execute. The exact options
496 available depend on the metadata. Some examples might
497 be 'compile' or 'populate_sysroot' or 'listtasks' may
498 give a list of the tasks available.
499 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
500 Invalidate the stamp for the specified task such as
501 'compile' and then run the default task for the
502 specified target(s).
503 -r PREFILE, --read=PREFILE
504 Read the specified file before bitbake.conf.
505 -R POSTFILE, --postread=POSTFILE
506 Read the specified file after bitbake.conf.
507 -v, --verbose Output more log message data to the terminal.
508 -D, --debug Increase the debug level. You can specify this more
509 than once.
510 -n, --dry-run Don't execute, just go through the motions.
511 -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
512 Dump out the signature construction information, with
513 no task execution. The SIGNATURE_HANDLER parameter is
514 passed to the handler. Two common values are none and
515 printdiff but the handler may define more/less. none
516 means only dump the signature, printdiff means compare
517 the dumped signature with the cached one.
518 -p, --parse-only Quit after parsing the BB recipes.
519 -s, --show-versions Show current and preferred versions of all recipes.
520 -e, --environment Show the global or per-recipe environment complete
521 with information about where variables were
522 set/changed.
523 -g, --graphviz Save dependency tree information for the specified
524 targets in the dot syntax.
525 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
526 Assume these dependencies don't exist and are already
527 provided (equivalent to ASSUME_PROVIDED). Useful to
528 make dependency graphs more appealing
529 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
530 Show debug logging for the specified logging domains
531 -P, --profile Profile the command and save reports.
532 -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp).
533 -t SERVERTYPE, --servertype=SERVERTYPE
534 Choose which server to use, process or xmlrpc.
535 --token=XMLRPCTOKEN Specify the connection token to be used when
536 connecting to a remote server.
537 --revisions-changed Set the exit code depending on whether upstream
538 floating revisions have changed or not.
539 --server-only Run bitbake without a UI, only starting a server
540 (cooker) process.
541 -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
542 --no-setscene Do not run any setscene tasks. sstate will be ignored
543 and everything needed, built.
544 --remote-server=REMOTE_SERVER
545 Connect to the specified server.
546 -m, --kill-server Terminate the remote server.
547 --observe-only Connect to a server as an observing-only client.
548 --status-only Check the status of the remote bitbake server.
549 </literallayout>
550 </para>
551 </section>
552
553 <section id='bitbake-examples'>
554 <title>Examples</title>
555
556 <para>
557 This section presents some examples showing how to use BitBake.
558 </para>
559
560 <section id='example-executing-a-task-against-a-single-recipe'>
561 <title>Executing a Task Against a Single Recipe</title>
562
563 <para>
564 Executing tasks for a single recipe file is relatively simple.
565 You specify the file in question, and BitBake parses
566 it and executes the specified task.
567 If you do not specify a task, BitBake executes the default
568 task, which is "buildâ€.
569 BitBake obeys inter-task dependencies when doing
570 so.
571 </para>
572
573 <para>
574 The following command runs the build task, which is
575 the default task, on the <filename>foo_1.0.bb</filename>
576 recipe file:
577 <literallayout class='monospaced'>
578 $ bitbake -b foo_1.0.bb
579 </literallayout>
580 The following command runs the clean task on the
581 <filename>foo.bb</filename> recipe file:
582 <literallayout class='monospaced'>
583 $ bitbake -b foo.bb -c clean
584 </literallayout>
585 <note>
586 The "-b" option explicitly does not handle recipe
587 dependencies.
588 Other than for debugging purposes, it is instead
589 recommended that you use the syntax presented in the
590 next section.
591 </note>
592 </para>
593 </section>
594
595 <section id='executing-tasks-against-a-set-of-recipe-files'>
596 <title>Executing Tasks Against a Set of Recipe Files</title>
597
598 <para>
599 There are a number of additional complexities introduced
600 when one wants to manage multiple <filename>.bb</filename>
601 files.
602 Clearly there needs to be a way to tell BitBake what
603 files are available and, of those, which you
604 want to execute.
605 There also needs to be a way for each recipe
606 to express its dependencies, both for build-time and
607 runtime.
608 There must be a way for you to express recipe preferences
609 when multiple recipes provide the same functionality, or when
610 there are multiple versions of a recipe.
611 </para>
612
613 <para>
614 The <filename>bitbake</filename> command, when not using
615 "--buildfile" or "-b" only accepts a "PROVIDES".
616 You cannot provide anything else.
617 By default, a recipe file generally "PROVIDES" its
618 "packagename" as shown in the following example:
619 <literallayout class='monospaced'>
620 $ bitbake foo
621 </literallayout>
622 This next example "PROVIDES" the package name and also uses
623 the "-c" option to tell BitBake to just execute the
624 <filename>do_clean</filename> task:
625 <literallayout class='monospaced'>
626 $ bitbake -c clean foo
627 </literallayout>
628 </para>
629 </section>
630
631 <section id='generating-dependency-graphs'>
632 <title>Generating Dependency Graphs</title>
633
634 <para>
635 BitBake is able to generate dependency graphs using
636 the <filename>dot</filename> syntax.
637 You can convert these graphs into images using the
638 <filename>dot</filename> tool from
639 <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
640 </para>
641
642 <para>
643 When you generate a dependency graph, BitBake writes four files
644 to the current working directory:
645 <itemizedlist>
646 <listitem><para><emphasis><filename>package-depends.dot</filename>:</emphasis>
647 Shows BitBake's knowledge of dependencies between
648 runtime targets.
649 </para></listitem>
650 <listitem><para><emphasis><filename>pn-depends.dot</filename>:</emphasis>
651 Shows dependencies between build-time targets
652 (i.e. recipes).
653 </para></listitem>
654 <listitem><para><emphasis><filename>task-depends.dot</filename>:</emphasis>
655 Shows dependencies between tasks.
656 </para></listitem>
657 <listitem><para><emphasis><filename>pn-buildlist</filename>:</emphasis>
658 Shows a simple list of targets that are to be built.
659 </para></listitem>
660 </itemizedlist>
661 </para>
662
663 <para>
664 To stop depending on common depends, use the "-I" depend
665 option and BitBake omits them from the graph.
666 Leaving this information out can produce more readable graphs.
667 This way, you can remove from the graph
668 <filename>DEPENDS</filename> from inherited classes
669 such as <filename>base.bbclass</filename>.
670 </para>
671
672 <para>
673 Here are two examples that create dependency graphs.
674 The second example omits depends common in OpenEmbedded from
675 the graph:
676 <literallayout class='monospaced'>
677 $ bitbake -g foo
678
679 $ bitbake -g -I virtual/kernel -I eglibc foo
680 </literallayout>
681 </para>
682 </section>
683 </section>
684 </section>
685</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
new file mode 100644
index 0000000000..0dd543bcc0
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -0,0 +1,1790 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id="bitbake-user-manual-metadata">
5 <title>Syntax and Operators</title>
6
7 <para>
8 Bitbake files have their own syntax.
9 The syntax has similarities to several
10 other languages but also has some unique features.
11 This section describes the available syntax and operators
12 as well as provides examples.
13 </para>
14
15 <section id='basic-syntax'>
16 <title>Basic Syntax</title>
17
18 <para>
19 This section provides some basic syntax examples.
20 </para>
21
22 <section id='basic-variable-setting'>
23 <title>Basic Variable Setting</title>
24
25 <para>
26 The following example sets <filename>VARIABLE</filename> to
27 "value".
28 This assignment occurs immediately as the statement is parsed.
29 It is a "hard" assignment.
30 <literallayout class='monospaced'>
31 VARIABLE = "value"
32 </literallayout>
33 As expected, if you include leading or trailing spaces as part of
34 an assignment, the spaces are retained:
35 <literallayout class='monospaced'>
36 VARIABLE = " value"
37 VARIABLE = "value "
38 </literallayout>
39 Setting <filename>VARIABLE</filename> to "" sets it to an empty string,
40 while setting the variable to " " sets it to a blank space
41 (i.e. these are not the same values).
42 <literallayout class='monospaced'>
43 VARIABLE = ""
44 VARIABLE = " "
45 </literallayout>
46 </para>
47 </section>
48
49 <section id='variable-expansion'>
50 <title>Variable Expansion</title>
51
52 <para>
53 BitBake supports variables referencing one another's
54 contents using a syntax that is similar to shell scripting.
55 Following is an example that results in <filename>A</filename>
56 containing "aval" and <filename>B</filename> evaluating to
57 "preavalpost" based on that current value of
58 <filename>A</filename>.
59 <literallayout class='monospaced'>
60 A = "aval"
61 B = "pre${A}post"
62 </literallayout>
63 You should realize that whenever <filename>B</filename> is
64 referenced, its evaluation will depend on the state of
65 <filename>A</filename> at that time.
66 Thus, later evaluations of <filename>B</filename> in the
67 previous example could result in different values
68 depending on the value of <filename>A</filename>.
69 </para>
70 </section>
71
72 <section id='setting-a-default-value'>
73 <title>Setting a default value (?=)</title>
74
75 <para>
76 You can use the "?=" operator to achieve a "softer" assignment
77 for a variable.
78 This type of assignment allows you to define a variable if it
79 is undefined when the statement is parsed, but to leave the
80 value alone if the variable has a value.
81 Here is an example:
82 <literallayout class='monospaced'>
83 A ?= "aval"
84 </literallayout>
85 If <filename>A</filename> is set at the time this statement is parsed,
86 the variable retains its value.
87 However, if <filename>A</filename> is not set,
88 the variable is set to "aval".
89 <note>
90 This assignment is immediate.
91 Consequently, if multiple "?=" assignments
92 to a single variable exist, the first of those ends up getting
93 used.
94 </note>
95 </para>
96 </section>
97
98 <section id='setting-a-weak-default-value'>
99 <title>Setting a weak default value (??=)</title>
100
101 <para>
102 It is possible to use a "weaker" assignment than in the
103 previous section by using the "??=" operator.
104 This assignment behaves identical to "?=" except that the
105 assignment is made at the end of the parsing process rather
106 than immediately.
107 Consequently, when multiple "??=" assignments exist, the last
108 one is used.
109 Also, any "=" or "?=" assignment will override the value set with
110 "??=".
111 Here is an example:
112 <literallayout class='monospaced'>
113 A ??= "somevalue"
114 A ??= "someothervalue"
115 </literallayout>
116 If <filename>A</filename> is set before the above statements are parsed,
117 the variable retains its value.
118 If <filename>A</filename> is not set,
119 the variable is set to "someothervalue".
120 </para>
121
122 <para>
123 Again, this assignment is a "lazy" or "weak" assignment
124 because it does not occur until the end
125 of the parsing process.
126 </para>
127 </section>
128
129 <section id='immediate-variable-expansion'>
130 <title>Immediate variable expansion (:=)</title>
131
132 <para>
133 The ":=" operator results in a variable's
134 contents being expanded immediately,
135 rather than when the variable is actually used:
136 <literallayout class='monospaced'>
137 T = "123"
138 A := "${B} ${A} test ${T}"
139 T = "456"
140 B = "${T} bval"
141 C = "cval"
142 C := "${C}append"
143 </literallayout>
144 In this example, <filename>A</filename> contains
145 "test 123" because <filename>${B}</filename> and
146 <filename>${A}</filename> at the time of parsing are undefined,
147 which leaves "test 123".
148 And, the variable <filename>C</filename>
149 contains "cvalappend" since <filename>${C}</filename> immediately
150 expands to "cval".
151 </para>
152 </section>
153
154 <section id='appending-and-prepending'>
155 <title>Appending (+=) and prepending (=+) With Spaces</title>
156
157 <para>
158 Appending and prepending values is common and can be accomplished
159 using the "+=" and "=+" operators.
160 These operators insert a space between the current
161 value and prepended or appended value.
162 </para>
163
164 <para>
165 These operators take immediate effect during parsing.
166 Here are some examples:
167 <literallayout class='monospaced'>
168 B = "bval"
169 B += "additionaldata"
170 C = "cval"
171 C =+ "test"
172 </literallayout>
173 The variable <filename>B</filename> contains
174 "bval additionaldata" and <filename>C</filename>
175 contains "test cval".
176 </para>
177 </section>
178
179 <section id='appending-and-prepending-without-spaces'>
180 <title>Appending (.=) and Prepending (=.) Without Spaces</title>
181
182 <para>
183 If you want to append or prepend values without an
184 inserted space, use the ".=" and "=." operators.
185 </para>
186
187 <para>
188 These operators take immediate effect during parsing.
189 Here are some examples:
190 <literallayout class='monospaced'>
191 B = "bval"
192 B .= "additionaldata"
193 C = "cval"
194 C =. "test"
195 </literallayout>
196 The variable <filename>B</filename> contains
197 "bvaladditionaldata" and
198 <filename>C</filename> contains "testcval".
199 </para>
200 </section>
201
202 <section id='appending-and-prepending-override-style-syntax'>
203 <title>Appending and Prepending (Override Style Syntax)</title>
204
205 <para>
206 You can also append and prepend a variable's value
207 using an override style syntax.
208 When you use this syntax, no spaces are inserted.
209 </para>
210
211 <para>
212 These operators differ from the ":=", ".=", "=.", "+=", and "=+"
213 operators in that their effects are deferred
214 until after parsing completes rather than being immediately
215 applied.
216 Here are some examples:
217 <literallayout class='monospaced'>
218 B = "bval"
219 B_append = " additional data"
220 C = "cval"
221 C_prepend = "additional data "
222 D = "dval"
223 D_append = "additional data"
224 </literallayout>
225 The variable <filename>B</filename> becomes
226 "bval additional data" and <filename>C</filename> becomes
227 "additional data cval".
228 The variable <filename>D</filename> becomes
229 "dvaladditional data".
230 <note>
231 You must control all spacing when you use the
232 override syntax.
233 </note>
234 </para>
235 </section>
236
237 <section id='removing-override-style-syntax'>
238 <title>Removal (Override Style Syntax)</title>
239
240 <para>
241 You can remove values from lists using the removal
242 override style syntax.
243 Specifying a value for removal causes all occurrences of that
244 value to be removed from the variable.
245 </para>
246
247 <para>
248 When you use this syntax, BitBake expects one or more strings.
249 Surrounding spaces are removed as well.
250 Here is an example:
251 <literallayout class='monospaced'>
252 FOO = "123 456 789 123456 123 456 123 456"
253 FOO_remove = "123"
254 FOO_remove = "456"
255 FOO2 = "abc def ghi abcdef abc def abc def"
256 FOO2_remove = "abc def"
257 </literallayout>
258 The variable <filename>FOO</filename> becomes
259 "789 123456" and <filename>FOO2</filename> becomes
260 "ghi abcdef".
261 </para>
262 </section>
263
264 <section id='variable-flag-syntax'>
265 <title>Variable Flag Syntax</title>
266
267 <para>
268 Variable flags are BitBake's implementation of variable properties
269 or attributes.
270 It is a way of tagging extra information onto a variable.
271 You can find more out about variable flags in general in the
272 "<link linkend='variable-flags'>Variable Flags</link>"
273 section.
274 </para>
275
276 <para>
277 You can define, append, and prepend values to variable flags.
278 All the standard syntax operations previously mentioned work
279 for variable flags except for override style syntax
280 (i.e. <filename>_prepend</filename>, <filename>_append</filename>,
281 and <filename>_remove</filename>).
282 </para>
283
284 <para>
285 Here are some examples showing how to set variable flags:
286 <literallayout class='monospaced'>
287 FOO[a] = "abc"
288 FOO[b] = "123"
289 FOO[a] += "456"
290 </literallayout>
291 The variable <filename>FOO</filename> has two flags:
292 <filename>a</filename> and <filename>b</filename>.
293 The flags are immediately set to "abc" and "123", respectively.
294 The <filename>a</filename> flag becomes "abc 456".
295 </para>
296
297 <para>
298 No need exists to pre-define variable flags.
299 You can simply start using them.
300 One extremely common application
301 is to attach some brief documentation to a BitBake variable as
302 follows:
303 <literallayout class='monospaced'>
304 CACHE[doc] = "The directory holding the cache of the metadata."
305 </literallayout>
306 </para>
307 </section>
308
309 <section id='inline-python-variable-expansion'>
310 <title>Inline Python Variable Expansion</title>
311
312 <para>
313 You can use inline Python variable expansion to
314 set variables.
315 Here is an example:
316 <literallayout class='monospaced'>
317 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
318 </literallayout>
319 This example results in the <filename>DATE</filename>
320 variable being set to the current date.
321 </para>
322
323 <para>
324 Probably the most common use of this feature is to extract
325 the value of variables from BitBake's internal data dictionary,
326 <filename>d</filename>.
327 The following lines select the values of a package name
328 and its version number, respectively:
329 <literallayout class='monospaced'>
330 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[0] or 'defaultpkgname'}"
331 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[1] or '1.0'}"
332 </literallayout>
333 </para>
334 </section>
335
336 <section id='providing-pathnames'>
337 <title>Providing Pathnames</title>
338
339 <para>
340 When specifying pathnames for use with BitBake,
341 do not use the tilde ("~") character as a shortcut
342 for your home directory.
343 Doing so might cause BitBake to not recognize the
344 path since BitBake does not expand this character in
345 the same way a shell would.
346 </para>
347
348 <para>
349 Instead, provide a fuller path as the following
350 example illustrates:
351 <literallayout class='monospaced'>
352 BBLAYERS ?= " \
353 /home/scott-lenovo/LayerA \
354 "
355 </literallayout>
356 </para>
357 </section>
358 </section>
359
360 <section id='conditional-syntax-overrides'>
361 <title>Conditional Syntax (Overrides)</title>
362
363 <para>
364 BitBake uses
365 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
366 to control what variables are overridden after BitBake
367 parses recipes and configuration files.
368 This section describes how you can use
369 <filename>OVERRIDES</filename> as conditional metadata,
370 talks about key expansion in relationship to
371 <filename>OVERRIDES</filename>, and provides some examples
372 to help with understanding.
373 </para>
374
375 <section id='conditional-metadata'>
376 <title>Conditional Metadata</title>
377
378 <para>
379 You can use <filename>OVERRIDES</filename> to conditionally select
380 a specific version of a variable and to conditionally
381 append or prepend the value of a variable.
382 <itemizedlist>
383 <listitem><para><emphasis>Selecting a Variable:</emphasis>
384 The <filename>OVERRIDES</filename> variable is
385 a colon-character-separated list that contains items
386 for which you want to satisfy conditions.
387 Thus, if you have a variable that is conditional on “armâ€, and “armâ€
388 is in <filename>OVERRIDES</filename>, then the “armâ€-specific
389 version of the variable is used rather than the non-conditional
390 version.
391 Here is an example:
392 <literallayout class='monospaced'>
393 OVERRIDES = "architecture:os:machine"
394 TEST = "default"
395 TEST_os = "osspecific"
396 TEST_nooverride = "othercondvalue"
397 </literallayout>
398 In this example, the <filename>OVERRIDES</filename>
399 variable lists three overrides:
400 "architecture", "os", and "machine".
401 The variable <filename>TEST</filename> by itself has a default
402 value of "default".
403 You select the os-specific version of the <filename>TEST</filename>
404 variable by appending the "os" override to the variable
405 (i.e.<filename>TEST_os</filename>).
406 </para>
407
408 <para>
409 To better understand this, consider a practical example
410 that assumes an OpenEmbedded metadata-based Linux
411 kernel recipe file.
412 The following lines from the recipe file first set
413 the kernel branch variable <filename>KBRANCH</filename>
414 to a default value, then conditionally override that
415 value based on the architecture of the build:
416 <literallayout class='monospaced'>
417 KBRANCH = "standard/base"
418 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
419 KBRANCH_qemumips = "standard/mti-malta32"
420 KBRANCH_qemuppc = "standard/qemuppc"
421 KBRANCH_qemux86 = "standard/common-pc/base"
422 KBRANCH_qemux86-64 = "standard/common-pc-64/base"
423 KBRANCH_qemumips64 = "standard/mti-malta64"
424 </literallayout>
425 </para></listitem>
426 <listitem><para><emphasis>Appending and Prepending:</emphasis>
427 BitBake also supports append and prepend operations to
428 variable values based on whether a specific item is
429 listed in <filename>OVERRIDES</filename>.
430 Here is an example:
431 <literallayout class='monospaced'>
432 DEPENDS = "glibc ncurses"
433 OVERRIDES = "machine:local"
434 DEPENDS_append_machine = "libmad"
435 </literallayout>
436 In this example, <filename>DEPENDS</filename> becomes
437 "glibc ncurses libmad".
438 </para>
439
440 <para>
441 Again, using an OpenEmbedded metadata-based
442 kernel recipe file as an example, the
443 following lines will conditionally append to the
444 <filename>KERNEL_FEATURES</filename> variable based
445 on the architecture:
446 <literallayout class='monospaced'>
447 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
448 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
449 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
450 </literallayout>
451 </para></listitem>
452 </itemizedlist>
453 </para>
454 </section>
455
456 <section id='key-expansion'>
457 <title>Key Expansion</title>
458
459 <para>
460 Key expansion happens when the BitBake datastore is finalized
461 just before BitBake expands overrides.
462 To better understand this, consider the following example:
463 <literallayout class='monospaced'>
464 A${B} = "X"
465 B = "2"
466 A2 = "Y"
467 </literallayout>
468 In this case, after all the parsing is complete, and
469 before any overrides are handled, BitBake expands
470 <filename>${B}</filename> into "2".
471 This expansion causes <filename>A2</filename>, which was
472 set to "Y" before the expansion, to become "X".
473 </para>
474 </section>
475
476 <section id='variable-interaction-worked-examples'>
477 <title>Examples</title>
478
479 <para>
480 Despite the previous explanations that show the different forms of
481 variable definitions, it can be hard to work
482 out exactly what happens when variable operators, conditional
483 overrides, and unconditional overrides are combined.
484 This section presents some common scenarios along
485 with explanations for variable interactions that
486 typically confuse users.
487 </para>
488
489 <para>
490 There is often confusion concerning the order in which
491 overrides and various "append" operators take effect.
492 Recall that an append or prepend operation using "_append"
493 and "_prepend" does not result in an immediate assignment
494 as would "+=", ".=", "=+", or "=.".
495 Consider the following example:
496 <literallayout class='monospaced'>
497 OVERRIDES = "foo"
498 A = "Z"
499 A_foo_append = "X"
500 </literallayout>
501 For this case, <filename>A</filename> is
502 unconditionally set to "Z" and "X" is
503 unconditionally and immediately appended to the variable
504 <filename>A_foo</filename>.
505 Because overrides have not been applied yet,
506 <filename>A_foo</filename> is set to "X" due to the append
507 and <filename>A</filename> simply equals "Z".
508 </para>
509
510 <para>
511 Applying overrides, however, changes things.
512 Since "foo" is listed in <filename>OVERRIDES</filename>,
513 the conditional variable <filename>A</filename> is replaced
514 with the "foo" version, which is equal to "X".
515 So effectively, <filename>A_foo</filename> replaces <filename>A</filename>.
516 </para>
517
518 <para>
519 This next example changes the order of the override and
520 the append:
521 <literallayout class='monospaced'>
522 OVERRIDES = "foo"
523 A = "Z"
524 A_append_foo = "X"
525 </literallayout>
526 For this case, before overrides are handled,
527 <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename>
528 is set to "X".
529 Once the override for "foo" is applied, however,
530 <filename>A</filename> gets appended with "X".
531 Consequently, <filename>A</filename> becomes "ZX".
532 Notice that spaces are not appended.
533 </para>
534
535 <para>
536 This next example has the order of the appends and overrides reversed
537 back as in the first example:
538 <literallayout class='monospaced'>
539 OVERRIDES = "foo"
540 A = "Y"
541 A_foo_append = "Z"
542 A_foo_append += "X"
543 </literallayout>
544 For this case, before any overrides are resolved,
545 <filename>A</filename> is set to "Y" using an immediate assignment.
546 After this immediate assignment, <filename>A_foo</filename> is set
547 to "Z", and then further appended with
548 "X" leaving the variable set to "Z X".
549 Finally, applying the override for "foo" results in the conditional
550 variable <filename>A</filename> becoming "Z X" (i.e.
551 <filename>A</filename> is replaced with <filename>A_foo</filename>).
552 </para>
553
554 <para>
555 This final example mixes in some varying operators:
556 <literallayout class='monospaced'>
557 A = "1"
558 A_append = "2"
559 A_append = "3"
560 A += "4"
561 A .= "5"
562 </literallayout>
563 For this case, the type of append operators are affecting the
564 order of assignments as BitBake passes through the code
565 multiple times.
566 Initially, <filename>A</filename> is set to "1 45" because
567 of the three statements that use immediate operators.
568 After these assignments are made, BitBake applies the
569 <filename>_append</filename> operations.
570 Those operations result in <filename>A</filename> becoming "1 4523".
571 </para>
572 </section>
573 </section>
574
575 <section id='sharing-functionality'>
576 <title>Sharing Functionality</title>
577
578 <para>
579 BitBake allows for metadata sharing through include files
580 (<filename>.inc</filename>) and class files
581 (<filename>.bbclass</filename>).
582 For example, suppose you have a piece of common functionality
583 such as a task definition that you want to share between
584 more than one recipe.
585 In this case, creating a <filename>.bbclass</filename>
586 file that contains the common functionality and then using
587 the <filename>inherit</filename> directive in your recipes to
588 inherit the class would be a common way to share the task.
589 </para>
590
591 <para>
592 This section presents the mechanisms BitBake provides to
593 allow you to share functionality between recipes.
594 Specifically, the mechanisms include <filename>include</filename>,
595 <filename>inherit</filename>, <filename>INHERIT</filename>, and
596 <filename>require</filename> directives.
597 </para>
598
599 <section id='locating-include-and-class-files'>
600 <title>Locating Include and Class Files</title>
601
602 <para>
603 BitBake uses the
604 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
605 variable to locate needed include and class files.
606 The <filename>BBPATH</filename> variable is analogous to
607 the environment variable <filename>PATH</filename>.
608 </para>
609
610 <para>
611 In order for include and class files to be found by BitBake,
612 they need to be located in a "classes" subdirectory that can
613 be found in <filename>BBPATH</filename>.
614 </para>
615 </section>
616
617 <section id='inherit-directive'>
618 <title><filename>inherit</filename> Directive</title>
619
620 <para>
621 When writing a recipe or class file, you can use the
622 <filename>inherit</filename> directive to inherit the
623 functionality of a class (<filename>.bbclass</filename>).
624 BitBake only supports this directive when used within recipe
625 and class files (i.e. <filename>.bb</filename> and
626 <filename>.bbclass</filename>).
627 </para>
628
629 <para>
630 The <filename>inherit</filename> directive is a rudimentary
631 means of specifying what classes of functionality your
632 recipes require.
633 For example, you can easily abstract out the tasks involved in
634 building a package that uses Autoconf and Automake and put
635 those tasks into a class file that can be used by your recipe.
636 </para>
637
638 <para>
639 As an example, your recipes could use the following directive
640 to inherit an <filename>autotools.bbclass</filename> file.
641 The class file would contain common functionality for using
642 Autotools that could be shared across recipes:
643 <literallayout class='monospaced'>
644 inherit autotools
645 </literallayout>
646 In this case, BitBake would search for the directory
647 <filename>classes/autotools.bbclass</filename>
648 in <filename>BBPATH</filename>.
649 <note>
650 You can override any values and functions of the
651 inherited class within your recipe by doing so
652 after the "inherit" statement.
653 </note>
654 </para>
655 </section>
656
657 <section id='include-directive'>
658 <title><filename>include</filename> Directive</title>
659
660 <para>
661 BitBake understands the <filename>include</filename>
662 directive.
663 This directive causes BitBake to parse whatever file you specify,
664 and to insert that file at that location.
665 The directive is much like its equivalent in Make except
666 that if the path specified on the include line is a relative
667 path, BitBake locates the first file it can find
668 within <filename>BBPATH</filename>.
669 </para>
670
671 <para>
672 As an example, suppose you needed a recipe to include some
673 self-test definitions:
674 <literallayout class='monospaced'>
675 include test_defs.inc
676 </literallayout>
677 <note>
678 The <filename>include</filename> directive does not
679 produce an error when the file cannot be found.
680 Consequently, it is recommended that if the file you
681 are including is expected to exist, you should use
682 <link linkend='require-inclusion'><filename>require</filename></link>
683 instead of <filename>include</filename>.
684 Doing so makes sure that an error is produced if the
685 file cannot be found.
686 </note>
687 </para>
688 </section>
689
690 <section id='require-inclusion'>
691 <title><filename>require</filename> Directive</title>
692
693 <para>
694 BitBake understands the <filename>require</filename>
695 directive.
696 This directive behaves just like the
697 <filename>include</filename> directive with the exception that
698 BitBake raises a parsing error if the file to be included cannot
699 be found.
700 Thus, any file you require is inserted into the file that is
701 being parsed at the location of the directive.
702 </para>
703
704 <para>
705 Similar to how BitBake handles
706 <link linkend='include-directive'><filename>include</filename></link>,
707 if the path specified
708 on the require line is a relative path, BitBake locates
709 the first file it can find within <filename>BBPATH</filename>.
710 </para>
711
712 <para>
713 As an example, suppose you have two versions of a recipe
714 (e.g. <filename>foo_1.2.2.bb</filename> and
715 <filename>foo_2.0.0.bb</filename>) where
716 each version contains some identical functionality that could be
717 shared.
718 You could create an include file named <filename>foo.inc</filename>
719 that contains the common definitions needed to build "foo".
720 You need to be sure <filename>foo.inc</filename> is located in the
721 same directory as your two recipe files as well.
722 Once these conditions are set up, you can share the functionality
723 using a <filename>require</filename> directive from within each
724 recipe:
725 <literallayout class='monospaced'>
726 require foo.inc
727 </literallayout>
728 </para>
729 </section>
730
731 <section id='inherit-configuration-directive'>
732 <title><filename>INHERIT</filename> Configuration Directive</title>
733
734 <para>
735 When creating a configuration file (<filename>.conf</filename>),
736 you can use the <filename>INHERIT</filename> directive to
737 inherit a class.
738 BitBake only supports this directive when used within
739 a configuration file.
740 </para>
741
742 <para>
743 As an example, suppose you needed to inherit a class
744 file called <filename>abc.bbclass</filename> from a
745 configuration file as follows:
746 <literallayout class='monospaced'>
747 INHERIT += "abc"
748 </literallayout>
749 This configuration directive causes the named
750 class to be inherited at the point of the directive
751 during parsing.
752 As with the <filename>inherit</filename> directive, the
753 <filename>.bbclass</filename> file must be located in a
754 "classes" subdirectory in one of the directories specified
755 in <filename>BBPATH</filename>.
756 <note>
757 Because <filename>.conf</filename> files are parsed
758 first during BitBake's execution, using
759 <filename>INHERIT</filename> to inherit a class effectively
760 inherits the class globally (i.e. for all recipes).
761 </note>
762 </para>
763 </section>
764 </section>
765
766 <section id='functions'>
767 <title>Functions</title>
768
769 <para>
770 As with most languages, functions are the building blocks that
771 are used to build up operations into tasks.
772 BitBake supports these types of functions:
773 <itemizedlist>
774 <listitem><para><emphasis>Shell Functions:</emphasis>
775 Functions written in shell script and executed either
776 directly as functions, tasks, or both.
777 They can also be called by other shell functions.
778 </para></listitem>
779 <listitem><para><emphasis>BitBake Style Python Functions:</emphasis>
780 Functions written in Python and executed by BitBake or other
781 Python functions using <filename>bb.build.exec_func()</filename>.
782 </para></listitem>
783 <listitem><para><emphasis>Python Functions:</emphasis>
784 Functions written in Python and executed by Python.
785 </para></listitem>
786 <listitem><para><emphasis>Anonymous Python Functions:</emphasis>
787 Python functions executed automatically during
788 parsing.
789 </para></listitem>
790 </itemizedlist>
791 Regardless of the type of function, you can only
792 define them in class (<filename>.bbclass</filename>)
793 and recipe (<filename>.bb</filename> or <filename>.inc</filename>)
794 files.
795 </para>
796
797 <section id='shell-functions'>
798 <title>Shell Functions</title>
799
800 <para>
801 Functions written in shell script and executed either
802 directly as functions, tasks, or both.
803 They can also be called by other shell functions.
804 Here is an example shell function definition:
805 <literallayout class='monospaced'>
806 some_function () {
807 echo "Hello World"
808 }
809 </literallayout>
810 When you create these types of functions in your recipe
811 or class files, you need to follow the shell programming
812 rules.
813 The scripts are executed by <filename>/bin/sh</filename>,
814 which may not be a bash shell but might be something
815 such as <filename>dash</filename>.
816 You should not use Bash-specific script (bashisms).
817 </para>
818 </section>
819
820 <section id='bitbake-style-python-functions'>
821 <title>BitBake Style Python Functions</title>
822
823 <para>
824 These functions are written in Python and executed by
825 BitBake or other Python functions using
826 <filename>bb.build.exec_func()</filename>.
827 </para>
828
829 <para>
830 An example BitBake function is:
831 <literallayout class='monospaced'>
832 python some_python_function () {
833 d.setVar("TEXT", "Hello World")
834 print d.getVar("TEXT", True)
835 }
836 </literallayout>
837 Because the Python "bb" and "os" modules are already
838 imported, you do not need to import these modules.
839 Also in these types of functions, the datastore ("d")
840 is a global variable and is always automatically
841 available.
842 </para>
843 </section>
844
845 <section id='python-functions'>
846 <title>Python Functions</title>
847
848 <para>
849 These functions are written in Python and are executed by
850 other Python code.
851 Examples of Python functions are utility functions
852 that you intend to call from in-line Python or
853 from within other Python functions.
854 Here is an example:
855 <literallayout class='monospaced'>
856 def get_depends(d):
857 if d.getVar('SOMECONDITION', True):
858 return "dependencywithcond"
859 else:
860 return "dependency"
861 SOMECONDITION = "1"
862 DEPENDS = "${@get_depends(d)}"
863 </literallayout>
864 This would result in <filename>DEPENDS</filename>
865 containing <filename>dependencywithcond</filename>.
866 </para>
867
868 <para>
869 Here are some things to know about Python functions:
870 <itemizedlist>
871 <listitem><para>Python functions can take parameters.
872 </para></listitem>
873 <listitem><para>The BitBake datastore is not
874 automatically available.
875 Consequently, you must pass it in as a
876 parameter to the function.
877 </para></listitem>
878 <listitem><para>The "bb" and "os" Python modules are
879 automatically available.
880 You do not need to import them.
881 </para></listitem>
882 </itemizedlist>
883 </para>
884 </section>
885
886 <section id='anonymous-python-functions'>
887 <title>Anonymous Python Functions</title>
888
889 <para>
890 Sometimes it is useful to run some code during
891 parsing to set variables or to perform other operations
892 programmatically.
893 To do this, you can define an anonymous Python function.
894 Here is an example that conditionally sets a
895 variable based on the value of another variable:
896 <literallayout class='monospaced'>
897 python __anonymous () {
898 if d.getVar('SOMEVAR', True) == 'value':
899 d.setVar('ANOTHERVAR', 'value2')
900 }
901 </literallayout>
902 The "__anonymous" function name is optional, so the
903 following example is functionally equivalent to the above:
904 <literallayout class='monospaced'>
905 python () {
906 if d.getVar('SOMEVAR', True) == 'value':
907 d.setVar('ANOTHERVAR', 'value2')
908 }
909 </literallayout>
910 Because unlike other Python functions anonymous
911 Python functions are executed during parsing, the
912 "d" variable within an anonymous Python function represents
913 the datastore for the entire recipe.
914 Consequently, you can set variable values here and
915 those values can be picked up by other functions.
916 </para>
917 </section>
918
919 <section id='flexible-inheritance-for-class-functions'>
920 <title>Flexible Inheritance for Class Functions</title>
921
922 <para>
923 Through coding techniques and the use of
924 <filename>EXPORT_FUNCTIONS</filename>, BitBake supports
925 exporting a function from a class such that the
926 class function appears as the default implementation
927 of the function, but can still be called if a recipe
928 inheriting the class needs to define its own version of
929 the function.
930 </para>
931
932 <para>
933 To understand the benefits of this feature, consider
934 the basic scenario where a class defines a task function
935 and your recipe inherits the class.
936 In this basic scenario, your recipe inherits the task
937 function as defined in the class.
938 If desired, your recipe can add to the start and end of the
939 function by using the "_prepend" or "_append" operations
940 respectively, or it can redefine the function completely.
941 However, if it redefines the function, there is
942 no means for it to call the class version of the function.
943 <filename>EXPORT_FUNCTIONS</filename> provides a mechanism
944 that enables the recipe's version of the function to call
945 the original version of the function.
946 </para>
947
948 <para>
949 To make use of this technique, you need the following
950 things in place:
951 <itemizedlist>
952 <listitem><para>
953 The class needs to define the function as follows:
954 <literallayout class='monospaced'>
955 &lt;classname&gt;_&lt;functionname&gt;
956 </literallayout>
957 For example, if you have a class file
958 <filename>bar.bbclass</filename> and a function named
959 <filename>do_foo</filename>, the class must define the function
960 as follows:
961 <literallayout class='monospaced'>
962 bar_do_foo
963 </literallayout>
964 </para></listitem>
965 <listitem><para>
966 The class needs to contain the <filename>EXPORT_FUNCTIONS</filename>
967 statement as follows:
968 <literallayout class='monospaced'>
969 EXPORT_FUNCTIONS &lt;functionname&gt;
970 </literallayout>
971 For example, continuing with the same example, the
972 statement in the <filename>bar.bbclass</filename> would be
973 as follows:
974 <literallayout class='monospaced'>
975 EXPORT_FUNCTIONS do_foo
976 </literallayout>
977 </para></listitem>
978 <listitem><para>
979 You need to call the function appropriately from within your
980 recipe.
981 Continuing with the same example, if your recipe
982 needs to call the class version of the function,
983 it should call <filename>bar_do_foo</filename>.
984 Assuming <filename>do_foo</filename> was a shell function
985 and <filename>EXPORT_FUNCTIONS</filename> was used as above,
986 the recipe's function could conditionally call the
987 class version of the function as follows:
988 <literallayout class='monospaced'>
989 do_foo() {
990 if [ somecondition ] ; then
991 bar_do_foo
992 else
993 # Do something else
994 fi
995 }
996 </literallayout>
997 To call your modified version of the function as defined
998 in your recipe, call it as <filename>do_foo</filename>.
999 </para></listitem>
1000 </itemizedlist>
1001 With these conditions met, your single recipe
1002 can freely choose between the original function
1003 as defined in the class file and the modified function in your recipe.
1004 If you do not set up these conditions, you are limited to using one function
1005 or the other.
1006 </para>
1007 </section>
1008 </section>
1009
1010 <section id='tasks'>
1011 <title>Tasks</title>
1012
1013 <para>
1014 Tasks are BitBake execution units that originate as
1015 functions and make up the steps that BitBake needs to run
1016 for given recipe.
1017 Tasks are only supported in recipe (<filename>.bb</filename>
1018 or <filename>.inc</filename>) and class
1019 (<filename>.bbclass</filename>) files.
1020 By convention, task names begin with the string "do_".
1021 </para>
1022
1023 <para>
1024 Here is an example of a task that prints out the date:
1025 <literallayout class='monospaced'>
1026 python do_printdate () {
1027 import time
1028 print time.strftime('%Y%m%d', time.gmtime())
1029 }
1030 addtask printdate after do_fetch before do_build
1031 </literallayout>
1032 </para>
1033
1034 <section id='promoting-a-function-to-a-task'>
1035 <title>Promoting a Function to a Task</title>
1036
1037 <para>
1038 Any function can be promoted to a task by applying the
1039 <filename>addtask</filename> command.
1040 The <filename>addtask</filename> command also describes
1041 inter-task dependencies.
1042 Here is the function from the previous section but with the
1043 <filename>addtask</filename> command promoting it to a task
1044 and defining some dependencies:
1045 <literallayout class='monospaced'>
1046 python do_printdate () {
1047 import time
1048 print time.strftime('%Y%m%d', time.gmtime())
1049 }
1050 addtask printdate after do_fetch before do_build
1051 </literallayout>
1052 In the example, the function is defined and then promoted
1053 as a task.
1054 The <filename>do_printdate</filename> task becomes a dependency of
1055 the <filename>do_build</filename> task, which is the default
1056 task.
1057 And, the <filename>do_printdate</filename> task is dependent upon
1058 the <filename>do_fetch</filename> task.
1059 Execution of the <filename>do_build</filename> task results
1060 in the <filename>do_printdate</filename> task running first.
1061 </para>
1062 </section>
1063
1064 <section id='deleting-a-task'>
1065 <title>Deleting a Task</title>
1066
1067 <para>
1068 As well as being able to add tasks, tasks can also be deleted.
1069 This is done simply with <filename>deltask</filename> command.
1070 For example, to delete the example task used in the previous
1071 sections, you would use:
1072 <literallayout class='monospaced'>
1073 deltask printdate
1074 </literallayout>
1075 </para>
1076 </section>
1077
1078 <section id='passing-information-into-the-build-task-environment'>
1079 <title>Passing Information Into the Build Task Environment</title>
1080
1081 <para>
1082 When running a task, BitBake tightly controls the execution
1083 environment of the build tasks to make
1084 sure unwanted contamination from the build machine cannot
1085 influence the build.
1086 Consequently, if you do want something to get passed into the
1087 build task environment, you must take these two steps:
1088 <orderedlist>
1089 <listitem><para>
1090 Tell BitBake to load what you want from the environment
1091 into the datastore.
1092 You can do so through the
1093 <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
1094 variable.
1095 For example, assume you want to prevent the build system from
1096 accessing your <filename>$HOME/.ccache</filename>
1097 directory.
1098 The following command tells BitBake to load
1099 <filename>CCACHE_DIR</filename> from the environment into
1100 the datastore:
1101 <literallayout class='monospaced'>
1102 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1103 </literallayout></para></listitem>
1104 <listitem><para>
1105 Tell BitBake to export what you have loaded into the
1106 datastore to the task environment of every running task.
1107 Loading something from the environment into the datastore
1108 (previous step) only makes it available in the datastore.
1109 To export it to the task environment of every running task,
1110 use a command similar to the following in your local configuration
1111 file <filename>local.conf</filename> or your
1112 distribution configuration file:
1113 <literallayout class='monospaced'>
1114 export CCACHE_DIR
1115 </literallayout>
1116 <note>
1117 A side effect of the previous steps is that BitBake
1118 records the variable as a dependency of the build process
1119 in things like the setscene checksums.
1120 If doing so results in unnecessary rebuilds of tasks, you can
1121 whitelist the variable so that the setscene code
1122 ignores the dependency when it creates checksums.
1123 </note></para></listitem>
1124 </orderedlist>
1125 </para>
1126
1127 <para>
1128 Sometimes, it is useful to be able to obtain information
1129 from the original execution environment.
1130 Bitbake saves a copy of the original environment into
1131 a special variable named
1132 <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
1133 </para>
1134
1135 <para>
1136 The <filename>BB_ORIGENV</filename> variable returns a datastore
1137 object that can be queried using the standard datastore operators
1138 such as <filename>getVar()</filename>.
1139 The datastore object is useful, for example, to find the original
1140 <filename>DISPLAY</filename> variable.
1141 Here is an example:
1142 <literallayout class='monospaced'>
1143 BB_ORIGENV - add example?
1144
1145 origenv = d.getVar("BB_ORIGENV", False)
1146 bar = origenv.getVar("BAR", False)
1147 </literallayout>
1148 The previous example returns <filename>BAR</filename> from the original
1149 execution environment.
1150 </para>
1151
1152 <para>
1153 By default, BitBake cleans the environment to include only those
1154 things exported or listed in its whitelist to ensure that the build
1155 environment is reproducible and consistent.
1156 </para>
1157 </section>
1158 </section>
1159
1160 <section id='variable-flags'>
1161 <title>Variable Flags</title>
1162
1163 <para>
1164 Variable flags (varflags) help control a task's functionality
1165 and dependencies.
1166 BitBake reads and writes varflags to the datastore using the following
1167 command forms:
1168 <literallayout class='monospaced'>
1169 &lt;variable&gt; = d.getVarFlags("&lt;variable&gt;")
1170 self.d.setVarFlags("FOO", {"func": True})
1171 </literallayout>
1172 </para>
1173
1174 <para>
1175 When working with varflags, the same syntax, with the exception of
1176 overrides, applies.
1177 In other words, you can set, append, and prepend varflags just like
1178 variables.
1179 See the
1180 "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>"
1181 section for details.
1182 </para>
1183
1184 <para>
1185 BitBake has a defined set of varflags available for recipes and
1186 classes.
1187 Tasks support a number of these flags which control various
1188 functionality of the task:
1189 <itemizedlist>
1190 <listitem><para><emphasis>dirs:</emphasis>
1191 Directories that should be created before the task runs.
1192 </para></listitem>
1193 <listitem><para><emphasis>cleandirs:</emphasis>
1194 Empty directories that should created before the task runs.
1195 </para></listitem>
1196 <listitem><para><emphasis>noexec:</emphasis>
1197 Marks the tasks as being empty and no execution required.
1198 The <filename>noexec</filename> flag can be used to set up
1199 tasks as dependency placeholders, or to disable tasks defined
1200 elsewhere that are not needed in a particular recipe.
1201 </para></listitem>
1202 <listitem><para><emphasis>nostamp:</emphasis>
1203 Tells BitBake to not generate a stamp file for a task,
1204 which implies the task should always be executed.
1205 </para></listitem>
1206 <listitem><para><emphasis>umask:</emphasis>
1207 The umask to run the task under.
1208 </para></listitem>
1209 <listitem><para><emphasis>deptask:</emphasis>
1210 Controls task build-time dependencies.
1211 See the
1212 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1213 variable and the
1214 "<link linkend='build-dependencies'>Build Dependencies</link>"
1215 section for more information.
1216 </para></listitem>
1217 <listitem><para><emphasis>rdeptask:</emphasis>
1218 Controls task runtime dependencies.
1219 See the
1220 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1221 variable, the
1222 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1223 variable, and the
1224 "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
1225 section for more information.
1226 </para></listitem>
1227 <listitem><para><emphasis>recrdeptask:</emphasis>
1228 Controls task recursive runtime dependencies.
1229 See the
1230 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1231 variable, the
1232 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1233 variable, and the
1234 "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
1235 section for more information.
1236 </para></listitem>
1237 <listitem><para><emphasis>depends:</emphasis>
1238 Controls inter-task dependencies.
1239 See the
1240 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1241 variable and the
1242 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1243 section for more information.
1244 </para></listitem>
1245 <listitem><para><emphasis>rdepends:</emphasis>
1246 Controls inter-task runtime dependencies.
1247 See the
1248 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1249 variable, the
1250 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1251 variable, and the
1252 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1253 section for more information.
1254 </para></listitem>
1255 <listitem><para><emphasis>postfuncs:</emphasis>
1256 List of functions to call after the completion of the task.
1257 </para></listitem>
1258 <listitem><para><emphasis>prefuncs:</emphasis>
1259 List of functions to call before the task executes.
1260 </para></listitem>
1261 <listitem><para><emphasis>stamp-extra-info:</emphasis>
1262 Extra stamp information to append to the task's stamp.
1263 As an example, OpenEmbedded uses this flag to allow
1264 machine-specific tasks.
1265 </para></listitem>
1266 </itemizedlist>
1267 </para>
1268
1269 <para>
1270 Several varflags are useful for controlling how signatures are
1271 calculated for variables.
1272 For more information on this process, see the
1273 "<link linkend='checksums'>Checksums (Signatures)</link>"
1274 section.
1275 <itemizedlist>
1276 <listitem><para><emphasis>vardeps:</emphasis>
1277 Specifies a space-separated list of additional
1278 variables to add to a variable's dependencies
1279 for the purposes of calculating its signature.
1280 Adding variables to this list is useful, for example, when
1281 a function refers to a variable in a manner that
1282 does not allow BitBake to automatically determine
1283 that the variable is referred to.
1284 </para></listitem>
1285 <listitem><para><emphasis>vardepvalue:</emphasis>
1286 If set, instructs BitBake to ignore the actual
1287 value of the variable and instead use the specified
1288 value when calculating the variable's signature.
1289 </para></listitem>
1290 <listitem><para><emphasis>vardepsexclude:</emphasis>
1291 Specifies a space-separated list of variables
1292 that should be excluded from a variable's dependencies
1293 for the purposes of calculating its signature.
1294 </para></listitem>
1295 <listitem><para><emphasis>vardepvalueexclude:</emphasis>
1296 Specifies a pipe-separated list of strings to exclude
1297 from the variable's value when calculating the
1298 variable's signature.
1299 </para></listitem>
1300 </itemizedlist>
1301 </para>
1302 </section>
1303
1304 <section id='events'>
1305 <title>Events</title>
1306
1307 <para>
1308 BitBake allows installation of event handlers within
1309 recipe and class files.
1310 Events are triggered at certain points during operation,
1311 such as the beginning of an operation against a given recipe
1312 (<filename>*.bb</filename> file), the start of a given task,
1313 task failure, task success, and so forth.
1314 The intent is to make it easy to do things like email
1315 notification on build failure.
1316 </para>
1317
1318 <para>
1319 Following is an example event handler that
1320 prints the name of the event and the content of
1321 the <filename>FILE</filename> variable:
1322 <literallayout class='monospaced'>
1323 addhandler myclass_eventhandler
1324 python myclass_eventhandler() {
1325 from bb.event import getName
1326 from bb import data
1327 print("The name of the Event is %s" % getName(e))
1328 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
1329 }
1330 </literallayout>
1331 This event handler gets called every time an event is
1332 triggered.
1333 A global variable "<filename>e</filename>" is defined and
1334 "<filename>e.data</filename>" contains an instance of
1335 "<filename>bb.data</filename>".
1336 With the <filename>getName(e)</filename> method, one can get
1337 the name of the triggered event.
1338 </para>
1339
1340 <para>
1341 Because you probably are only interested in a subset of events,
1342 you would likely use the <filename>[eventmask]</filename> flag
1343 for your event handler to be sure that only certain events
1344 trigger the handler.
1345 Given the previous example, suppose you only wanted the
1346 <filename>bb.build.TaskFailed</filename> event to trigger that
1347 event handler.
1348 Use the flag as follows:
1349 <literallayout class='monospaced'>
1350 addhandler myclass_eventhandler
1351 myclass_eventhandler[eventmask] = "bb.build.TaskFailed"
1352 python myclass_eventhandler() {
1353 from bb.event import getName
1354 from bb import data
1355 print("The name of the Event is %s" % getName(e))
1356 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
1357 }
1358 </literallayout>
1359 </para>
1360
1361 <para>
1362 During a standard build, the following common events might occur:
1363 <itemizedlist>
1364 <listitem><para>
1365 <filename>bb.event.ConfigParsed()</filename>
1366 </para></listitem>
1367 <listitem><para>
1368 <filename>bb.event.ParseStarted()</filename>
1369 </para></listitem>
1370 <listitem><para>
1371 <filename>bb.event.ParseProgress()</filename>
1372 </para></listitem>
1373 <listitem><para>
1374 <filename>bb.event.ParseCompleted()</filename>
1375 </para></listitem>
1376 <listitem><para>
1377 <filename>bb.event.BuildStarted()</filename>
1378 </para></listitem>
1379 <listitem><para>
1380 <filename>bb.build.TaskStarted()</filename>
1381 </para></listitem>
1382 <listitem><para>
1383 <filename>bb.build.TaskInvalid()</filename>
1384 </para></listitem>
1385 <listitem><para>
1386 <filename>bb.build.TaskFailedSilent()</filename>
1387 </para></listitem>
1388 <listitem><para>
1389 <filename>bb.build.TaskFailed()</filename>
1390 </para></listitem>
1391 <listitem><para>
1392 <filename>bb.build.TaskSucceeded()</filename>
1393 </para></listitem>
1394 <listitem><para>
1395 <filename>bb.event.BuildCompleted()</filename>
1396 </para></listitem>
1397 <listitem><para>
1398 <filename>bb.cooker.CookerExit()</filename>
1399 </para></listitem>
1400 </itemizedlist>
1401 Here is a list of other events that occur based on specific requests
1402 to the server:
1403 <itemizedlist>
1404 <listitem><para>
1405 <filename>bb.event.TreeDataPreparationStarted()</filename>
1406 </para></listitem>
1407 <listitem><para>
1408 <filename>bb.event.TreeDataPreparationProgress</filename>
1409 </para></listitem>
1410 <listitem><para>
1411 <filename>bb.event.TreeDataPreparationCompleted</filename>
1412 </para></listitem>
1413 <listitem><para>
1414 <filename>bb.event.DepTreeGenerated</filename>
1415 </para></listitem>
1416 <listitem><para>
1417 <filename>bb.event.CoreBaseFilesFound</filename>
1418 </para></listitem>
1419 <listitem><para>
1420 <filename>bb.event.ConfigFilePathFound</filename>
1421 </para></listitem>
1422 <listitem><para>
1423 <filename>bb.event.FilesMatchingFound</filename>
1424 </para></listitem>
1425 <listitem><para>
1426 <filename>bb.event.ConfigFilesFound</filename>
1427 </para></listitem>
1428 <listitem><para>
1429 <filename>bb.event.TargetsTreeGenerated</filename>
1430 </para></listitem>
1431 </itemizedlist>
1432 </para>
1433 </section>
1434
1435 <section id='variants-class-extension-mechanism'>
1436 <title>Variants - Class Extension Mechanism</title>
1437
1438 <para>
1439 BitBake supports two features that facilitate creating
1440 from a single recipe file multiple incarnations of that
1441 recipe file where all incarnations are buildable.
1442 These features are enabled through the
1443 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
1444 and
1445 <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link>
1446 variables.
1447 <note>
1448 The mechanism for this class extension is extremely
1449 specific to the implementation.
1450 Usually, the recipe's
1451 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>,
1452 <link linkend='var-PN'><filename>PN</filename></link>, and
1453 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1454 variables would need to be modified by the extension class.
1455 For specific examples, see the OE-Core
1456 <filename>native</filename>, <filename>nativesdk</filename>,
1457 and <filename>multilib</filename> classes.
1458 </note>
1459 <itemizedlist>
1460 <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis>
1461 This variable is a space separated list of classes used to "extend" the
1462 recipe for each variant.
1463 Here is an example that results in a second incarnation of the current
1464 recipe being available.
1465 This second incarnation will have the "native" class inherited.
1466 <literallayout class='monospaced'>
1467 BBCLASSEXTEND = "native"
1468 </literallayout></para></listitem>
1469 <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis>
1470 This variable allows a single recipe to build multiple versions of a
1471 project from a single recipe file.
1472 You can also specify conditional metadata
1473 (using the
1474 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1475 mechanism) for a single version, or an optionally named range of versions.
1476 Here is an example:
1477 <literallayout class='monospaced'>
1478 BBVERSIONS = "1.0 2.0 git"
1479 SRC_URI_git = "git://someurl/somepath.git"
1480
1481 BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
1482 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
1483 </literallayout>
1484 The name of the range defaults to the original version of the
1485 recipe.
1486 For example, in OpenEmbedded, the recipe file
1487 <filename>foo_1.0.0+.bb</filename> creates a default name range
1488 of <filename>1.0.0+</filename>.
1489 This is useful because the range name is not only placed
1490 into overrides, but it is also made available for the metadata to use
1491 in the variable that defines the base recipe versions for use in
1492 <filename>file://</filename> search paths
1493 (<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>).
1494 </para></listitem>
1495 </itemizedlist>
1496 </para>
1497 </section>
1498
1499 <section id='dependencies'>
1500 <title>Dependencies</title>
1501
1502 <para>
1503 To allow for efficient operation given multiple processes
1504 executing in parallel, BitBake handles dependencies at
1505 the task level.
1506 BitBake supports a robust method to handle these dependencies.
1507 </para>
1508
1509 <para>
1510 This section describes several types of dependency mechanisms.
1511 </para>
1512
1513 <section id='dependencies-internal-to-the-bb-file'>
1514 <title>Dependencies Internal to the <filename>.bb</filename> File</title>
1515
1516 <para>
1517 BitBake uses the <filename>addtask</filename> directive
1518 to manage dependencies that are internal to a given recipe
1519 file.
1520 You can use the <filename>addtask</filename> directive to
1521 indicate when a task is dependent on other tasks or when
1522 other tasks depend on that recipe.
1523 Here is an example:
1524 <literallayout class='monospaced'>
1525 addtask printdate after do_fetch before do_build
1526 </literallayout>
1527 In this example, the <filename>printdate</filename> task is
1528 depends on the completion of the <filename>do_fetch</filename>
1529 task.
1530 And, the <filename>do_build</filename> depends on the completion
1531 of the <filename>printdate</filename> task.
1532 </para>
1533 </section>
1534
1535 <section id='build-dependencies'>
1536 <title>Build Dependencies</title>
1537
1538 <para>
1539 BitBake uses the
1540 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1541 variable to manage build time dependencies.
1542 The "deptask" varflag for tasks signifies the task of each
1543 item listed in <filename>DEPENDS</filename> that must
1544 complete before that task can be executed.
1545 Here is an example:
1546 <literallayout class='monospaced'>
1547 do_configure[deptask] = "do_populate_sysroot"
1548 </literallayout>
1549 In this example, the <filename>do_populate_sysroot</filename>
1550 task of each item in <filename>DEPENDS</filename> must complete before
1551 <filename>do_configure</filename> can execute.
1552 </para>
1553 </section>
1554
1555 <section id='runtime-dependencies'>
1556 <title>Runtime Dependencies</title>
1557
1558 <para>
1559 BitBake uses the
1560 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
1561 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, and
1562 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1563 variables to manage runtime dependencies.
1564 </para>
1565
1566 <para>
1567 The <filename>PACKAGES</filename> variable lists runtime
1568 packages.
1569 Each of those packages can have <filename>RDEPENDS</filename> and
1570 <filename>RRECOMMENDS</filename> runtime dependencies.
1571 The "rdeptask" flag for tasks is used to signify the task of each
1572 item runtime dependency which must have completed before that
1573 task can be executed.
1574 <literallayout class='monospaced'>
1575 do_package_qa[rdeptask] = "do_packagedata"
1576 </literallayout>
1577 In the previous example, the <filename>do_packagedata</filename>
1578 task of each item in <filename>RDEPENDS</filename> must have
1579 completed before <filename>do_package_qa</filename> can execute.
1580 </para>
1581 </section>
1582
1583 <section id='recursive-dependencies'>
1584 <title>Recursive Dependencies</title>
1585
1586 <para>
1587 BitBake uses the "recrdeptask" flag to manage
1588 recursive task dependencies.
1589 BitBake looks through the build-time and runtime
1590 dependencies of the current recipe, looks through
1591 the task's inter-task
1592 dependencies, and then adds dependencies for the
1593 listed task.
1594 Once BitBake has accomplished this, it recursively works through
1595 the dependencies of those tasks.
1596 Iterative passes continue until all dependencies are discovered
1597 and added.
1598 </para>
1599
1600 <para>
1601 You might want to not only have BitBake look for
1602 dependencies of those tasks, but also have BitBake look
1603 for build-time and runtime dependencies of the dependent
1604 tasks as well.
1605 If that is the case, you need to reference the task name
1606 itself in the task list:
1607 <literallayout class='monospaced'>
1608 do_a[recrdeptask] = "do_a do_b"
1609 </literallayout>
1610 </para>
1611 </section>
1612
1613 <section id='inter-task-dependencies'>
1614 <title>Inter-Task Dependencies</title>
1615
1616 <para>
1617 BitBake uses the "depends" flag in a more generic form
1618 to manage inter-task dependencies.
1619 This more generic form allows for inter-dependency
1620 checks for specific tasks rather than checks for
1621 the data in <filename>DEPENDS</filename>.
1622 Here is an example:
1623 <literallayout class='monospaced'>
1624 do_patch[depends] = "quilt-native:do_populate_sysroot"
1625 </literallayout>
1626 In this example, the <filename>do_populate_sysroot</filename>
1627 task of the target <filename>quilt-native</filename>
1628 must have completed before the
1629 <filename>do_patch</filename> task can execute.
1630 </para>
1631
1632 <para>
1633 The "rdepends" flag works in a similar way but takes targets
1634 in the runtime namespace instead of the build-time dependency
1635 namespace.
1636 </para>
1637 </section>
1638 </section>
1639
1640 <section id='accessing-datastore-variables-using-python'>
1641 <title>Accessing Datastore Variables Using Python</title>
1642
1643 <para>
1644 It is often necessary to access variables in the
1645 BitBake datastore using Python functions.
1646 The Bitbake datastore has an API that allows you this
1647 access.
1648 Here is a list of available operations:
1649 </para>
1650
1651 <para>
1652 <informaltable frame='none'>
1653 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
1654 <colspec colname='c1' colwidth='1*'/>
1655 <colspec colname='c2' colwidth='1*'/>
1656 <thead>
1657 <row>
1658 <entry align="left"><emphasis>Operation</emphasis></entry>
1659 <entry align="left"><emphasis>Description</emphasis></entry>
1660 </row>
1661 </thead>
1662 <tbody>
1663 <row>
1664 <entry align="left"><filename>d.getVar("X", expand=False)</filename></entry>
1665 <entry align="left">Returns the value of variable "X".
1666 Using "expand=True" expands the value.</entry>
1667 </row>
1668 <row>
1669 <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
1670 <entry align="left">Sets the variable "X" to "value".</entry>
1671 </row>
1672 <row>
1673 <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
1674 <entry align="left">Adds "value" to the end of the variable "X".</entry>
1675 </row>
1676 <row>
1677 <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
1678 <entry align="left">Adds "value" to the start of the variable "X".</entry>
1679 </row>
1680 <row>
1681 <entry align="left"><filename>d.delVar("X")</filename></entry>
1682 <entry align="left">Deletes the variable "X" from the datastore.</entry>
1683 </row>
1684 <row>
1685 <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
1686 <entry align="left">Renames the variable "X" to "Y".</entry>
1687 </row>
1688 <row>
1689 <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
1690 <entry align="left">Gets then named flag from the variable "X".
1691 Using "expand=True" expands the named flag.</entry>
1692 </row>
1693 <row>
1694 <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
1695 <entry align="left">Sets the named flag for variable "X" to "value".</entry>
1696 </row>
1697 <row>
1698 <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
1699 <entry align="left">Appends "value" to the named flag on the
1700 variable "X".</entry>
1701 </row>
1702 <row>
1703 <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
1704 <entry align="left">Prepends "value" to the named flag on
1705 the variable "X".</entry>
1706 </row>
1707 <row>
1708 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
1709 <entry align="left">Deletes the named flag on the variable
1710 "X" from the datastore.</entry>
1711 </row>
1712 <row>
1713 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
1714 <entry align="left">Sets the flags specified in
1715 the <filename>flagsdict()</filename> parameter.
1716 <filename>setVarFlags</filename> does not clear previous flags.
1717 Think of this operation as <filename>addVarFlags</filename>.</entry>
1718 </row>
1719 <row>
1720 <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
1721 <entry align="left">Returns a <filename>flagsdict</filename> of the flags for
1722 the variable "X".</entry>
1723 </row>
1724 <row>
1725 <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
1726 <entry align="left">Deletes all the flags for the variable "X".</entry>
1727 </row>
1728 </tbody>
1729 </tgroup>
1730 </informaltable>
1731 </para>
1732 </section>
1733
1734 <section id='task-checksums-and-setscene'>
1735 <title>Task Checksums and Setscene</title>
1736
1737 <para>
1738 BitBake uses checksums (or signatures) along with the setscene
1739 to determine if a task needs to be run.
1740 This section describes the process.
1741 To help understand how BitBake does this, the section assumes an
1742 OpenEmbedded metadata-based example.
1743 </para>
1744
1745 <para>
1746 This list is a place holder of content existed from previous work
1747 on the manual.
1748 Some or all of it probably needs integrated into the subsections
1749 that make up this section.
1750 For now, I have just provided a short glossary-like description
1751 for each variable.
1752 Ultimately, this list goes away.
1753 <itemizedlist>
1754 <listitem><para><filename>STAMP</filename>:
1755 The base path to create stamp files.</para></listitem>
1756 <listitem><para><filename>STAMPCLEAN</filename>
1757 Again, the base path to create stamp files but can use wildcards
1758 for matching a range of files for clean operations.
1759 </para></listitem>
1760 <listitem><para><filename>BB_STAMP_WHITELIST</filename>
1761 Lists stamp files that are looked at when the stamp policy
1762 is "whitelist".
1763 </para></listitem>
1764 <listitem><para><filename>BB_STAMP_POLICY</filename>
1765 Defines the mode for comparing timestamps of stamp files.
1766 </para></listitem>
1767 <listitem><para><filename>BB_HASHCHECK_FUNCTION</filename>
1768 Specifies the name of the function to call during
1769 the "setscene" part of the task's execution in order
1770 to validate the list of task hashes.
1771 </para></listitem>
1772 <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
1773 Specifies a function to call that verifies the list of
1774 planned task execution before the main task execution
1775 happens.
1776 </para></listitem>
1777 <listitem><para><filename>BB_SETSCENE_DEPVALID</filename>
1778 Specifies a function BitBake calls that determines
1779 whether BitBake requires a setscene dependency to
1780 be met.
1781 </para></listitem>
1782 <listitem><para><filename>BB_TASKHASH</filename>
1783 Within an executing task, this variable holds the hash
1784 of the task as returned by the currently enabled
1785 signature generator.
1786 </para></listitem>
1787 </itemizedlist>
1788 </para>
1789 </section>
1790</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
new file mode 100644
index 0000000000..988719d038
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
@@ -0,0 +1,2152 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used by BitBake and gives an overview
12 of their function and contents.
13</para>
14
15<note>
16 Following are some points regarding the variables listed in this glossary:
17 <itemizedlist>
18 <listitem><para>The variables listed in this glossary
19 are specific to BitBake.
20 Consequently, the descriptions are limited to that context.
21 </para></listitem>
22 <listitem><para>Also, variables exist in other systems that use BitBake
23 (e.g. The Yocto Project and OpenEmbedded) that have names identical
24 to those found in this glossary.
25 For such cases, the variables in those systems extend the
26 functionality of the variable as it is described here in
27 this glossary.
28 </para></listitem>
29 <listitem><para>Finally, there are variables mentioned in this
30 glossary that do not appear in the BitBake glossary.
31 These other variables are variables used in systems that use
32 BitBake.
33 </para></listitem>
34 </itemizedlist>
35</note>
36
37<glossary id='ref-variables-glossary'>
38
39 <para>
40 <link linkend='var-ASSUME_PROVIDED'>A</link>
41 <link linkend='var-B'>B</link>
42 <link linkend='var-CACHE'>C</link>
43 <link linkend='var-DEFAULT_PREFERENCE'>D</link>
44 <link linkend='var-EXCLUDE_FROM_WORLD'>E</link>
45 <link linkend='var-FAKEROOT'>F</link>
46<!-- <link linkend='var-GROUPADD_PARAM'>G</link> -->
47 <link linkend='var-HOMEPAGE'>H</link>
48<!-- <link linkend='var-ICECC_DISABLED'>I</link> -->
49<!-- <link linkend='var-glossary-j'>J</link> -->
50<!-- <link linkend='var-KARCH'>K</link> -->
51 <link linkend='var-LAYERDEPENDS'>L</link>
52 <link linkend='var-MIRRORS'>M</link>
53<!-- <link linkend='var-glossary-n'>N</link> -->
54 <link linkend='var-OVERRIDES'>O</link>
55 <link linkend='var-PACKAGES'>P</link>
56<!-- <link linkend='var-QMAKE_PROFILES'>Q</link> -->
57 <link linkend='var-RDEPENDS'>R</link>
58 <link linkend='var-SECTION'>S</link>
59 <link linkend='var-T'>T</link>
60<!-- <link linkend='var-UBOOT_CONFIG'>U</link> -->
61<!-- <link linkend='var-glossary-v'>V</link> -->
62<!-- <link linkend='var-WARN_QA'>W</link> -->
63<!-- <link linkend='var-glossary-x'>X</link> -->
64<!-- <link linkend='var-glossary-y'>Y</link> -->
65<!-- <link linkend='var-glossary-z'>Z</link>-->
66 </para>
67
68 <glossdiv id='var-glossary-a'><title>A</title>
69
70 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
71 <glossdef>
72 <para>
73 Lists recipe names
74 (<link linkend='var-PN'><filename>PN</filename></link>
75 values) BitBake does not attempt to build.
76 Instead, BitBake assumes these recipes have already been
77 built.
78 </para>
79
80 <para>
81 In OpenEmbedded Core, <filename>ASSUME_PROVIDED</filename>
82 mostly specifies native tools that should not be built.
83 An example is <filename>git-native</filename>, which
84 when specified allows for the Git binary from the host to
85 be used rather than building
86 <filename>git-native</filename>.
87 </para>
88 </glossdef>
89 </glossentry>
90
91 </glossdiv>
92
93
94 <glossdiv id='var-glossary-b'><title>B</title>
95
96 <glossentry id='var-B'><glossterm>B</glossterm>
97 <glossdef>
98 <para>
99 The directory in which BitBake executes functions
100 during a recipe's build process.
101 </para>
102 </glossdef>
103 </glossentry>
104
105 <glossentry id='var-BB_CONSOLELOG'><glossterm>BB_CONSOLELOG</glossterm>
106 <glossdef>
107 <para>
108 Specifies the path to a log file into which BitBake's user
109 interface writes output during the build.
110 </para>
111 </glossdef>
112 </glossentry>
113
114 <glossentry id='var-BB_CURRENTTASK'><glossterm>BB_CURRENTTASK</glossterm>
115 <glossdef>
116 <para>
117 Contains the name of the currently running task.
118 The name does not include the
119 <filename>do_</filename> prefix.
120 </para>
121 </glossdef>
122 </glossentry>
123
124 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
125 <glossdef>
126 <para>
127 Defines how BitBake handles situations where an append
128 file (<filename>.bbappend</filename>) has no
129 corresponding recipe file (<filename>.bb</filename>).
130 This condition often occurs when layers get out of sync
131 (e.g. <filename>oe-core</filename> bumps a
132 recipe version and the old recipe no longer exists and the
133 other layer has not been updated to the new version
134 of the recipe yet).
135 </para>
136
137 <para>
138 The default fatal behavior is safest because it is
139 the sane reaction given something is out of sync.
140 It is important to realize when your changes are no longer
141 being applied.
142 </para>
143 </glossdef>
144 </glossentry>
145
146 <glossentry id='var-BB_DEFAULT_TASK'><glossterm>BB_DEFAULT_TASK</glossterm>
147 <glossdef>
148 <para>
149 The default task to use when none is specified (e.g.
150 with the <filename>-c</filename> command line option).
151 The task name specified should not include the
152 <filename>do_</filename> prefix.
153 </para>
154 </glossdef>
155 </glossentry>
156
157 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
158 <glossdef>
159 <para>
160 Monitors disk space and available inodes during the build
161 and allows you to control the build based on these
162 parameters.
163 </para>
164
165 <para>
166 Disk space monitoring is disabled by default.
167 When setting this variable, use the following form:
168 <literallayout class='monospaced'>
169 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
170
171 where:
172
173 &lt;action&gt; is:
174 ABORT: Immediately abort the build when
175 a threshold is broken.
176 STOPTASKS: Stop the build after the currently
177 executing tasks have finished when
178 a threshold is broken.
179 WARN: Issue a warning but continue the
180 build when a threshold is broken.
181 Subsequent warnings are issued as
182 defined by the
183 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
184 which must be defined.
185
186 &lt;dir&gt; is:
187 Any directory you choose. You can specify one or
188 more directories to monitor by separating the
189 groupings with a space. If two directories are
190 on the same device, only the first directory
191 is monitored.
192
193 &lt;threshold&gt; is:
194 Either the minimum available disk space,
195 the minimum number of free inodes, or
196 both. You must specify at least one. To
197 omit one or the other, simply omit the value.
198 Specify the threshold using G, M, K for Gbytes,
199 Mbytes, and Kbytes, respectively. If you do
200 not specify G, M, or K, Kbytes is assumed by
201 default. Do not use GB, MB, or KB.
202 </literallayout>
203 </para>
204
205 <para>
206 Here are some examples:
207 <literallayout class='monospaced'>
208 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
209 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
210 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
211 </literallayout>
212 The first example works only if you also set
213 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable.
214 This example causes the build system to immediately
215 abort when either the disk space in <filename>${TMPDIR}</filename> drops
216 below 1 Gbyte or the available free inodes drops below
217 100 Kbytes.
218 Because two directories are provided with the variable, the
219 build system also issues a
220 warning when the disk space in the
221 <filename>${SSTATE_DIR}</filename> directory drops
222 below 1 Gbyte or the number of free inodes drops
223 below 100 Kbytes.
224 Subsequent warnings are issued during intervals as
225 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
226 variable.
227 </para>
228
229 <para>
230 The second example stops the build after all currently
231 executing tasks complete when the minimum disk space
232 in the <filename>${TMPDIR}</filename>
233 directory drops below 1 Gbyte.
234 No disk monitoring occurs for the free inodes in this case.
235 </para>
236
237 <para>
238 The final example immediately aborts the build when the
239 number of free inodes in the <filename>${TMPDIR}</filename> directory
240 drops below 100 Kbytes.
241 No disk space monitoring for the directory itself occurs
242 in this case.
243 </para>
244 </glossdef>
245 </glossentry>
246
247 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
248 <glossdef>
249 <para>
250 Defines the disk space and free inode warning intervals.
251 </para>
252
253 <para>
254 If you are going to use the
255 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
256 also use the
257 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
258 and define its action as "WARN".
259 During the build, subsequent warnings are issued each time
260 disk space or number of free inodes further reduces by
261 the respective interval.
262 </para>
263
264 <para>
265 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
266 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
267 the "WARN" action, the disk monitoring interval defaults to
268 the following:
269 <literallayout class='monospaced'>
270 BB_DISKMON_WARNINTERVAL = "50M,5K"
271 </literallayout>
272 </para>
273
274 <para>
275 When specifying the variable in your configuration file,
276 use the following form:
277 <literallayout class='monospaced'>
278 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
279
280 where:
281
282 &lt;disk_space_interval&gt; is:
283 An interval of memory expressed in either
284 G, M, or K for Gbytes, Mbytes, or Kbytes,
285 respectively. You cannot use GB, MB, or KB.
286
287 &lt;disk_inode_interval&gt; is:
288 An interval of free inodes expressed in either
289 G, M, or K for Gbytes, Mbytes, or Kbytes,
290 respectively. You cannot use GB, MB, or KB.
291 </literallayout>
292 </para>
293
294 <para>
295 Here is an example:
296 <literallayout class='monospaced'>
297 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
298 BB_DISKMON_WARNINTERVAL = "50M,5K"
299 </literallayout>
300 These variables cause BitBake to
301 issue subsequent warnings each time the available
302 disk space further reduces by 50 Mbytes or the number
303 of free inodes further reduces by 5 Kbytes in the
304 <filename>${SSTATE_DIR}</filename> directory.
305 Subsequent warnings based on the interval occur each time
306 a respective interval is reached beyond the initial warning
307 (i.e. 1 Gbytes and 100 Kbytes).
308 </para>
309 </glossdef>
310 </glossentry>
311
312 <glossentry id='var-BB_ENV_WHITELIST'><glossterm>BB_ENV_WHITELIST</glossterm>
313 <glossdef>
314 <para>
315 Specifies the internal whitelist of variables to allow
316 through from the external environment into BitBake's
317 datastore.
318 If the value of this variable is not specified
319 (which is the default), the following list is used:
320 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>,
321 <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>,
322 <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>,
323 and
324 <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>.
325 <note>
326 You must set this variable in the external environment
327 in order for it to work.
328 </note>
329 </para>
330 </glossdef>
331 </glossentry>
332
333 <glossentry id='var-BB_ENV_EXTRAWHITE'><glossterm>BB_ENV_EXTRAWHITE</glossterm>
334 <glossdef>
335 <para>
336 Specifies an additional set of variables to allow through
337 (whitelist) from the external environment into BitBake's
338 datastore.
339 This list of variables are on top of the internal list
340 set in
341 <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>.
342 <note>
343 You must set this variable in the external
344 environment in order for it to work.
345 </note>
346 </para>
347 </glossdef>
348 </glossentry>
349
350 <glossentry id='var-BB_FETCH_PREMIRRORONLY'><glossterm>BB_FETCH_PREMIRRORONLY</glossterm>
351 <glossdef>
352 <para>
353 When set to "1", causes BitBake's fetcher module to only
354 search
355 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
356 for files.
357 BitBake will not search the main
358 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
359 or
360 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>.
361 </para>
362 </glossdef>
363 </glossentry>
364
365 <glossentry id='var-BB_FILENAME'><glossterm>BB_FILENAME</glossterm>
366 <glossdef>
367 <para>
368 Contains the filename of the recipe that owns the currently
369 running task.
370 For example, if the <filename>do_fetch</filename> task that
371 resides in the <filename>my-recipe.bb</filename> is
372 executing, the <filename>BB_FILENAME</filename> variable
373 contains "/foo/path/my-recipe.bb".
374 </para>
375 </glossdef>
376 </glossentry>
377
378 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
379 <glossdef>
380 <para>
381 Causes tarballs of the Git repositories, including the
382 Git metadata, to be placed in the
383 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
384 directory.
385 Anyone wishing to create a source mirror would want to
386 enable this variable.
387 </para>
388
389 <para>
390 For performance reasons, creating and placing tarballs of
391 the Git repositories is not the default action by BitBake.
392 <literallayout class='monospaced'>
393 BB_GENERATE_MIRROR_TARBALLS = "1"
394 </literallayout>
395 </para>
396 </glossdef>
397 </glossentry>
398
399 <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm>
400 <glossdef>
401 <para>
402 Lists variables that are excluded from base configuration
403 checksum, which is used to determine if the cache can
404 be reused.
405 </para>
406
407 <para>
408 One of the ways BitBake determines whether to re-parse the
409 main metadata is through checksums of the variables in the
410 datastore of the base configuration data.
411 There are variables that you typically want to exclude when
412 checking whether or not to re-parse and thus rebuild the
413 cache.
414 As an example, you would usually exclude
415 <filename>TIME</filename> and <filename>DATE</filename>
416 because these variables are always changing.
417 If you did not exclude them, BitBake would never reuse the
418 cache.
419 </para>
420 </glossdef>
421 </glossentry>
422
423 <glossentry id='var-BB_HASHBASE_WHITELIST'><glossterm>BB_HASHBASE_WHITELIST</glossterm>
424 <glossdef>
425 <para>
426 Lists variables that are excluded from checksum and
427 dependency data.
428 Variables that are excluded can therefore change without
429 affecting the checksum mechanism.
430 A common example would be the variable for the path of
431 the build.
432 BitBake's output should not (and usually does not) depend
433 on the directory in which it was built.
434 </para>
435 </glossdef>
436 </glossentry>
437
438 <glossentry id='var-BB_HASHCHECK_FUNCTION'><glossterm>BB_HASHCHECK_FUNCTION</glossterm>
439 <glossdef>
440 <para>
441 Specifies the name of the function to call during the
442 "setscene" part of the task's execution in order to
443 validate the list of task hashes.
444 The function returns the list of setscene tasks that should
445 be executed.
446 </para>
447
448 <para>
449 At this point in the execution of the code, the objective
450 is to quickly verify if a given setscene function is likely
451 to work or not.
452 It's easier to check the list of setscene functions in
453 one pass than to call many individual tasks.
454 The returned list need not be completely accurate.
455 A given setscene task can still later fail.
456 However, the more accurate the data returned, the more
457 efficient the build will be.
458 </para>
459 </glossdef>
460 </glossentry>
461
462 <glossentry id='var-BB_INVALIDCONF'><glossterm>BB_INVALIDCONF</glossterm>
463 <glossdef>
464 <para>
465 Used in combination with the
466 <filename>ConfigParsed</filename> event to trigger
467 re-parsing the base metadata (i.e. all the
468 recipes).
469 The <filename>ConfigParsed</filename> event can set the
470 variable to trigger the re-parse.
471 You must be careful to avoid recursive loops with this
472 functionality.
473 </para>
474 </glossdef>
475 </glossentry>
476
477 <glossentry id='var-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
478 <glossdef>
479 <para>
480 Specifies the name of the log files saved into
481 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
482 By default, the <filename>BB_LOGFMT</filename> variable
483 is undefined and the log file names get created using the
484 following form:
485 <literallayout class='monospaced'>
486 log.{task}.{pid}
487 </literallayout>
488 If you want to force log files to take a specific name,
489 you can set this variable in a configuration file.
490 </para>
491 </glossdef>
492 </glossentry>
493
494 <glossentry id='var-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm>
495 <glossdef>
496 <para>
497 Allows BitBake to run at a specific priority
498 (i.e. nice level).
499 System permissions usually mean that BitBake can reduce its
500 priority but not raise it again.
501 See
502 <link linkend='var-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link>
503 for additional information.
504 </para>
505 </glossdef>
506 </glossentry>
507
508 <glossentry id='var-BB_NO_NETWORK'><glossterm>BB_NO_NETWORK</glossterm>
509 <glossdef>
510 <para>
511 Disables network access in the BitBake fetcher modules.
512 With this access disabled, any command that attempts to
513 access the network becomes an error.
514 </para>
515
516 <para>
517 Disabling network access is useful for testing source
518 mirrors, running builds when not connected to the Internet,
519 and when operating in certain kinds of firewall
520 environments.
521 </para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
526 <glossdef>
527 <para>
528 The maximum number of tasks BitBake should run in parallel
529 at any one time.
530 If your host development system supports multiple cores,
531 a good rule of thumb is to set this variable to twice the
532 number of cores.
533 </para>
534 </glossdef>
535 </glossentry>
536
537 <glossentry id='var-BB_NUMBER_PARSE_THREADS'><glossterm>BB_NUMBER_PARSE_THREADS</glossterm>
538 <glossdef>
539 <para>
540 Sets the number of threads BitBake uses when parsing.
541 By default, the number of threads is equal to the number
542 of cores on the system.
543 </para>
544 </glossdef>
545 </glossentry>
546
547 <glossentry id='var-BB_ORIGENV'><glossterm>BB_ORIGENV</glossterm>
548 <glossdef>
549 <para>
550 Contains a copy of the original external environment in
551 which BitBake was run.
552 The copy is taken before any whitelisted variable values
553 are filtered into BitBake's datastore.
554 <note>
555 The contents of this variable is a datastore object
556 that can be queried using the normal datastore
557 operations.
558 </note>
559 </para>
560 </glossdef>
561 </glossentry>
562
563 <glossentry id='var-BB_PRESERVE_ENV'><glossterm>BB_PRESERVE_ENV</glossterm>
564 <glossdef>
565 <para>
566 Disables whitelisting and instead allows all variables
567 through from the external environment into BitBake's
568 datastore.
569 <note>
570 You must set this variable in the external
571 environment in order for it to work.
572 </note>
573 </para>
574 </glossdef>
575 </glossentry>
576
577 <glossentry id='var-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm>
578 <glossdef>
579 <para>
580 Specifies the name of the executable script files
581 (i.e. run files) saved into
582 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
583 By default, the <filename>BB_RUNFMT</filename> variable
584 is undefined and the run file names get created using the
585 following form:
586 <literallayout class='monospaced'>
587 run.{task}.{pid}
588 </literallayout>
589 If you want to force run files to take a specific name,
590 you can set this variable in a configuration file.
591 </para>
592 </glossdef>
593 </glossentry>
594
595 <glossentry id='var-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm>
596 <glossdef>
597 <para>
598 Contains the name of the currently executing task.
599 The value does not include the "do_" prefix.
600 For example, if the currently executing task is
601 <filename>do_config</filename>, the value is
602 "config".
603 </para>
604 </glossdef>
605 </glossentry>
606
607 <glossentry id='var-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm>
608 <glossdef>
609 <para>
610 Selects the name of the scheduler to use for the
611 scheduling of BitBake tasks.
612 Three options exist:
613 <itemizedlist>
614 <listitem><para><emphasis>basic</emphasis> -
615 The basic framework from which everything derives.
616 Using this option causes tasks to be ordered
617 numerically as they are parsed.
618 </para></listitem>
619 <listitem><para><emphasis>speed</emphasis> -
620 Executes tasks first that have more tasks
621 depending on them.
622 The "speed" option is the default.
623 </para></listitem>
624 <listitem><para><emphasis>completion</emphasis> -
625 Causes the scheduler to try to complete a given
626 recipe once its build has started.
627 </para></listitem>
628 </itemizedlist>
629 </para>
630 </glossdef>
631 </glossentry>
632
633 <glossentry id='var-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm>
634 <glossdef>
635 <para>
636 Defines custom schedulers to import.
637 Custom schedulers need to be derived from the
638 <filename>RunQueueScheduler</filename> class.
639 </para>
640
641 <para>
642 For information how to select a scheduler, see the
643 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
644 variable.
645 </para>
646 </glossdef>
647 </glossentry>
648
649 <glossentry id='var-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm>
650 <glossdef>
651 <para>
652 Specifies a function BitBake calls that determines
653 whether BitBake requires a setscene dependency to be met.
654 </para>
655
656 <para>
657 When running a setscene task, BitBake needs to
658 know which dependencies of that setscene task also need
659 to be run.
660 Whether dependencies also need to be run is highly
661 dependent on the metadata.
662 The function specified by this variable returns a
663 "True" or "False" depending on whether the dependency needs
664 to be met.
665 </para>
666 </glossdef>
667 </glossentry>
668
669 <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION'><glossterm>BB_SETSCENE_VERIFY_FUNCTION</glossterm>
670 <glossdef>
671 <para>
672 Specifies a function to call that verifies the list of
673 planned task execution before the main task execution
674 happens.
675 The function is called once BitBake has a list of setscene
676 tasks that have run and either succeeded or failed.
677 </para>
678
679 <para>
680 The function allows for a task list check to see if they
681 make sense.
682 Even if BitBake was planning to skip a task, the
683 returned value of the function can force BitBake to run
684 the task, which is necessary under certain metadata
685 defined circumstances.
686 </para>
687 </glossdef>
688 </glossentry>
689
690 <glossentry id='var-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm>
691 <glossdef>
692 <para>
693 Lists variable flags (varflags)
694 that can be safely excluded from checksum
695 and dependency data for keys in the datastore.
696 When generating checksum or dependency data for keys in the
697 datastore, the flags set against that key are normally
698 included in the checksum.
699 </para>
700
701 <para>
702 For more information on varflags, see the
703 "<link linkend='variable-flags'>Variable Flags</link>"
704 section.
705 </para>
706 </glossdef>
707 </glossentry>
708
709 <glossentry id='var-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm>
710 <glossdef>
711 <para>
712 Defines the name of the signature handler BitBake uses.
713 The signature handler defines the way stamp files are
714 created and handled, if and how the signature is
715 incorporated into the stamps, and how the signature
716 itself is generated.
717 </para>
718
719 <para>
720 A new signature handler can be added by injecting a class
721 derived from the
722 <filename>SignatureGenerator</filename> class into the
723 global namespace.
724 </para>
725 </glossdef>
726 </glossentry>
727
728 <glossentry id='var-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm>
729 <glossdef>
730 <para>
731 Defines the behavior of the fetcher when it interacts with
732 source control systems and dynamic source revisions.
733 The <filename>BB_SRCREV_POLICY</filename> variable is
734 useful when working without a network.
735 </para>
736
737 <para>
738 The variable can be set using one of two policies:
739 <itemizedlist>
740 <listitem><para><emphasis>cache</emphasis> -
741 Retains the value the system obtained previously
742 rather than querying the source control system
743 each time.
744 </para></listitem>
745 <listitem><para><emphasis>clear</emphasis> -
746 Queries the source controls system every time.
747 With this policy, there is no cache.
748 The "clear" policy is the default.
749 </para></listitem>
750 </itemizedlist>
751 </para>
752 </glossdef>
753 </glossentry>
754
755 <glossentry id='var-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm>
756 <glossdef>
757 <para>
758 Defines the mode used for how timestamps of stamp files
759 are compared.
760 You can set the variable to one of the following modes:
761 <itemizedlist>
762 <listitem><para><emphasis>perfile</emphasis> -
763 Timestamp comparisons are only made
764 between timestamps of a specific recipe.
765 This is the default mode.
766 </para></listitem>
767 <listitem><para><emphasis>full</emphasis> -
768 Timestamp comparisons are made for all
769 dependencies.
770 </para></listitem>
771 <listitem><para><emphasis>whitelist</emphasis> -
772 Identical to "full" mode except timestamp
773 comparisons are made for recipes listed in the
774 <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>
775 variable.
776 </para></listitem>
777 </itemizedlist>
778 <note>
779 Stamp policies are largely obsolete with the
780 introduction of setscene tasks.
781 </note>
782 </para>
783 </glossdef>
784 </glossentry>
785
786 <glossentry id='var-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm>
787 <glossdef>
788 <para>
789 Lists files whose stamp file timestamps are compared when
790 the stamp policy mode is set to "whitelist".
791 For information on stamp policies, see the
792 <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>
793 variable.
794 </para>
795 </glossdef>
796 </glossentry>
797
798 <glossentry id='var-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm>
799 <glossdef>
800 <para>
801 Sets a more strict checksum mechanism for non-local URLs.
802 Setting this variable to a value causes BitBake
803 to report an error if it encounters a non-local URL
804 that does not have at least one checksum specified.
805 </para>
806 </glossdef>
807 </glossentry>
808
809 <glossentry id='var-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm>
810 <glossdef>
811 <para>
812 Allows specific tasks to change their priority
813 (i.e. nice level).
814 </para>
815
816 <para>
817 You can use this variable in combination with task
818 overrides to raise or lower priorities of specific tasks.
819 For example, on the
820 <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>
821 autobuilder, QEMU emulation in images is given a higher
822 priority as compared to build tasks to ensure that images
823 do not suffer timeouts on loaded systems.
824 </para>
825 </glossdef>
826 </glossentry>
827
828 <glossentry id='var-BB_TASKHASH'><glossterm>BB_TASKHASH</glossterm>
829 <glossdef>
830 <para>
831 Within an executing task, this variable holds the hash
832 of the task as returned by the currently enabled
833 signature generator.
834 </para>
835 </glossdef>
836 </glossentry>
837
838 <glossentry id='var-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm>
839 <glossdef>
840 <para>
841 Controls how verbose BitBake is during builds.
842 If set, shell scripts echo commands and shell script output
843 appears on standard out (stdout).
844 </para>
845 </glossdef>
846 </glossentry>
847
848 <glossentry id='var-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm>
849 <glossdef>
850 <para>
851 Specifies if the current context is executing a task.
852 BitBake sets this variable to "1" when a task is
853 being executed.
854 The value is not set when the task is in server context
855 during parsing or event handling.
856 </para>
857 </glossdef>
858 </glossentry>
859
860
861 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
862 <glossdef>
863 <para>
864 Allows you to extend a recipe so that it builds variants
865 of the software.
866 Some examples of these variants for recipes from the
867 OpenEmbedded Core metadata are "natives" such as
868 <filename>quilt-native</filename>, which is a copy of
869 Quilt built to run on the build system; "crosses" such
870 as <filename>gcc-cross</filename>, which is a compiler
871 built to run on the build machine but produces binaries
872 that run on the target <filename>MACHINE</filename>;
873 "nativesdk", which targets the SDK machine instead of
874 <filename>MACHINE</filename>; and "mulitlibs" in the form
875 "<filename>multilib:&lt;multilib_name&gt;</filename>".
876 </para>
877
878 <para>
879 To build a different variant of the recipe with a minimal
880 amount of code, it usually is as simple as adding the
881 variable to your recipe.
882 Here are two examples.
883 The "native" variants are from the OpenEmbedded Core
884 metadata:
885 <literallayout class='monospaced'>
886 BBCLASSEXTEND =+ "native nativesdk"
887 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
888 </literallayout>
889 </para>
890 </glossdef>
891 </glossentry>
892
893 <glossentry id='var-BBDEBUG'><glossterm>BBDEBUG</glossterm>
894 <glossdef>
895 <para>
896 Sets the BitBake debug output level to a specific value
897 as incremented by the <filename>-d</filename> command line
898 option.
899 <note>
900 You must set this variable in the external environment
901 in order for it to work.
902 </note>
903 </para>
904 </glossdef>
905 </glossentry>
906
907 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
908 <glossdef>
909 <para>Lists the names of configured layers.
910 These names are used to find the other <filename>BBFILE_*</filename>
911 variables.
912 Typically, each layer appends its name to this variable in its
913 <filename>conf/layer.conf</filename> file.
914 </para>
915 </glossdef>
916 </glossentry>
917
918 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
919 <glossdef>
920 <para>Variable that expands to match files from
921 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
922 in a particular layer.
923 This variable is used in the <filename>conf/layer.conf</filename> file and must
924 be suffixed with the name of the specific layer (e.g.
925 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
926 </glossdef>
927 </glossentry>
928
929 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
930 <glossdef>
931 <para>Assigns the priority for recipe files in each layer.</para>
932 <para>This variable is useful in situations where the same recipe appears in
933 more than one layer.
934 Setting this variable allows you to prioritize a
935 layer against other layers that contain the same recipe - effectively
936 letting you control the precedence for the multiple layers.
937 The precedence established through this variable stands regardless of a
938 recipe's version
939 (<link linkend='var-PV'><filename>PV</filename></link> variable).
940 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
941 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
942 lower precedence.</para>
943 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
944 precedence.
945 For example, the value 6 has a higher precedence than the value 5.
946 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
947 dependencies (see the
948 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
949 more information.
950 The default priority, if unspecified
951 for a layer with no dependencies, is the lowest defined priority + 1
952 (or 1 if no priorities are defined).</para>
953 <tip>
954 You can use the command <filename>bitbake-layers show-layers</filename> to list
955 all configured layers along with their priorities.
956 </tip>
957 </glossdef>
958 </glossentry>
959
960 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
961 <glossdef>
962 <para>List of recipe files BitBake uses to build software.</para>
963 </glossdef>
964 </glossentry>
965
966 <glossentry id='var-BBINCLUDED'><glossterm>BBINCLUDED</glossterm>
967 <glossdef>
968 <para>
969 Contains a space-separated list of all of all files that
970 BitBake's parser included during parsing of the current
971 file.
972 </para>
973 </glossdef>
974 </glossentry>
975
976 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
977 <glossdef>
978 <para>
979 If set to a value, enables printing the task log when
980 reporting a failed task.
981 </para>
982 </glossdef>
983 </glossentry>
984
985 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
986 <glossdef>
987 <para>
988 If
989 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
990 is set, specifies the maximum number of lines from the
991 task log file to print when reporting a failed task.
992 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
993 the entire log is printed.
994 </para>
995 </glossdef>
996 </glossentry>
997
998 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
999 <glossdef>
1000 <para>Lists the layers to enable during the build.
1001 This variable is defined in the <filename>bblayers.conf</filename> configuration
1002 file in the build directory.
1003 Here is an example:
1004 <literallayout class='monospaced'>
1005 BBLAYERS = " \
1006 /home/scottrif/poky/meta \
1007 /home/scottrif/poky/meta-yocto \
1008 /home/scottrif/poky/meta-yocto-bsp \
1009 /home/scottrif/poky/meta-mykernel \
1010 "
1011
1012 </literallayout>
1013 This example enables four layers, one of which is a custom, user-defined layer
1014 named <filename>meta-mykernel</filename>.
1015 </para>
1016 </glossdef>
1017 </glossentry>
1018
1019 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1020 <glossdef>
1021 <para>
1022 Prevents BitBake from processing recipes and recipe
1023 append files.
1024 </para>
1025
1026 <para>
1027 You can use the <filename>BBMASK</filename> variable
1028 to "hide" these <filename>.bb</filename> and
1029 <filename>.bbappend</filename> files.
1030 BitBake ignores any recipe or recipe append files that
1031 match the expression.
1032 It is as if BitBake does not see them at all.
1033 Consequently, matching files are not parsed or otherwise
1034 used by BitBake.</para>
1035 <para>
1036 The value you provide is passed to Python's regular
1037 expression compiler.
1038 The expression is compared against the full paths to
1039 the files.
1040 For complete syntax information, see Python's
1041 documentation at
1042 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
1043 </para>
1044
1045 <para>
1046 The following example uses a complete regular expression
1047 to tell BitBake to ignore all recipe and recipe append
1048 files in the <filename>meta-ti/recipes-misc/</filename>
1049 directory:
1050 <literallayout class='monospaced'>
1051 BBMASK = "meta-ti/recipes-misc/"
1052 </literallayout>
1053 If you want to mask out multiple directories or recipes,
1054 use the vertical bar to separate the regular expression
1055 fragments.
1056 This next example masks out multiple directories and
1057 individual recipes:
1058 <literallayout class='monospaced'>
1059 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
1060 BBMASK .= "|.*meta-oe/recipes-support/"
1061 BBMASK .= "|.*openldap"
1062 BBMASK .= "|.*opencv"
1063 BBMASK .= "|.*lzma"
1064 </literallayout>
1065 Notice how the vertical bar is used to append the fragments.
1066 <note>
1067 When specifying a directory name, use the trailing
1068 slash character to ensure you match just that directory
1069 name.
1070 </note>
1071 </para>
1072 </glossdef>
1073 </glossentry>
1074
1075 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1076 <glossdef>
1077 <para>
1078 Used by BitBake to locate class
1079 (<filename>.bbclass</filename>) and configuration
1080 (<filename>.conf</filename>) files.
1081 This variable is analogous to the
1082 <filename>PATH</filename> variable.
1083 </para>
1084
1085 <para>
1086 If you run BitBake from a directory outside of the
1087 build directory,
1088 you must be sure to set
1089 <filename>BBPATH</filename> to point to the
1090 build directory.
1091 Set the variable as you would any environment variable
1092 and then run BitBake:
1093 <literallayout class='monospaced'>
1094 $ BBPATH="&lt;build_directory&gt;"
1095 $ export BBPATH
1096 $ bitbake &lt;target&gt;
1097 </literallayout>
1098 </para>
1099 </glossdef>
1100 </glossentry>
1101
1102 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1103 <glossdef>
1104 <para>
1105 Points to the server that runs memory-resident BitBake.
1106 The variable is only used when you employ memory-resident
1107 BitBake.
1108 </para>
1109 </glossdef>
1110 </glossentry>
1111
1112 <glossentry id='var-BBVERSIONS'><glossterm>BBVERSIONS</glossterm>
1113 <glossdef>
1114 <para>
1115 Allows a single recipe to build multiple versions of a
1116 project from a single recipe file.
1117 You also able to specify conditional metadata
1118 using the
1119 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1120 mechanism for a single version or for an optionally named
1121 range of versions.
1122 </para>
1123
1124 <para>
1125 For more information on <filename>BBVERSIONS</filename>,
1126 see the
1127 "<link linkend='variants-class-extension-mechanism'>Variants - Class Extension Mechanism</link>"
1128 section.
1129 </para>
1130 </glossdef>
1131 </glossentry>
1132
1133 <glossentry id='var-BITBAKE_UI'><glossterm>BITBAKE_UI</glossterm>
1134 <glossdef>
1135 <para>
1136 Used to specify the UI module to use when running BitBake.
1137 Using this variable is equivalent to using the
1138 <filename>-u</filename> command-line option.
1139 <note>
1140 You must set this variable in the external environment
1141 in order for it to work.
1142 </note>
1143 </para>
1144 </glossdef>
1145 </glossentry>
1146
1147 <glossentry id='var-BUILDNAME'><glossterm>BUILDNAME</glossterm>
1148 <glossdef>
1149 <para>
1150 A name assigned to the build.
1151 The name defaults to a datetime stamp of when the build was
1152 started but can be defined by the metadata.
1153 </para>
1154 </glossdef>
1155 </glossentry>
1156
1157 </glossdiv>
1158
1159 <glossdiv id='var-glossary-c'><title>C</title>
1160
1161 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
1162 <glossdef>
1163 <para>
1164 Specifies the directory BitBake uses to store a cache
1165 of the metadata so it does not need to be parsed every
1166 time BitBake is started.
1167 </para>
1168 </glossdef>
1169 </glossentry>
1170
1171 </glossdiv>
1172
1173 <glossdiv id='var-glossary-d'><title>D</title>
1174
1175 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1176 <glossdef>
1177 <para>
1178 Specifies a weak bias for recipe selection priority.
1179 </para>
1180 <para>
1181 The most common usage of this is variable is to set
1182 it to "-1" within a recipe for a development version of a
1183 piece of software.
1184 Using the variable in this way causes the stable version
1185 of the recipe to build by default in the absence of
1186 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1187 being used to build the development version.
1188 </para>
1189 <note>
1190 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1191 is weak and is overridden by
1192 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1193 if that variable is different between two layers
1194 that contain different versions of the same recipe.
1195 </note>
1196 </glossdef>
1197 </glossentry>
1198
1199 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1200 <glossdef>
1201 <para>
1202 Lists a recipe's build-time dependencies
1203 (i.e. other recipe files).
1204 </para>
1205
1206 <para>
1207 Consider this simple example for two recipes named "a" and
1208 "b" that produce similarly named packages.
1209 In this example, the <filename>DEPENDS</filename>
1210 statement appears in the "a" recipe:
1211 <literallayout class='monospaced'>
1212 DEPENDS = "b"
1213 </literallayout>
1214 Here, the dependency is such that the
1215 <filename>do_configure</filename> task for recipe "a"
1216 depends on the <filename>do_populate_sysroot</filename>
1217 task of recipe "b".
1218 This means anything that recipe "b" puts into sysroot
1219 is available when recipe "a" is configuring itself.
1220 </para>
1221
1222 <para>
1223 For information on runtime dependencies, see the
1224 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1225 variable.
1226 </para>
1227 </glossdef>
1228 </glossentry>
1229
1230 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1231 <glossdef>
1232 <para>
1233 A long description for the recipe.
1234 </para>
1235 </glossdef>
1236 </glossentry>
1237
1238 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1239 <glossdef>
1240 <para>
1241 The central download directory used by the build process to
1242 store downloads.
1243 By default, <filename>DL_DIR</filename> gets files
1244 suitable for mirroring for everything except Git
1245 repositories.
1246 If you want tarballs of Git repositories, use the
1247 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1248 variable.
1249 </para>
1250 </glossdef>
1251
1252 </glossentry>
1253 </glossdiv>
1254
1255 <glossdiv id='var-glossary-e'><title>E</title>
1256
1257 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1258 <glossdef>
1259 <para>
1260 Directs BitBake to exclude a recipe from world builds (i.e.
1261 <filename>bitbake world</filename>).
1262 During world builds, BitBake locates, parses and builds all
1263 recipes found in every layer exposed in the
1264 <filename>bblayers.conf</filename> configuration file.
1265 </para>
1266
1267 <para>
1268 To exclude a recipe from a world build using this variable,
1269 set the variable to "1" in the recipe.
1270 </para>
1271
1272 <note>
1273 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1274 may still be built during a world build in order to satisfy
1275 dependencies of other recipes.
1276 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1277 only ensures that the recipe is not explicitly added
1278 to the list of build targets in a world build.
1279 </note>
1280 </glossdef>
1281 </glossentry>
1282
1283 </glossdiv>
1284
1285 <glossdiv id='var-glossary-f'><title>F</title>
1286
1287 <glossentry id='var-FAKEROOT'><glossterm>FAKEROOT</glossterm>
1288 <glossdef>
1289 <para>
1290 Contains the command to use when running a shell script
1291 in a fakeroot environment.
1292 The <filename>FAKEROOT</filename> variable is obsolete
1293 and has been replaced by the other
1294 <filename>FAKEROOT*</filename> variables.
1295 See these entries in the glossary for more information.
1296 </para>
1297 </glossdef>
1298 </glossentry>
1299
1300 <glossentry id='var-FAKEROOTBASEENV'><glossterm>FAKEROOTBASEENV</glossterm>
1301 <glossdef>
1302 <para>
1303 Lists environment variables to set when executing
1304 the command defined by
1305 <link linkend='var-FAKEROOTCMD'><filename>FAKEROOTCMD</filename></link>
1306 that starts the bitbake-worker process
1307 in the fakeroot environment.
1308 </para>
1309 </glossdef>
1310 </glossentry>
1311
1312 <glossentry id='var-FAKEROOTCMD'><glossterm>FAKEROOTCMD</glossterm>
1313 <glossdef>
1314 <para>
1315 Contains the command that starts the bitbake-worker
1316 process in the fakeroot environment.
1317 </para>
1318 </glossdef>
1319 </glossentry>
1320
1321 <glossentry id='var-FAKEROOTDIRS'><glossterm>FAKEROOTDIRS</glossterm>
1322 <glossdef>
1323 <para>
1324 Lists directories to create before running a task in
1325 the fakeroot environment.
1326 </para>
1327 </glossdef>
1328 </glossentry>
1329
1330 <glossentry id='var-FAKEROOTENV'><glossterm>FAKEROOTENV</glossterm>
1331 <glossdef>
1332 <para>
1333 Lists environment variables to set when running a task
1334 in the fakeroot environment.
1335 For additional information on environment variables and
1336 the fakeroot environment, see the
1337 <link linkend='var-FAKEROOTBASEENV'><filename>FAKEROOTBASEENV</filename></link>
1338 variable.
1339 </para>
1340 </glossdef>
1341 </glossentry>
1342
1343 <glossentry id='var-FAKEROOTNOENV'><glossterm>FAKEROOTNOENV</glossterm>
1344 <glossdef>
1345 <para>
1346 Lists environment variables to set when running a task
1347 that is not in the fakeroot environment.
1348 For additional information on environment variables and
1349 the fakeroot environment, see the
1350 <link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
1351 variable.
1352 </para>
1353 </glossdef>
1354 </glossentry>
1355
1356 <glossentry id='var-FETCHCMD'><glossterm>FETCHCMD</glossterm>
1357 <glossdef>
1358 <para>
1359 Defines the command the BitBake fetcher module
1360 executes when running fetch operations.
1361 You need to use an override suffix when you use the
1362 variable (e.g. <filename>FETCHCMD_git</filename>
1363 or <filename>FETCHCMD_svn</filename>).
1364 </para>
1365 </glossdef>
1366 </glossentry>
1367
1368 <glossentry id='var-FILE'><glossterm>FILE</glossterm>
1369 <glossdef>
1370 <para>
1371 Points at the current file.
1372 BitBake sets this variable during the parsing process
1373 to identify the file being parsed.
1374 BitBake also sets this variable when a recipe is being
1375 executed to identify the recipe file.
1376 </para>
1377 </glossdef>
1378 </glossentry>
1379
1380 <glossentry id='var-FILESDIR'><glossterm>FILESDIR</glossterm>
1381 <glossdef>
1382 <para>
1383 Specifies directories BitBake uses when searching for
1384 patches and files.
1385 The "local" fetcher module uses these directories when
1386 handling <filename>file://</filename> URLs if the file
1387 was not found using
1388 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
1389 <note>
1390 The <filename>FILESDIR</filename> variable is
1391 deprecated and you should use
1392 <filename>FILESPATH</filename> in all new code.
1393 </note>
1394 </para>
1395 </glossdef>
1396 </glossentry>
1397
1398 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1399 <glossdef>
1400 <para>
1401 Specifies directories BitBake uses when searching for
1402 patches and files.
1403 The "local" fetcher module uses these directories when
1404 handling <filename>file://</filename> URLs.
1405 The variable behaves like a shell <filename>PATH</filename>
1406 environment variable.
1407 The value is a colon-separated list of directories that
1408 are searched left-to-right in order.
1409 </para>
1410 </glossdef>
1411 </glossentry>
1412
1413 </glossdiv>
1414
1415<!--
1416 <glossdiv id='var-glossary-g'><title>G</title>
1417 </glossdiv>
1418-->
1419
1420 <glossdiv id='var-glossary-h'><title>H</title>
1421
1422 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1423 <glossdef>
1424 <para>Website where more information about the software the recipe is building
1425 can be found.</para>
1426 </glossdef>
1427 </glossentry>
1428
1429 </glossdiv>
1430
1431 <glossdiv id='var-glossary-i'><title>I</title>
1432
1433 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
1434 <glossdef>
1435 <para>
1436 Causes the named class to be inherited at
1437 this point during parsing.
1438 The variable is only valid in configuration files.
1439 </para>
1440 </glossdef>
1441 </glossentry>
1442
1443 </glossdiv>
1444
1445<!--
1446 <glossdiv id='var-glossary-j'><title>J</title>
1447 </glossdiv>
1448
1449 <glossdiv id='var-glossary-k'><title>K</title>
1450 </glossdiv>
1451-->
1452
1453 <glossdiv id='var-glossary-l'><title>L</title>
1454
1455 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
1456 <glossdef>
1457 <para>Lists the layers, separated by spaces, upon which this recipe depends.
1458 Optionally, you can specify a specific layer version for a dependency
1459 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1460 to be compared against
1461 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
1462 in this case).
1463 BitBake produces an error if any dependency is missing or
1464 the version numbers do not match exactly (if specified).</para>
1465 <para>
1466 You use this variable in the <filename>conf/layer.conf</filename> file.
1467 You must also use the specific layer name as a suffix
1468 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1469 </glossdef>
1470 </glossentry>
1471
1472 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
1473 <glossdef>
1474 <para>When used inside the <filename>layer.conf</filename> configuration
1475 file, this variable provides the path of the current layer.
1476 This variable is not available outside of <filename>layer.conf</filename>
1477 and references are expanded immediately when parsing of the file completes.</para>
1478 </glossdef>
1479 </glossentry>
1480
1481 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
1482 <glossdef>
1483 <para>Optionally specifies the version of a layer as a single number.
1484 You can use this variable within
1485 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
1486 for another layer in order to depend on a specific version
1487 of the layer.</para>
1488 <para>
1489 You use this variable in the <filename>conf/layer.conf</filename> file.
1490 You must also use the specific layer name as a suffix
1491 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1492 </glossdef>
1493 </glossentry>
1494
1495 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
1496 <glossdef>
1497 <para>
1498 The list of source licenses for the recipe.
1499 </para>
1500 </glossdef>
1501 </glossentry>
1502
1503 </glossdiv>
1504
1505 <glossdiv id='var-glossary-m'><title>M</title>
1506
1507 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
1508 <glossdef>
1509 <para>
1510 Specifies additional paths from which BitBake gets source code.
1511 When the build system searches for source code, it first
1512 tries the local download directory.
1513 If that location fails, the build system tries locations
1514 defined by
1515 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
1516 the upstream source, and then locations specified by
1517 <filename>MIRRORS</filename> in that order.
1518 </para>
1519 </glossdef>
1520 </glossentry>
1521
1522 <glossentry id='var-MULTI_PROVIDER_WHITELIST'><glossterm>MULTI_PROVIDER_WHITELIST</glossterm>
1523 <glossdef>
1524 <para>
1525 Allows you to suppress BitBake warnings caused when
1526 building two separate recipes that provide the same
1527 output.
1528 </para>
1529
1530 <para>
1531 Bitbake normally issues a warning when building two
1532 different recipes where each provides the same output.
1533 This scenario is usually something the user does not
1534 want.
1535 However, cases do exist where it makes sense, particularly
1536 in the <filename>virtual/*</filename> namespace.
1537 You can use this variable to suppress BitBake's warnings.
1538 </para>
1539
1540 <para>
1541 To use the variable, list provider names (e.g.
1542 recipe names, <filename>virtual/kernel</filename>,
1543 and so forth).
1544 </para>
1545 </glossdef>
1546 </glossentry>
1547
1548 </glossdiv>
1549
1550<!--
1551 <glossdiv id='var-glossary-n'><title>N</title>
1552 </glossdiv>
1553-->
1554
1555 <glossdiv id='var-glossary-o'><title>O</title>
1556
1557 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
1558 <glossdef>
1559 <para>
1560 BitBake uses <filename>OVERRIDES</filename> to control
1561 what variables are overridden after BitBake parses
1562 recipes and configuration files.
1563 </para>
1564
1565 <para>
1566 Following is a simple example that uses an overrides
1567 list based on machine architectures:
1568 <literallayout class='monospaced'>
1569 OVERRIDES = "arm:x86:mips:powerpc"
1570 </literallayout>
1571 You can find information on how to use
1572 <filename>OVERRIDES</filename> in the
1573 "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
1574 section.
1575 </para>
1576 </glossdef>
1577 </glossentry>
1578 </glossdiv>
1579
1580 <glossdiv id='var-glossary-p'><title>P</title>
1581
1582 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
1583 <glossdef>
1584 <para>The list of packages the recipe creates.
1585 </para>
1586 </glossdef>
1587 </glossentry>
1588
1589 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
1590 <glossdef>
1591 <para>
1592 A promise that your recipe satisfies runtime dependencies
1593 for optional modules that are found in other recipes.
1594 <filename>PACKAGES_DYNAMIC</filename>
1595 does not actually satisfy the dependencies, it only states that
1596 they should be satisfied.
1597 For example, if a hard, runtime dependency
1598 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
1599 of another package is satisfied during the build
1600 through the <filename>PACKAGES_DYNAMIC</filename>
1601 variable, but a package with the module name is never actually
1602 produced, then the other package will be broken.
1603 </para>
1604 </glossdef>
1605 </glossentry>
1606
1607 <glossentry id='var-PE'><glossterm>PE</glossterm>
1608 <glossdef>
1609 <para>
1610 The epoch of the recipe.
1611 By default, this variable is unset.
1612 The variable is used to make upgrades possible when the
1613 versioning scheme changes in some backwards incompatible
1614 way.
1615 </para>
1616 </glossdef>
1617 </glossentry>
1618
1619 <glossentry id='var-PERSISTENT_DIR'><glossterm>PERSISTENT_DIR</glossterm>
1620 <glossdef>
1621 <para>
1622 Specifies the directory BitBake uses to store data that
1623 should be preserved between builds.
1624 In particular, the data stored is the data that uses
1625 BitBake's persistent data API and the data used by the
1626 PR Server and PR Service.
1627 </para>
1628 </glossdef>
1629 </glossentry>
1630
1631 <glossentry id='var-PF'><glossterm>PF</glossterm>
1632 <glossdef>
1633 <para>
1634 Specifies the recipe or package name and includes all version and revision
1635 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
1636 <filename>bash-4.2-r1/</filename>).
1637 </para>
1638 </glossdef>
1639 </glossentry>
1640
1641 <glossentry id='var-PN'><glossterm>PN</glossterm>
1642 <glossdef>
1643 <para>The recipe name.</para>
1644 </glossdef>
1645 </glossentry>
1646
1647 <glossentry id='var-PR'><glossterm>PR</glossterm>
1648 <glossdef>
1649 <para>The revision of the recipe.
1650 </para>
1651 </glossdef>
1652 </glossentry>
1653
1654 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
1655 <glossdef>
1656 <para>
1657 Determines which recipe should be given preference when
1658 multiple recipes provide the same item.
1659 You should always suffix the variable with the name of the
1660 provided item, and you should set it to the
1661 <link linkend='var-PN'><filename>PN</filename></link>
1662 of the recipe to which you want to give precedence.
1663 Some examples:
1664 <literallayout class='monospaced'>
1665 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1666 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1667 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1668 </literallayout>
1669 </para>
1670 </glossdef>
1671 </glossentry>
1672
1673 <glossentry id='var-PREFERRED_PROVIDERS'><glossterm>PREFERRED_PROVIDERS</glossterm>
1674 <glossdef>
1675 <para>
1676 Determines which recipe should be given preference for
1677 cases where multiple recipes provide the same item.
1678 Functionally,
1679 <filename>PREFERRED_PROVIDERS</filename> is identical to
1680 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>.
1681 However, the <filename>PREFERRED_PROVIDERS</filename>
1682 variable lets you define preferences for multiple
1683 situations using the following form:
1684 <literallayout class='monospaced'>
1685 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1686 </literallayout>
1687 This form is a convenient replacement for the following:
1688 <literallayout class='monospaced'>
1689 PREFERRED_PROVIDER_xxx = "yyy"
1690 PREFERRED_PROVIDER_aaa = "bbb"
1691 </literallayout>
1692 </para>
1693 </glossdef>
1694 </glossentry>
1695
1696 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
1697 <glossdef>
1698 <para>
1699 If there are multiple versions of recipes available, this
1700 variable determines which recipe should be given preference.
1701 You must always suffix the variable with the
1702 <link linkend='var-PN'><filename>PN</filename></link>
1703 you want to select, and you should set
1704 <link linkend='var-PV'><filename>PV</filename></link>
1705 accordingly for precedence.
1706 You can use the "<filename>%</filename>" character as a
1707 wildcard to match any number of characters, which can be
1708 useful when specifying versions that contain long revision
1709 numbers that could potentially change.
1710 Here are two examples:
1711 <literallayout class='monospaced'>
1712 PREFERRED_VERSION_python = "2.7.3"
1713 PREFERRED_VERSION_linux-yocto = "3.10%"
1714 </literallayout>
1715 </para>
1716 </glossdef>
1717 </glossentry>
1718
1719 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
1720 <glossdef>
1721 <para>
1722 Specifies additional paths from which BitBake gets source code.
1723 When the build system searches for source code, it first
1724 tries the local download directory.
1725 If that location fails, the build system tries locations
1726 defined by <filename>PREMIRRORS</filename>, the upstream
1727 source, and then locations specified by
1728 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
1729 in that order.
1730 </para>
1731
1732 <para>
1733 Typically, you would add a specific server for the
1734 build system to attempt before any others by adding
1735 something like the following to your configuration:
1736 <literallayout class='monospaced'>
1737 PREMIRRORS_prepend = "\
1738 git://.*/.* http://www.yoctoproject.org/sources/ \n \
1739 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
1740 http://.*/.* http://www.yoctoproject.org/sources/ \n \
1741 https://.*/.* http://www.yoctoproject.org/sources/ \n"
1742 </literallayout>
1743 These changes cause the build system to intercept
1744 Git, FTP, HTTP, and HTTPS requests and direct them to
1745 the <filename>http://</filename> sources mirror.
1746 You can use <filename>file://</filename> URLs to point
1747 to local directories or network shares as well.
1748 </para>
1749 </glossdef>
1750 </glossentry>
1751
1752 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
1753 <glossdef>
1754 <para>
1755 A list of aliases by which a particular recipe can be
1756 known.
1757 By default, a recipe's own
1758 <filename><link linkend='var-PN'>PN</link></filename>
1759 is implicitly already in its <filename>PROVIDES</filename>
1760 list.
1761 If a recipe uses <filename>PROVIDES</filename>, the
1762 additional aliases are synonyms for the recipe and can
1763 be useful satisfying dependencies of other recipes during
1764 the build as specified by
1765 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
1766 </para>
1767
1768 <para>
1769 Consider the following example
1770 <filename>PROVIDES</filename> statement from a recipe
1771 file <filename>libav_0.8.11.bb</filename>:
1772 <literallayout class='monospaced'>
1773 PROVIDES += "libpostproc"
1774 </literallayout>
1775 The <filename>PROVIDES</filename> statement results in
1776 the "libav" recipe also being known as "libpostproc".
1777 </para>
1778 </glossdef>
1779 </glossentry>
1780
1781 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
1782 <glossdef>
1783 <para>
1784 The network based
1785 <link linkend='var-PR'><filename>PR</filename></link>
1786 service host and port.
1787 </para>
1788
1789 <para>
1790 Following is an example of how the <filename>PRSERV_HOST</filename> variable is
1791 set:
1792 <literallayout class='monospaced'>
1793 PRSERV_HOST = "localhost:0"
1794 </literallayout>
1795 You must set the variable if you want to automatically
1796 start a local PR service.
1797 You can set <filename>PRSERV_HOST</filename> to other
1798 values to use a remote PR service.
1799 </para>
1800 </glossdef>
1801 </glossentry>
1802
1803 <glossentry id='var-PV'><glossterm>PV</glossterm>
1804 <glossdef>
1805 <para>The version of the recipe.
1806 </para>
1807 </glossdef>
1808 </glossentry>
1809
1810 </glossdiv>
1811
1812<!--
1813 <glossdiv id='var-glossary-q'><title>Q</title>
1814 </glossdiv>
1815-->
1816
1817 <glossdiv id='var-glossary-r'><title>R</title>
1818
1819 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
1820 <glossdef>
1821 <para>
1822 Lists a package's runtime dependencies (i.e. other packages)
1823 that must be installed in order for the built package to run
1824 correctly.
1825 If a package in this list cannot be found during the build,
1826 you will get a build error.
1827 </para>
1828
1829 <para>
1830 Because the <filename>RDEPENDS</filename> variable applies
1831 to packages being built, you should always use the variable
1832 in a form with an attached package name.
1833 For example, suppose you are building a development package
1834 that depends on the <filename>perl</filename> package.
1835 In this case, you would use the following
1836 <filename>RDEPENDS</filename> statement:
1837 <literallayout class='monospaced'>
1838 RDEPENDS_${PN}-dev += "perl"
1839 </literallayout>
1840 In the example, the development package depends on
1841 the <filename>perl</filename> package.
1842 Thus, the <filename>RDEPENDS</filename> variable has the
1843 <filename>${PN}-dev</filename> package name as part of the
1844 variable.
1845 </para>
1846
1847 <para>
1848 BitBake supports specifying versioned dependencies.
1849 Although the syntax varies depending on the packaging
1850 format, BitBake hides these differences from you.
1851 Here is the general syntax to specify versions with
1852 the <filename>RDEPENDS</filename> variable:
1853 <literallayout class='monospaced'>
1854 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
1855 </literallayout>
1856 For <filename>operator</filename>, you can specify the
1857 following:
1858 <literallayout class='monospaced'>
1859 =
1860 &lt;
1861 &gt;
1862 &lt;=
1863 &gt;=
1864 </literallayout>
1865 For example, the following sets up a dependency on version
1866 1.2 or greater of the package <filename>foo</filename>:
1867 <literallayout class='monospaced'>
1868 RDEPENDS_${PN} = "foo (>= 1.2)"
1869 </literallayout>
1870 </para>
1871
1872 <para>
1873 For information on build-time dependencies, see the
1874 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1875 variable.
1876 </para>
1877 </glossdef>
1878 </glossentry>
1879
1880 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
1881 <glossdef>
1882 <para>
1883 A list of package name aliases that a package also provides.
1884 These aliases are useful for satisfying runtime dependencies
1885 of other packages both during the build and on the target
1886 (as specified by
1887 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
1888 </para>
1889 <para>
1890 As with all package-controlling variables, you must always
1891 use the variable in conjunction with a package name override.
1892 Here is an example:
1893 <literallayout class='monospaced'>
1894 RPROVIDES_${PN} = "widget-abi-2"
1895 </literallayout>
1896 </para>
1897 </glossdef>
1898 </glossentry>
1899
1900 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
1901 <glossdef>
1902 <para>
1903 A list of packages that extends the usability of a package
1904 being built.
1905 The package being built does not depend on this list of
1906 packages in order to successfully build, but needs them for
1907 the extended usability.
1908 To specify runtime dependencies for packages, see the
1909 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
1910 variable.
1911 </para>
1912
1913 <para>
1914 BitBake supports specifying versioned recommends.
1915 Although the syntax varies depending on the packaging
1916 format, BitBake hides these differences from you.
1917 Here is the general syntax to specify versions with
1918 the <filename>RRECOMMENDS</filename> variable:
1919 <literallayout class='monospaced'>
1920 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
1921 </literallayout>
1922 For <filename>operator</filename>, you can specify the
1923 following:
1924 <literallayout class='monospaced'>
1925 =
1926 &lt;
1927 &gt;
1928 &lt;=
1929 &gt;=
1930 </literallayout>
1931 For example, the following sets up a recommend on version
1932 1.2 or greater of the package <filename>foo</filename>:
1933 <literallayout class='monospaced'>
1934 RRECOMMENDS_${PN} = "foo (>= 1.2)"
1935 </literallayout>
1936 </para>
1937 </glossdef>
1938 </glossentry>
1939
1940 </glossdiv>
1941
1942 <glossdiv id='var-glossary-s'><title>S</title>
1943
1944 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
1945 <glossdef>
1946 <para>The section in which packages should be categorized.</para>
1947 </glossdef>
1948 </glossentry>
1949
1950 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
1951 <glossdef>
1952 <para>
1953 The list of source files - local or remote.
1954 This variable tells BitBake which bits
1955 to pull for the build and how to pull them.
1956 For example, if the recipe or append file needs to
1957 fetch a single tarball from the Internet, the recipe or
1958 append file uses a <filename>SRC_URI</filename>
1959 entry that specifies that tarball.
1960 On the other hand, if the recipe or append file needs to
1961 fetch a tarball and include a custom file, the recipe or
1962 append file needs an <filename>SRC_URI</filename> variable
1963 that specifies all those sources.</para>
1964 <para>The following list explains the available URI protocols:
1965 <itemizedlist>
1966 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
1967 Fetches files, which are usually files shipped with
1968 the metadata,
1969 from the local machine.
1970 The path is relative to the
1971 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
1972 variable.</para></listitem>
1973 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
1974 Bazaar revision control repository.</para></listitem>
1975 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
1976 Git revision control repository.</para></listitem>
1977 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
1978 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
1979 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
1980 a repo (Git) repository.</para></listitem>
1981 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
1982 the Internet using HTTP.</para></listitem>
1983 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
1984 from the Internet using HTTPS.</para></listitem>
1985 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
1986 from the Internet using FTP.</para></listitem>
1987 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
1988 a CVS revision control repository.</para></listitem>
1989 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
1990 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
1991 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
1992 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
1993 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
1994 a secure shell.</para></listitem>
1995 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
1996 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
1997 </itemizedlist>
1998 </para>
1999 <para>Here are some additional options worth mentioning:
2000 <itemizedlist>
2001 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
2002 whether or not to unpack the file if it is an archive.
2003 The default action is to unpack the file.</para></listitem>
2004 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
2005 (or extracts its contents) into the specified
2006 subdirectory.
2007 This option is useful for unusual tarballs or other archives that
2008 do not have their files already in a subdirectory within the archive.
2009 </para></listitem>
2010 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
2011 name to be used for association with <filename>SRC_URI</filename> checksums
2012 when you have more than one file specified in <filename>SRC_URI</filename>.
2013 </para></listitem>
2014 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
2015 the filename used when storing the downloaded file.</para></listitem>
2016 </itemizedlist>
2017 </para>
2018 </glossdef>
2019 </glossentry>
2020
2021 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
2022 <glossdef>
2023 <para>
2024 The date of the source code used to build the package.
2025 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2026 </para>
2027 </glossdef>
2028 </glossentry>
2029
2030 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
2031 <glossdef>
2032 <para>
2033 The revision of the source code used to build the package.
2034 This variable applies only when using Subversion, Git, Mercurial and Bazaar.
2035 If you want to build a fixed revision and you want
2036 to avoid performing a query on the remote repository every time
2037 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
2038 full revision identifier and not just a tag.
2039 </para>
2040 </glossdef>
2041 </glossentry>
2042
2043 <glossentry id='var-SRCREV_FORMAT'><glossterm>SRCREV_FORMAT</glossterm>
2044 <glossdef>
2045 <para>
2046 Helps construct valid
2047 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2048 values when multiple source controlled URLs are used in
2049 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
2050 </para>
2051
2052 <para>
2053 The system needs help constructing these values under these
2054 circumstances.
2055 Each component in the <filename>SRC_URI</filename>
2056 is assigned a name and these are referenced
2057 in the <filename>SRCREV_FORMAT</filename> variable.
2058 Consider an example with URLs named "machine" and "meta".
2059 In this case, <filename>SRCREV_FORMAT</filename> could look
2060 like "machine_meta" and those names would have the SCM
2061 versions substituted into each position.
2062 Only one <filename>AUTOINC</filename> placeholder is added
2063 and if needed.
2064 And, this placeholder is placed at the start of the
2065 returned string.
2066 </para>
2067 </glossdef>
2068 </glossentry>
2069
2070 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
2071 <glossdef>
2072 <para>
2073 Specifies the base path used to create recipe stamp files.
2074 The path to an actual stamp file is constructed by evaluating this
2075 string and then appending additional information.
2076 </para>
2077 </glossdef>
2078 </glossentry>
2079
2080 <glossentry id='var-STAMPCLEAN'><glossterm>STAMPCLEAN</glossterm>
2081 <glossdef>
2082 <para>
2083 Specifies the base path used to create recipe stamp files.
2084 Unlike the
2085 <link linkend='var-STAMP'><filename>STAMP</filename></link>
2086 variable, <filename>STAMPCLEAN</filename> can contain
2087 wildcards to match the range of files a clean operation
2088 should remove.
2089 BitBake uses a clean operation to remove any other stamps
2090 it should be removing when creating a new stamp.
2091 </para>
2092 </glossdef>
2093 </glossentry>
2094
2095 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
2096 <glossdef>
2097 <para>
2098 A short summary for the recipe, which is 72 characters or less.
2099 </para>
2100 </glossdef>
2101 </glossentry>
2102
2103 </glossdiv>
2104
2105 <glossdiv id='var-glossary-t'><title>T</title>
2106
2107 <glossentry id='var-T'><glossterm>T</glossterm>
2108 <glossdef>
2109 <para>Points to a directory were BitBake places
2110 temporary files, which consist mostly of task logs and
2111 scripts, when building a particular recipe.
2112 </para>
2113 </glossdef>
2114 </glossentry>
2115
2116 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
2117 <glossdef>
2118 <para>
2119 Points to the build directory.
2120 BitBake automatically sets this variable.
2121 </para>
2122 </glossdef>
2123 </glossentry>
2124
2125 </glossdiv>
2126
2127<!--
2128 <glossdiv id='var-glossary-u'><title>U</title>
2129 </glossdiv>
2130
2131 <glossdiv id='var-glossary-v'><title>V</title>
2132 </glossdiv>
2133
2134 <glossdiv id='var-glossary-w'><title>W</title>
2135 </glossdiv>
2136
2137 <glossdiv id='var-glossary-x'><title>X</title>
2138 </glossdiv>
2139
2140 <glossdiv id='var-glossary-y'><title>Y</title>
2141 </glossdiv>
2142
2143 <glossdiv id='var-glossary-z'><title>Z</title>
2144 </glossdiv>
2145-->
2146
2147
2148</glossary>
2149</chapter>
2150<!--
2151vim: expandtab tw=80 ts=4
2152-->
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css
new file mode 100644
index 0000000000..65da2a4e31
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css
@@ -0,0 +1,984 @@
1/*
2 Generic XHTML / DocBook XHTML CSS Stylesheet.
3
4 Browser wrangling and typographic design by
5 Oyvind Kolas / pippin@gimp.org
6
7 Customised for Poky by
8 Matthew Allum / mallum@o-hand.com
9
10 Thanks to:
11 Liam R. E. Quin
12 William Skaggs
13 Jakub Steiner
14
15 Structure
16 ---------
17
18 The stylesheet is divided into the following sections:
19
20 Positioning
21 Margins, paddings, width, font-size, clearing.
22 Decorations
23 Borders, style
24 Colors
25 Colors
26 Graphics
27 Graphical backgrounds
28 Nasty IE tweaks
29 Workarounds needed to make it work in internet explorer,
30 currently makes the stylesheet non validating, but up until
31 this point it is validating.
32 Mozilla extensions
33 Transparency for footer
34 Rounded corners on boxes
35
36*/
37
38
39 /*************** /
40 / Positioning /
41/ ***************/
42
43body {
44 font-family: Verdana, Sans, sans-serif;
45
46 min-width: 640px;
47 width: 80%;
48 margin: 0em auto;
49 padding: 2em 5em 5em 5em;
50 color: #333;
51}
52
53h1,h2,h3,h4,h5,h6,h7 {
54 font-family: Arial, Sans;
55 color: #00557D;
56 clear: both;
57}
58
59h1 {
60 font-size: 2em;
61 text-align: left;
62 padding: 0em 0em 0em 0em;
63 margin: 2em 0em 0em 0em;
64}
65
66h2.subtitle {
67 margin: 0.10em 0em 3.0em 0em;
68 padding: 0em 0em 0em 0em;
69 font-size: 1.8em;
70 padding-left: 20%;
71 font-weight: normal;
72 font-style: italic;
73}
74
75h2 {
76 margin: 2em 0em 0.66em 0em;
77 padding: 0.5em 0em 0em 0em;
78 font-size: 1.5em;
79 font-weight: bold;
80}
81
82h3.subtitle {
83 margin: 0em 0em 1em 0em;
84 padding: 0em 0em 0em 0em;
85 font-size: 142.14%;
86 text-align: right;
87}
88
89h3 {
90 margin: 1em 0em 0.5em 0em;
91 padding: 1em 0em 0em 0em;
92 font-size: 140%;
93 font-weight: bold;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: bold;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110%;
107 font-weight: bold;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 110%;
114 font-weight: bold;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256px;
121 background-image: url("figures/bitbake-title.png");
122 background-position: left top;
123 margin-top: -256px;
124 padding-right: 50px;
125 margin-left: 0px;
126 text-align: right;
127 width: 740px;
128}
129
130h3.author {
131 margin: 0em 0me 0em 0em;
132 padding: 0em 0em 0em 0em;
133 font-weight: normal;
134 font-size: 100%;
135 color: #333;
136 clear: both;
137}
138
139.author tt.email {
140 font-size: 66%;
141}
142
143.titlepage hr {
144 width: 0em;
145 clear: both;
146}
147
148.revhistory {
149 padding-top: 2em;
150 clear: both;
151}
152
153.toc,
154.list-of-tables,
155.list-of-examples,
156.list-of-figures {
157 padding: 1.33em 0em 2.5em 0em;
158 color: #00557D;
159}
160
161.toc p,
162.list-of-tables p,
163.list-of-figures p,
164.list-of-examples p {
165 padding: 0em 0em 0em 0em;
166 padding: 0em 0em 0.3em;
167 margin: 1.5em 0em 0em 0em;
168}
169
170.toc p b,
171.list-of-tables p b,
172.list-of-figures p b,
173.list-of-examples p b{
174 font-size: 100.0%;
175 font-weight: bold;
176}
177
178.toc dl,
179.list-of-tables dl,
180.list-of-figures dl,
181.list-of-examples dl {
182 margin: 0em 0em 0.5em 0em;
183 padding: 0em 0em 0em 0em;
184}
185
186.toc dt {
187 margin: 0em 0em 0em 0em;
188 padding: 0em 0em 0em 0em;
189}
190
191.toc dd {
192 margin: 0em 0em 0em 2.6em;
193 padding: 0em 0em 0em 0em;
194}
195
196div.glossary dl,
197div.variablelist dl {
198}
199
200.glossary dl dt,
201.variablelist dl dt,
202.variablelist dl dt span.term {
203 font-weight: normal;
204 width: 20em;
205 text-align: right;
206}
207
208.variablelist dl dt {
209 margin-top: 0.5em;
210}
211
212.glossary dl dd,
213.variablelist dl dd {
214 margin-top: -1em;
215 margin-left: 25.5em;
216}
217
218.glossary dd p,
219.variablelist dd p {
220 margin-top: 0em;
221 margin-bottom: 1em;
222}
223
224
225div.calloutlist table td {
226 padding: 0em 0em 0em 0em;
227 margin: 0em 0em 0em 0em;
228}
229
230div.calloutlist table td p {
231 margin-top: 0em;
232 margin-bottom: 1em;
233}
234
235div p.copyright {
236 text-align: left;
237}
238
239div.legalnotice p.legalnotice-title {
240 margin-bottom: 0em;
241}
242
243p {
244 line-height: 1.5em;
245 margin-top: 0em;
246
247}
248
249dl {
250 padding-top: 0em;
251}
252
253hr {
254 border: solid 1px;
255}
256
257
258.mediaobject,
259.mediaobjectco {
260 text-align: center;
261}
262
263img {
264 border: none;
265}
266
267ul {
268 padding: 0em 0em 0em 1.5em;
269}
270
271ul li {
272 padding: 0em 0em 0em 0em;
273}
274
275ul li p {
276 text-align: left;
277}
278
279table {
280 width :100%;
281}
282
283th {
284 padding: 0.25em;
285 text-align: left;
286 font-weight: normal;
287 vertical-align: top;
288}
289
290td {
291 padding: 0.25em;
292 vertical-align: top;
293}
294
295p a[id] {
296 margin: 0px;
297 padding: 0px;
298 display: inline;
299 background-image: none;
300}
301
302a {
303 text-decoration: underline;
304 color: #444;
305}
306
307pre {
308 overflow: auto;
309}
310
311a:hover {
312 text-decoration: underline;
313 /*font-weight: bold;*/
314}
315
316/* This style defines how the permalink character
317 appears by itself and when hovered over with
318 the mouse. */
319
320[alt='Permalink'] { color: #eee; }
321[alt='Permalink']:hover { color: black; }
322
323
324div.informalfigure,
325div.informalexample,
326div.informaltable,
327div.figure,
328div.table,
329div.example {
330 margin: 1em 0em;
331 padding: 1em;
332 page-break-inside: avoid;
333}
334
335
336div.informalfigure p.title b,
337div.informalexample p.title b,
338div.informaltable p.title b,
339div.figure p.title b,
340div.example p.title b,
341div.table p.title b{
342 padding-top: 0em;
343 margin-top: 0em;
344 font-size: 100%;
345 font-weight: normal;
346}
347
348.mediaobject .caption,
349.mediaobject .caption p {
350 text-align: center;
351 font-size: 80%;
352 padding-top: 0.5em;
353 padding-bottom: 0.5em;
354}
355
356.epigraph {
357 padding-left: 55%;
358 margin-bottom: 1em;
359}
360
361.epigraph p {
362 text-align: left;
363}
364
365.epigraph .quote {
366 font-style: italic;
367}
368.epigraph .attribution {
369 font-style: normal;
370 text-align: right;
371}
372
373span.application {
374 font-style: italic;
375}
376
377.programlisting {
378 font-family: monospace;
379 font-size: 80%;
380 white-space: pre;
381 margin: 1.33em 0em;
382 padding: 1.33em;
383}
384
385.tip,
386.warning,
387.caution,
388.note {
389 margin-top: 1em;
390 margin-bottom: 1em;
391
392}
393
394/* force full width of table within div */
395.tip table,
396.warning table,
397.caution table,
398.note table {
399 border: none;
400 width: 100%;
401}
402
403
404.tip table th,
405.warning table th,
406.caution table th,
407.note table th {
408 padding: 0.8em 0.0em 0.0em 0.0em;
409 margin : 0em 0em 0em 0em;
410}
411
412.tip p,
413.warning p,
414.caution p,
415.note p {
416 margin-top: 0.5em;
417 margin-bottom: 0.5em;
418 padding-right: 1em;
419 text-align: left;
420}
421
422.acronym {
423 text-transform: uppercase;
424}
425
426b.keycap,
427.keycap {
428 padding: 0.09em 0.3em;
429 margin: 0em;
430}
431
432.itemizedlist li {
433 clear: none;
434}
435
436.filename {
437 font-size: medium;
438 font-family: Courier, monospace;
439}
440
441
442div.navheader, div.heading{
443 position: absolute;
444 left: 0em;
445 top: 0em;
446 width: 100%;
447 background-color: #cdf;
448 width: 100%;
449}
450
451div.navfooter, div.footing{
452 position: fixed;
453 left: 0em;
454 bottom: 0em;
455 background-color: #eee;
456 width: 100%;
457}
458
459
460div.navheader td,
461div.navfooter td {
462 font-size: 66%;
463}
464
465div.navheader table th {
466 /*font-family: Georgia, Times, serif;*/
467 /*font-size: x-large;*/
468 font-size: 80%;
469}
470
471div.navheader table {
472 border-left: 0em;
473 border-right: 0em;
474 border-top: 0em;
475 width: 100%;
476}
477
478div.navfooter table {
479 border-left: 0em;
480 border-right: 0em;
481 border-bottom: 0em;
482 width: 100%;
483}
484
485div.navheader table td a,
486div.navfooter table td a {
487 color: #777;
488 text-decoration: none;
489}
490
491/* normal text in the footer */
492div.navfooter table td {
493 color: black;
494}
495
496div.navheader table td a:visited,
497div.navfooter table td a:visited {
498 color: #444;
499}
500
501
502/* links in header and footer */
503div.navheader table td a:hover,
504div.navfooter table td a:hover {
505 text-decoration: underline;
506 background-color: transparent;
507 color: #33a;
508}
509
510div.navheader hr,
511div.navfooter hr {
512 display: none;
513}
514
515
516.qandaset tr.question td p {
517 margin: 0em 0em 1em 0em;
518 padding: 0em 0em 0em 0em;
519}
520
521.qandaset tr.answer td p {
522 margin: 0em 0em 1em 0em;
523 padding: 0em 0em 0em 0em;
524}
525.answer td {
526 padding-bottom: 1.5em;
527}
528
529.emphasis {
530 font-weight: bold;
531}
532
533
534 /************* /
535 / decorations /
536/ *************/
537
538.titlepage {
539}
540
541.part .title {
542}
543
544.subtitle {
545 border: none;
546}
547
548/*
549h1 {
550 border: none;
551}
552
553h2 {
554 border-top: solid 0.2em;
555 border-bottom: solid 0.06em;
556}
557
558h3 {
559 border-top: 0em;
560 border-bottom: solid 0.06em;
561}
562
563h4 {
564 border: 0em;
565 border-bottom: solid 0.06em;
566}
567
568h5 {
569 border: 0em;
570}
571*/
572
573.programlisting {
574 border: solid 1px;
575}
576
577div.figure,
578div.table,
579div.informalfigure,
580div.informaltable,
581div.informalexample,
582div.example {
583 border: 1px solid;
584}
585
586
587
588.tip,
589.warning,
590.caution,
591.note {
592 border: 1px solid;
593}
594
595.tip table th,
596.warning table th,
597.caution table th,
598.note table th {
599 border-bottom: 1px solid;
600}
601
602.question td {
603 border-top: 1px solid black;
604}
605
606.answer {
607}
608
609
610b.keycap,
611.keycap {
612 border: 1px solid;
613}
614
615
616div.navheader, div.heading{
617 border-bottom: 1px solid;
618}
619
620
621div.navfooter, div.footing{
622 border-top: 1px solid;
623}
624
625 /********* /
626 / colors /
627/ *********/
628
629body {
630 color: #333;
631 background: white;
632}
633
634a {
635 background: transparent;
636}
637
638a:hover {
639 background-color: #dedede;
640}
641
642
643h1,
644h2,
645h3,
646h4,
647h5,
648h6,
649h7,
650h8 {
651 background-color: transparent;
652}
653
654hr {
655 border-color: #aaa;
656}
657
658
659.tip, .warning, .caution, .note {
660 border-color: #fff;
661}
662
663
664.tip table th,
665.warning table th,
666.caution table th,
667.note table th {
668 border-bottom-color: #fff;
669}
670
671
672.warning {
673 background-color: #f0f0f2;
674}
675
676.caution {
677 background-color: #f0f0f2;
678}
679
680.tip {
681 background-color: #f0f0f2;
682}
683
684.note {
685 background-color: #f0f0f2;
686}
687
688.glossary dl dt,
689.variablelist dl dt,
690.variablelist dl dt span.term {
691 color: #044;
692}
693
694div.figure,
695div.table,
696div.example,
697div.informalfigure,
698div.informaltable,
699div.informalexample {
700 border-color: #aaa;
701}
702
703pre.programlisting {
704 color: black;
705 background-color: #fff;
706 border-color: #aaa;
707 border-width: 2px;
708}
709
710.guimenu,
711.guilabel,
712.guimenuitem {
713 background-color: #eee;
714}
715
716
717b.keycap,
718.keycap {
719 background-color: #eee;
720 border-color: #999;
721}
722
723
724div.navheader {
725 border-color: black;
726}
727
728
729div.navfooter {
730 border-color: black;
731}
732
733
734 /*********** /
735 / graphics /
736/ ***********/
737
738/*
739body {
740 background-image: url("images/body_bg.jpg");
741 background-attachment: fixed;
742}
743
744.navheader,
745.note,
746.tip {
747 background-image: url("images/note_bg.jpg");
748 background-attachment: fixed;
749}
750
751.warning,
752.caution {
753 background-image: url("images/warning_bg.jpg");
754 background-attachment: fixed;
755}
756
757.figure,
758.informalfigure,
759.example,
760.informalexample,
761.table,
762.informaltable {
763 background-image: url("images/figure_bg.jpg");
764 background-attachment: fixed;
765}
766
767*/
768h1,
769h2,
770h3,
771h4,
772h5,
773h6,
774h7{
775}
776
777/*
778Example of how to stick an image as part of the title.
779
780div.article .titlepage .title
781{
782 background-image: url("figures/white-on-black.png");
783 background-position: center;
784 background-repeat: repeat-x;
785}
786*/
787
788div.preface .titlepage .title,
789div.colophon .title,
790div.chapter .titlepage .title,
791div.article .titlepage .title
792{
793}
794
795div.section div.section .titlepage .title,
796div.sect2 .titlepage .title {
797 background: none;
798}
799
800
801h1.title {
802 background-color: transparent;
803 background-repeat: no-repeat;
804 height: 256px;
805 text-indent: -9000px;
806 overflow:hidden;
807}
808
809h2.subtitle {
810 background-color: transparent;
811 text-indent: -9000px;
812 overflow:hidden;
813 width: 0px;
814 display: none;
815}
816
817 /*************************************** /
818 / pippin.gimp.org specific alterations /
819/ ***************************************/
820
821/*
822div.heading, div.navheader {
823 color: #777;
824 font-size: 80%;
825 padding: 0;
826 margin: 0;
827 text-align: left;
828 position: absolute;
829 top: 0px;
830 left: 0px;
831 width: 100%;
832 height: 50px;
833 background: url('/gfx/heading_bg.png') transparent;
834 background-repeat: repeat-x;
835 background-attachment: fixed;
836 border: none;
837}
838
839div.heading a {
840 color: #444;
841}
842
843div.footing, div.navfooter {
844 border: none;
845 color: #ddd;
846 font-size: 80%;
847 text-align:right;
848
849 width: 100%;
850 padding-top: 10px;
851 position: absolute;
852 bottom: 0px;
853 left: 0px;
854
855 background: url('/gfx/footing_bg.png') transparent;
856}
857*/
858
859
860
861 /****************** /
862 / nasty ie tweaks /
863/ ******************/
864
865/*
866div.heading, div.navheader {
867 width:expression(document.body.clientWidth + "px");
868}
869
870div.footing, div.navfooter {
871 width:expression(document.body.clientWidth + "px");
872 margin-left:expression("-5em");
873}
874body {
875 padding:expression("4em 5em 0em 5em");
876}
877*/
878
879 /**************************************** /
880 / mozilla vendor specific css extensions /
881/ ****************************************/
882/*
883div.navfooter, div.footing{
884 -moz-opacity: 0.8em;
885}
886
887div.figure,
888div.table,
889div.informalfigure,
890div.informaltable,
891div.informalexample,
892div.example,
893.tip,
894.warning,
895.caution,
896.note {
897 -moz-border-radius: 0.5em;
898}
899
900b.keycap,
901.keycap {
902 -moz-border-radius: 0.3em;
903}
904*/
905
906table tr td table tr td {
907 display: none;
908}
909
910
911hr {
912 display: none;
913}
914
915table {
916 border: 0em;
917}
918
919 .photo {
920 float: right;
921 margin-left: 1.5em;
922 margin-bottom: 1.5em;
923 margin-top: 0em;
924 max-width: 17em;
925 border: 1px solid gray;
926 padding: 3px;
927 background: white;
928}
929 .seperator {
930 padding-top: 2em;
931 clear: both;
932 }
933
934 #validators {
935 margin-top: 5em;
936 text-align: right;
937 color: #777;
938 }
939 @media print {
940 body {
941 font-size: 8pt;
942 }
943 .noprint {
944 display: none;
945 }
946 }
947
948
949.tip,
950.note {
951 background: #f0f0f2;
952 color: #333;
953 padding: 20px;
954 margin: 20px;
955}
956
957.tip h3,
958.note h3 {
959 padding: 0em;
960 margin: 0em;
961 font-size: 2em;
962 font-weight: bold;
963 color: #333;
964}
965
966.tip a,
967.note a {
968 color: #333;
969 text-decoration: underline;
970}
971
972.footnote {
973 font-size: small;
974 color: #333;
975}
976
977/* Changes the announcement text */
978.tip h3,
979.warning h3,
980.caution h3,
981.note h3 {
982 font-size:large;
983 color: #00557D;
984}
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml
new file mode 100644
index 0000000000..7fff933be8
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml
@@ -0,0 +1,88 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<book id='bitbake-user-manual' lang='en'
5 xmlns:xi="http://www.w3.org/2003/XInclude"
6 xmlns="http://docbook.org/ns/docbook"
7 >
8 <bookinfo>
9
10 <mediaobject>
11 <imageobject>
12 <imagedata fileref='figures/bitbake-title.png'
13 format='SVG'
14 align='left' scalefit='1' width='100%'/>
15 </imageobject>
16 </mediaobject>
17
18 <title>
19 BitBake User Manual
20 </title>
21
22 <authorgroup>
23 <author>
24 <firstname>Richard Purdie, Chris Larson, and </firstname> <surname>Phil Blundell</surname>
25 <affiliation>
26 <orgname>BitBake Community</orgname>
27 </affiliation>
28 <email>bitbake-devel@lists.openembedded.org</email>
29 </author>
30 </authorgroup>
31
32<!--
33# Add in some revision history if we want it here.
34 <revhistory>
35 <revision>
36 <revnumber>x.x</revnumber>
37 <date>dd month year</date>
38 <revremark>Some relevent comment</revremark>
39 </revision>
40 <revision>
41 <revnumber>x.x</revnumber>
42 <date>dd month year</date>
43 <revremark>Some relevent comment</revremark>
44 </revision>
45 <revision>
46 <revnumber>x.x</revnumber>
47 <date>dd month year</date>
48 <revremark>Some relevent comment</revremark>
49 </revision>
50 <revision>
51 <revnumber>x.x</revnumber>
52 <date>dd month year</date>
53 <revremark>Some relevent comment</revremark>
54 </revision>
55 </revhistory>
56-->
57
58 <copyright>
59 <year>2004-2015</year>
60 <holder>Richard Purdie</holder>
61 <holder>Chris Larson</holder>
62 <holder>and Phil Blundell</holder>
63 </copyright>
64
65 <legalnotice>
66 <para>
67 This work is licensed under the Creative Commons Attribution License.
68 To view a copy of this license, visit
69 <ulink url="http://creativecommons.org/licenses/by/2.5/">http://creativecommons.org/licenses/by/2.5/</ulink>
70 or send a letter to Creative Commons, 444 Castro Street,
71 Suite 900, Mountain View, California 94041, USA.
72 </para>
73 </legalnotice>
74 </bookinfo>
75
76 <xi:include href="bitbake-user-manual-intro.xml"/>
77
78 <xi:include href="bitbake-user-manual-execution.xml"/>
79
80 <xi:include href="bitbake-user-manual-metadata.xml"/>
81
82 <xi:include href="bitbake-user-manual-fetching.xml"/>
83
84 <xi:include href="bitbake-user-manual-ref-variables.xml"/>
85
86 <xi:include href="bitbake-user-manual-hello.xml"/>
87
88</book>
diff --git a/bitbake/doc/bitbake-user-manual/figures/bitbake-title.png b/bitbake/doc/bitbake-user-manual/figures/bitbake-title.png
new file mode 100644
index 0000000000..cb290154da
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/figures/bitbake-title.png
Binary files differ
diff --git a/bitbake/doc/bitbake-user-manual/html.css b/bitbake/doc/bitbake-user-manual/html.css
new file mode 100644
index 0000000000..6eedfd3189
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/html.css
@@ -0,0 +1,281 @@
1/* Feuille de style DocBook du projet Traduc.org */
2/* DocBook CSS stylesheet of the Traduc.org project */
3
4/* (c) Jean-Philippe Guérard - 14 août 2004 */
5/* (c) Jean-Philippe Guérard - 14 August 2004 */
6
7/* Cette feuille de style est libre, vous pouvez la */
8/* redistribuer et la modifier selon les termes de la Licence */
9/* Art Libre. Vous trouverez un exemplaire de cette Licence sur */
10/* http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
11
12/* This work of art is free, you can redistribute it and/or */
13/* modify it according to terms of the Free Art license. You */
14/* will find a specimen of this license on the Copyleft */
15/* Attitude web site: http://artlibre.org as well as on other */
16/* sites. */
17/* Please note that the French version of this licence as shown */
18/* on http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
19/* is only official licence of this document. The English */
20/* is only provided to help you understand this licence. */
21
22/* La dernière version de cette feuille de style est toujours */
23/* disponible sur : http://tigreraye.org/style.css */
24/* Elle est également disponible sur : */
25/* http://www.traduc.org/docs/HOWTO/lecture/style.css */
26
27/* The latest version of this stylesheet is available from: */
28/* http://tigreraye.org/style.css */
29/* It is also available on: */
30/* http://www.traduc.org/docs/HOWTO/lecture/style.css */
31
32/* N'hésitez pas à envoyer vos commentaires et corrections à */
33/* Jean-Philippe Guérard <jean-philippe.guerard@tigreraye.org> */
34
35/* Please send feedback and bug reports to */
36/* Jean-Philippe Guérard <jean-philippe.guerard@tigreraye.org> */
37
38/* $Id: style.css,v 1.14 2004/09/10 20:12:09 fevrier Exp fevrier $ */
39
40/* Présentation générale du document */
41/* Overall document presentation */
42
43body {
44 /*
45 font-family: Apolline, "URW Palladio L", Garamond, jGaramond,
46 "Bitstream Cyberbit", "Palatino Linotype", serif;
47 */
48 margin: 7%;
49 background-color: white;
50}
51
52/* Taille du texte */
53/* Text size */
54
55* { font-size: 100%; }
56
57/* Gestion des textes mis en relief imbriqués */
58/* Embedded emphasis */
59
60em { font-style: italic; }
61em em { font-style: normal; }
62em em em { font-style: italic; }
63
64/* Titres */
65/* Titles */
66
67h1 { font-size: 200%; font-weight: 900; }
68h2 { font-size: 160%; font-weight: 900; }
69h3 { font-size: 130%; font-weight: bold; }
70h4 { font-size: 115%; font-weight: bold; }
71h5 { font-size: 108%; font-weight: bold; }
72h6 { font-weight: bold; }
73
74/* Nom de famille en petites majuscules (uniquement en français) */
75/* Last names in small caps (for French only) */
76
77*[class~="surname"]:lang(fr) { font-variant: small-caps; }
78
79/* Blocs de citation */
80/* Quotation blocs */
81
82div[class~="blockquote"] {
83 border: solid 2px #AAA;
84 padding: 5px;
85 margin: 5px;
86}
87
88div[class~="blockquote"] > table {
89 border: none;
90}
91
92/* Blocs litéraux : fond gris clair */
93/* Literal blocs: light gray background */
94
95*[class~="literallayout"] {
96 background: #f0f0f0;
97 padding: 5px;
98 margin: 5px;
99}
100
101/* Programmes et captures texte : fond bleu clair */
102/* Listing and text screen snapshots: light blue background */
103
104*[class~="programlisting"], *[class~="screen"] {
105 background: #f0f0ff;
106 padding: 5px;
107 margin: 5px;
108}
109
110/* Les textes à remplacer sont surlignés en vert pâle */
111/* Replaceable text in highlighted in pale green */
112
113*[class~="replaceable"] {
114 background-color: #98fb98;
115 font-style: normal; }
116
117/* Tables : fonds gris clair & bords simples */
118/* Tables: light gray background and solid borders */
119
120*[class~="table"] *[class~="title"] { width:100%; border: 0px; }
121
122table {
123 border: 1px solid #aaa;
124 border-collapse: collapse;
125 padding: 2px;
126 margin: 5px;
127}
128
129/* Listes simples en style table */
130/* Simples lists in table presentation */
131
132table[class~="simplelist"] {
133 background-color: #F0F0F0;
134 margin: 5px;
135 border: solid 1px #AAA;
136}
137
138table[class~="simplelist"] td {
139 border: solid 1px #AAA;
140}
141
142/* Les tables */
143/* Tables */
144
145*[class~="table"] table {
146 background-color: #F0F0F0;
147 border: solid 1px #AAA;
148}
149*[class~="informaltable"] table { background-color: #F0F0F0; }
150
151th,td {
152 vertical-align: baseline;
153 text-align: left;
154 padding: 0.1em 0.3em;
155 empty-cells: show;
156}
157
158/* Alignement des colonnes */
159/* Colunms alignment */
160
161td[align=center] , th[align=center] { text-align: center; }
162td[align=right] , th[align=right] { text-align: right; }
163td[align=left] , th[align=left] { text-align: left; }
164td[align=justify] , th[align=justify] { text-align: justify; }
165
166/* Pas de marge autour des images */
167/* No inside margins for images */
168
169img { border: 0; }
170
171/* Les liens ne sont pas soulignés */
172/* No underlines for links */
173
174:link , :visited , :active { text-decoration: none; }
175
176/* Prudence : cadre jaune et fond jaune clair */
177/* Caution: yellow border and light yellow background */
178
179*[class~="caution"] {
180 border: solid 2px yellow;
181 background-color: #ffffe0;
182 padding: 1em 6px 1em ;
183 margin: 5px;
184}
185
186*[class~="caution"] th {
187 vertical-align: middle
188}
189
190*[class~="caution"] table {
191 background-color: #ffffe0;
192 border: none;
193}
194
195/* Note importante : cadre jaune et fond jaune clair */
196/* Important: yellow border and light yellow background */
197
198*[class~="important"] {
199 border: solid 2px yellow;
200 background-color: #ffffe0;
201 padding: 1em 6px 1em;
202 margin: 5px;
203}
204
205*[class~="important"] th {
206 vertical-align: middle
207}
208
209*[class~="important"] table {
210 background-color: #ffffe0;
211 border: none;
212}
213
214/* Mise en évidence : texte légèrement plus grand */
215/* Highlights: slightly larger texts */
216
217*[class~="highlights"] {
218 font-size: 110%;
219}
220
221/* Note : cadre bleu et fond bleu clair */
222/* Notes: blue border and light blue background */
223
224*[class~="note"] {
225 border: solid 2px #7099C5;
226 background-color: #f0f0ff;
227 padding: 1em 6px 1em ;
228 margin: 5px;
229}
230
231*[class~="note"] th {
232 vertical-align: middle
233}
234
235*[class~="note"] table {
236 background-color: #f0f0ff;
237 border: none;
238}
239
240/* Astuce : cadre vert et fond vert clair */
241/* Tip: green border and light green background */
242
243*[class~="tip"] {
244 border: solid 2px #00ff00;
245 background-color: #f0ffff;
246 padding: 1em 6px 1em ;
247 margin: 5px;
248}
249
250*[class~="tip"] th {
251 vertical-align: middle;
252}
253
254*[class~="tip"] table {
255 background-color: #f0ffff;
256 border: none;
257}
258
259/* Avertissement : cadre rouge et fond rouge clair */
260/* Warning: red border and light red background */
261
262*[class~="warning"] {
263 border: solid 2px #ff0000;
264 background-color: #fff0f0;
265 padding: 1em 6px 1em ;
266 margin: 5px;
267}
268
269*[class~="warning"] th {
270 vertical-align: middle;
271}
272
273
274*[class~="warning"] table {
275 background-color: #fff0f0;
276 border: none;
277}
278
279/* Fin */
280/* The End */
281
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-25 02:14:04 +0000