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