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.xml506
-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.xml1712
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml2132
-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, 7828 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..4ce7ed9f8c
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
@@ -0,0 +1,506 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='hello-world-example'>
5 <title>Hello World Example</title>
6
7 <section id='bitbake-hello-world'>
8 <title>BitBake Hello World</title>
9
10 <para>
11 The simplest example commonly used to demonstrate any new
12 programming language or tool is the
13 "<ulink url="http://en.wikipedia.org/wiki/Hello_world_program">Hello World</ulink>"
14 example.
15 This appendix demonstrates, in tutorial form, Hello
16 World within the context of BitBake.
17 The tutorial describes how to create a new project
18 and the applicable metadata files necessary to allow
19 BitBake to build it.
20 </para>
21 </section>
22
23 <section id='example-obtaining-bitbake'>
24 <title>Obtaining BitBake</title>
25
26 <para>
27 See the
28 "<link linkend='obtaining-bitbake'>Obtaining BitBake</link>"
29 section for information on how to obtain BitBake.
30 Once you have the source code on your machine, the BitBake directory
31 appears as follows:
32 <literallayout class='monospaced'>
33 $ ls -al
34 total 100
35 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 .
36 drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 ..
37 -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
38 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin
39 drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build
40 -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
41 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes
42 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf
43 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib
44 -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
45 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc
46 -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore
47 -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
48 drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib
49 -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in
50 -rwxrwxr-x. 1 wmat wmat 3195 Jan 31 11:57 setup.py
51 -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO
52 </literallayout>
53 </para>
54
55 <para>
56 At this point, you should have BitBake cloned to
57 a directory that matches the previous listing except for
58 dates and user names.
59 </para>
60 </section>
61
62 <section id='setting-up-the-bitbake-environment'>
63 <title>Setting Up the BitBake Environment</title>
64
65 <para>
66 First, you need to be sure that you can run BitBake.
67 Set your working directory to where your local BitBake
68 files are and run the following command:
69 <literallayout class='monospaced'>
70 $ ./bin/bitbake --version
71 BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
72 </literallayout>
73 The console output tells you what version you are running.
74 </para>
75
76 <para>
77 The recommended method to run BitBake is from a directory of your
78 choice.
79 To be able to run BitBake from any directory, you need to add the
80 executable binary to your binary to your shell's environment
81 <filename>PATH</filename> variable.
82 First, look at your current <filename>PATH</filename> variable
83 by entering the following:
84 <literallayout class='monospaced'>
85 $ echo $PATH
86 </literallayout>
87 Next, add the directory location for the BitBake binary to the
88 <filename>PATH</filename>.
89 Here is an example that adds the
90 <filename>/home/scott-lenovo/bitbake/bin</filename> directory
91 to the front of the <filename>PATH</filename> variable:
92 <literallayout class='monospaced'>
93 $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
94 </literallayout>
95 You should now be able to enter the <filename>bitbake</filename>
96 command from the command line while working from any directory.
97 </para>
98 </section>
99
100 <section id='the-hello-world-example'>
101 <title>The Hello World Example</title>
102
103 <para>
104 The overall goal of this exercise is to build a
105 complete "Hello World" example utilizing task and layer
106 concepts.
107 Because this is how modern projects such as OpenEmbedded and
108 the Yocto Project utilize BitBake, the example
109 provides an excellent starting point for understanding
110 BitBake.
111 </para>
112
113 <para>
114 To help you understand how to use BitBake to build targets,
115 the example starts with nothing but the <filename>bitbake</filename>
116 command, which causes BitBake to fail and report problems.
117 The example progresses by adding pieces to the build to
118 eventually conclude with a working, minimal "Hello World"
119 example.
120 </para>
121
122 <para>
123 While every attempt is made to explain what is happening during
124 the example, the descriptions cannot cover everything.
125 You can find further information throughout this manual.
126 Also, you can actively participate in the
127 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'></ulink>
128 discussion mailing list about the BitBake build tool.
129 </para>
130
131 <note>
132 This example was inspired by and drew heavily from these sources:
133 <itemizedlist>
134 <listitem><para>
135 <ulink url="http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html">Mailing List post - The BitBake equivalent of "Hello, World!"</ulink>
136 </para></listitem>
137 <listitem><para>
138 <ulink url="http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/">Hambedded Linux blog post - From Bitbake Hello World to an Image</ulink>
139 </para></listitem>
140 </itemizedlist>
141 </note>
142
143 <para>
144 As stated earlier, the goal of this example
145 is to eventually compile "Hello World".
146 However, it is unknown what BitBake needs and what you have
147 to provide in order to achieve that goal.
148 Recall that BitBake utilizes three types of metadata files:
149 <link linkend='configuration-files'>Configuration Files</link>,
150 <link linkend='classes'>Classes</link>, and
151 <link linkend='recipes'>Recipes</link>.
152 But where do they go?
153 How does BitBake find them?
154 BitBake's error messaging helps you answer these types of questions
155 and helps you better understand exactly what is going on.
156 </para>
157
158 <para>
159 Following is the complete "Hello World" example.
160 </para>
161
162 <orderedlist>
163 <listitem><para><emphasis>Create a Project Directory:</emphasis>
164 First, set up a directory for the "Hello World" project.
165 Here is how you can do so in your home directory:
166 <literallayout class='monospaced'>
167 $ mkdir ~/hello
168 $ cd ~/hello
169 </literallayout>
170 This is the directory that BitBake will use to do all of
171 its work.
172 You can use this directory to keep all the metafiles needed
173 by BitBake.
174 Having a project directory is a good way to isolate your
175 project.
176 </para></listitem>
177 <listitem><para><emphasis>Run Bitbake:</emphasis>
178 At this point, you have nothing but a project directory.
179 Run the <filename>bitbake</filename> command and see what
180 it does:
181 <literallayout class='monospaced'>
182 $ bitbake
183 The BBPATH variable is not set and bitbake did not
184 find a conf/bblayers.conf file in the expected location.
185 Maybe you accidentally invoked bitbake from the wrong directory?
186 DEBUG: Removed the following variables from the environment:
187 GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
188 GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
189 XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
190 MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
191 GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
192 XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
193 _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
194 UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
195 </literallayout>
196 The majority of this output is specific to environment variables
197 that are not directly relevant to BitBake.
198 However, the very first message regarding the
199 <filename>BBPATH</filename> variable and the
200 <filename>conf/bblayers.conf</filename> file
201 is relevant.</para>
202 <para>
203 When you run BitBake, it begins looking for metadata files.
204 The
205 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
206 variable is what tells BitBake where to look for those files.
207 <filename>BBPATH</filename> is not set and you need to set it.
208 Without <filename>BBPATH</filename>, Bitbake cannot
209 find any configuration files (<filename>.conf</filename>)
210 or recipe files (<filename>.bb</filename>) at all.
211 BitBake also cannot find the <filename>bitbake.conf</filename>
212 file.
213 </para></listitem>
214 <listitem><para><emphasis>Setting <filename>BBPATH</filename>:</emphasis>
215 For this example, you can set <filename>BBPATH</filename>
216 in the same manner that you set <filename>PATH</filename>
217 earlier in the appendix.
218 You should realize, though, that it is much more flexible to set the
219 <filename>BBPATH</filename> variable up in a configuration
220 file for each project.</para>
221 <para>From your shell, enter the following commands to set and
222 export the <filename>BBPATH</filename> variable:
223 <literallayout class='monospaced'>
224 $ BBPATH="&lt;projectdirectory&gt;"
225 $ export BBPATH
226 </literallayout>
227 Use your actual project directory in the command.
228 BitBake uses that directory to find the metadata it needs for
229 your project.
230 <note>
231 When specifying your project directory, do not use the
232 tilde ("~") character as BitBake does not expand that character
233 as the shell would.
234 </note>
235 </para></listitem>
236 <listitem><para><emphasis>Run Bitbake:</emphasis>
237 Now that you have <filename>BBPATH</filename> defined, run
238 the <filename>bitbake</filename> command again:
239 <literallayout class='monospaced'>
240 $ bitbake
241 ERROR: Traceback (most recent call last):
242 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
243 return func(fn, *args)
244 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
245 return bb.parse.handle(fn, data, include)
246 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
247 return h['handle'](fn, data, include)
248 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
249 abs_fn = resolve_file(fn, data)
250 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
251 raise IOError("file %s not found in %s" % (fn, bbpath))
252 IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
253
254 ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
255 </literallayout>
256 This sample output shows that BitBake could not find the
257 <filename>conf/bitbake.conf</filename> file in the project
258 directory.
259 This file is the first thing BitBake must find in order
260 to build a target.
261 And, since the project directory for this example is
262 empty, you need to provide a <filename>conf/bitbake.conf</filename>
263 file.
264 </para></listitem>
265 <listitem><para><emphasis>Creating <filename>conf/bitbake.conf</filename>:</emphasis>
266 The <filename>conf/bitbake.conf</filename> includes a number of
267 configuration variables BitBake uses for metadata and recipe
268 files.
269 For this example, you need to create the file in your project directory
270 and define some key BitBake variables.
271 For more information on the <filename>bitbake.conf</filename>,
272 see
273 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#an-overview-of-bitbakeconf'></ulink>
274 </para>
275 <para>Use the following commands to create the <filename>conf</filename>
276 directory in the project directory:
277 <literallayout class='monospaced'>
278 $ mkdir conf
279 </literallayout>
280 From within the <filename>conf</filename> directory, use
281 some editor to create the <filename>bitbake.conf</filename>
282 so that it contains the following:
283 <literallayout class='monospaced'>
284 TMPDIR = "${<link linkend='var-TOPDIR'>TOPDIR</link>}/tmp"
285 <link linkend='var-CACHE'>CACHE</link> = "${TMPDIR}/cache"
286 <link linkend='var-STAMP'>STAMP</link> = "${TMPDIR}/stamps"
287 <link linkend='var-T'>T</link> = "${TMPDIR}/work"
288 <link linkend='var-B'>B</link> = "${TMPDIR}"
289 </literallayout>
290 The <filename>TMPDIR</filename> variable establishes a directory
291 that BitBake uses for build output and intermediate files (other
292 than the cached information used by the
293 <link linkend='setscene'>Setscene</link> process.
294 Here, the <filename>TMPDIR</filename> directory is set to
295 <filename>hello/tmp</filename>.
296 <note><title>Tip</title>
297 You can always safely delete the <filename>tmp</filename>
298 directory in order to rebuild a BitBake target.
299 The build process creates the directory for you
300 when you run BitBake.
301 </note></para>
302 <para>For information about each of the other variables defined in this
303 example, click on the links to take you to the definitions in
304 the glossary.
305 </para></listitem>
306 <listitem><para><emphasis>Run Bitbake:</emphasis>
307 After making sure that the <filename>conf/bitbake.conf</filename>
308 file exists, you can run the <filename>bitbake</filename>
309 command again:
310 <literallayout class='monospaced'>
311$ bitbake
312ERROR: Traceback (most recent call last):
313 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
314 return func(fn, *args)
315 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
316 bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
317 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
318 include(fn, file, lineno, d, "inherit")
319 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
320 raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
321ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
322
323ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
324 </literallayout>
325 In the sample output, BitBake could not find the
326 <filename>classes/base.bbclass</filename> file.
327 You need to create that file next.
328 </para></listitem>
329 <listitem><para><emphasis>Creating <filename>classes/base.bbclass</filename>:</emphasis>
330 BitBake uses class files to provide common code and functionality.
331 The minimally required class for BitBake is the
332 <filename>classes/base.bbclass</filename> file.
333 The <filename>base</filename> class is implicitly inherited by
334 every recipe.
335 BitBake looks for the class in the <filename>classes</filename>
336 directory of the project (i.e <filename>hello/classes</filename>
337 in this example).
338 </para>
339 <para>Create the <filename>classes</filename> directory as follows:
340 <literallayout class='monospaced'>
341 $ cd $HOME/hello
342 $ mkdir classes
343 </literallayout>
344 Move to the <filename>classes</filename> directory and then
345 create the <filename>base.bbclass</filename> file by inserting
346 this single line:
347 <literallayout class='monospaced'>
348 addtask build
349 </literallayout>
350 The minimal task that BitBake runs is the
351 <filename>do_build</filename> task.
352 This is all the example needs in order to build the project.
353 Of course, the <filename>base.bbclass</filename> can have much
354 more depending on which build environments BitBake is
355 supporting.
356 For more information on the <filename>base.bbclass</filename> file,
357 you can look at
358 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#tasks'></ulink>.
359 </para></listitem>
360 <listitem><para><emphasis>Run Bitbake:</emphasis>
361 After making sure that the <filename>classes/base.bbclass</filename>
362 file exists, you can run the <filename>bitbake</filename>
363 command again:
364 <literallayout class='monospaced'>
365 $ bitbake
366 Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
367 </literallayout>
368 BitBake is finally reporting no errors.
369 However, you can see that it really does not have anything
370 to do.
371 You need to create a recipe that gives BitBake something to do.
372 </para></listitem>
373 <listitem><para><emphasis>Creating a Layer:</emphasis>
374 While it is not really necessary for such a small example,
375 it is good practice to create a layer in which to keep your
376 code separate from the general metadata used by BitBake.
377 Thus, this example creates and uses a layer called "mylayer".
378 <note>
379 You can find additional information on adding a layer at
380 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#adding-an-example-layer'></ulink>.
381 </note>
382 </para>
383 <para>Minimally, you need a recipe file and a layer configuration
384 file in your layer.
385 The configuration file needs to be in the <filename>conf</filename>
386 directory inside the layer.
387 Use these commands to set up the layer and the <filename>conf</filename>
388 directory:
389 <literallayout class='monospaced'>
390 $ cd $HOME
391 $ mkdir mylayer
392 $ cd mylayer
393 $ mkdir conf
394 </literallayout>
395 Move to the <filename>conf</filename> directory and create a
396 <filename>layer.conf</filename> file that has the following:
397 <literallayout class='monospaced'>
398 BBPATH .= ":${<link linkend='var-LAYERDIR'>LAYERDIR</link>}"
399
400 <link linkend='var-BBFILES'>BBFILES</link> += "${LAYERDIR}/*.bb"
401
402 <link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link> += "mylayer"
403 <link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR}/"
404 </literallayout>
405 For information on these variables, click the links
406 to go to the definitions in the glossary.</para>
407 <para>You need to create the recipe file next.
408 Inside your layer at the top-level, use an editor and create
409 a recipe file named <filename>printhello.bb</filename> that
410 has the following:
411 <literallayout class='monospaced'>
412 <link linkend='var-DESCRIPTION'>DESCRIPTION</link> = "Prints Hello World"
413 <link linkend='var-PN'>PN</link> = 'printhello'
414 <link linkend='var-PV'>PV</link> = '1'
415
416 python do_build() {
417 bb.plain("********************");
418 bb.plain("* *");
419 bb.plain("* Hello, World! *");
420 bb.plain("* *");
421 bb.plain("********************");
422 }
423 </literallayout>
424 The recipe file simply provides a description of the
425 recipe, the name, version, and the <filename>do_build</filename>
426 task, which prints out "Hello World" to the console.
427 For more information on these variables, follow the links
428 to the glossary.
429 </para></listitem>
430 <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
431 Now that a BitBake target exists, run the command and provide
432 that target:
433 <literallayout class='monospaced'>
434 $ cd $HOME/hello
435 $ bitbake printhello
436 ERROR: no recipe files to build, check your BBPATH and BBFILES?
437
438 Summary: There was 1 ERROR message shown, returning a non-zero exit code.
439 </literallayout>
440 We have created the layer with the recipe and the layer
441 configuration file but it still seems that BitBake cannot
442 find the recipe.
443 BitBake needs a <filename>conf/bblayers.conf</filename> that
444 lists the layers for the project.
445 Without this file, BitBake cannot find the recipe.
446 </para></listitem>
447 <listitem><para><emphasis>Creating <filename>conf/bblayers.conf</filename>:</emphasis>
448 BitBake uses the <filename>conf/bblayers.conf</filename> file
449 to locate layers needed for the project.
450 This file must reside in the <filename>conf</filename> directory
451 of the project (i.e. <filename>hello/conf</filename> for this
452 example).</para>
453 <para>Set your working directory to the <filename>hello/conf</filename>
454 directory and then create the <filename>bblayers.conf</filename>
455 file so that it contains the following:
456 <literallayout class='monospaced'>
457 BBLAYERS ?= " \
458 /home/&lt;you&gt;/mylayer \
459 "
460 </literallayout>
461 You need to provide your own information for
462 <filename>you</filename> in the file.
463 </para></listitem>
464 <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
465 Now that you have supplied the <filename>bblayers.conf</filename>
466 file, run the <filename>bitbake</filename> command and provide
467 the target:
468 <literallayout class='monospaced'>
469 $ bitbake printhello
470 Parsing recipes: 100% |##################################################################################|
471 Time: 00:00:00
472 Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
473 NOTE: Resolving any missing task queue dependencies
474 NOTE: Preparing runqueue
475 NOTE: Executing RunQueue Tasks
476 ********************
477 * *
478 * Hello, World! *
479 * *
480 ********************
481 NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
482 </literallayout>
483 BitBake finds the <filename>printhello</filename> recipe and
484 successfully runs the task.
485 <note>
486 After the first execution, re-running
487 <filename>bitbake printhello</filename> again will not
488 result in a BitBake run that prints the same console
489 output.
490 The reason for this is that the first time the
491 <filename>printhello.bb</filename> recipe's
492 <filename>do_build</filename> task executes
493 successfully, BitBake writes a stamp file for the task.
494 Thus, the next time you attempt to run the task
495 using that same <filename>bitbake</filename> command,
496 BitBake notices the stamp and therefore determines
497 that the task does not need to be re-run.
498 If you delete the <filename>tmp</filename> directory
499 or run <filename>bitbake -c clean printhello</filename>
500 and then re-run the build, the "Hello, World!" message will
501 be printed again.
502 </note>
503 </para></listitem>
504 </orderedlist>
505 </section>
506</appendix>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
new file mode 100644
index 0000000000..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..a9f5072128
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -0,0 +1,1712 @@
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
305 <section id='providing-pathnames'>
306 <title>Providing Pathnames</title>
307
308 <para>
309 When specifying pathnames for use with BitBake,
310 do not use the tilde ("~") character as a shortcut
311 for your home directory.
312 Doing so might cause BitBake to not recognize the
313 path since BitBake does not expand this character in
314 the same way a shell would.
315 </para>
316
317 <para>
318 Instead, provide a fuller path as the following
319 example illustrates:
320 <literallayout class='monospaced'>
321 BBLAYERS ?= " \
322 /home/scott-lenovo/LayerA \
323 "
324 </literallayout>
325 </para>
326 </section>
327 </section>
328
329 <section id='conditional-syntax-overrides'>
330 <title>Conditional Syntax (Overrides)</title>
331
332 <para>
333 BitBake uses
334 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
335 to control what variables are overridden after BitBake
336 parses recipes and configuration files.
337 This section describes how you can use
338 <filename>OVERRIDES</filename> as conditional metadata,
339 talks about key expansion in relationship to
340 <filename>OVERRIDES</filename>, and provides some examples
341 to help with understanding.
342 </para>
343
344 <section id='conditional-metadata'>
345 <title>Conditional Metadata</title>
346
347 <para>
348 You can use <filename>OVERRIDES</filename> to conditionally select
349 a specific version of a variable and to conditionally
350 append or prepend the value of a variable.
351 <itemizedlist>
352 <listitem><para><emphasis>Selecting a Variable:</emphasis>
353 The <filename>OVERRIDES</filename> variable is
354 a colon-character-separated list that contains items
355 for which you want to satisfy conditions.
356 Thus, if you have a variable that is conditional on “armâ€, and “armâ€
357 is in <filename>OVERRIDES</filename>, then the “armâ€-specific
358 version of the variable is used rather than the non-conditional
359 version.
360 Here is an example:
361 <literallayout class='monospaced'>
362 OVERRIDES = "architecture:os:machine"
363 TEST = "default"
364 TEST_os = "osspecific"
365 TEST_nooverride = "othercondvalue"
366 </literallayout>
367 In this example, the <filename>OVERRIDES</filename>
368 variable lists three overrides:
369 "architecture", "os", and "machine".
370 The variable <filename>TEST</filename> by itself has a default
371 value of "default".
372 You select the os-specific version of the <filename>TEST</filename>
373 variable by appending the "os" override to the variable
374 (i.e.<filename>TEST_os</filename>).
375 </para></listitem>
376 <listitem><para><emphasis>Appending and Prepending:</emphasis>
377 BitBake also supports append and prepend operations to
378 variable values based on whether a specific item is
379 listed in <filename>OVERRIDES</filename>.
380 Here is an example:
381 <literallayout class='monospaced'>
382 DEPENDS = "glibc ncurses"
383 OVERRIDES = "machine:local"
384 DEPENDS_append_machine = "libmad"
385 </literallayout>
386 In this example, <filename>DEPENDS</filename> becomes
387 "glibc ncurses libmad".
388 </para></listitem>
389 </itemizedlist>
390 </para>
391 </section>
392
393 <section id='key-expansion'>
394 <title>Key Expansion</title>
395
396 <para>
397 Key expansion happens when the BitBake datastore is finalized
398 just before BitBake expands overrides.
399 To better understand this, consider the following example:
400 <literallayout class='monospaced'>
401 A${B} = "X"
402 B = "2"
403 A2 = "Y"
404 </literallayout>
405 In this case, after all the parsing is complete, and
406 before any overrides are handled, BitBake expands
407 <filename>${B}</filename> into "2".
408 This expansion causes <filename>A2</filename>, which was
409 set to "Y" before the expansion, to become "X".
410 </para>
411 </section>
412
413 <section id='variable-interaction-worked-examples'>
414 <title>Examples</title>
415
416 <para>
417 Despite the previous explanations that show the different forms of
418 variable definitions, it can be hard to work
419 out exactly what happens when variable operators, conditional
420 overrides, and unconditional overrides are combined.
421 This section presents some common scenarios along
422 with explanations for variable interactions that
423 typically confuse users.
424 </para>
425
426 <para>
427 There is often confusion concerning the order in which
428 overrides and various "append" operators take effect.
429 Recall that an append or prepend operation using "_append"
430 and "_prepend" does not result in an immediate assignment
431 as would "+=", ".=", "=+", or "=.".
432 Consider the following example:
433 <literallayout class='monospaced'>
434 OVERRIDES = "foo"
435 A = "Z"
436 A_foo_append = "X"
437 </literallayout>
438 For this case, <filename>A</filename> is
439 unconditionally set to "Z" and "X" is
440 unconditionally and immediately appended to the variable
441 <filename>A_foo</filename>.
442 Because overrides have not been applied yet,
443 <filename>A_foo</filename> is set to "X" due to the append
444 and <filename>A</filename> simply equals "Z".
445 </para>
446
447 <para>
448 Applying overrides, however, changes things.
449 Since "foo" is listed in <filename>OVERRIDES</filename>,
450 the conditional variable <filename>A</filename> is replaced
451 with the "foo" version, which is equal to "X".
452 So effectively, <filename>A_foo</filename> replaces <filename>A</filename>.
453 </para>
454
455 <para>
456 This next example changes the order of the override and
457 the append:
458 <literallayout class='monospaced'>
459 OVERRIDES = "foo"
460 A = "Z"
461 A_append_foo = "X"
462 </literallayout>
463 For this case, before overrides are handled,
464 <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename>
465 is set to "X".
466 Once the override for "foo" is applied, however,
467 <filename>A</filename> gets appended with "X".
468 Consequently, <filename>A</filename> becomes "ZX".
469 Notice that spaces are not appended.
470 </para>
471
472 <para>
473 This next example has the order of the appends and overrides reversed
474 back as in the first example:
475 <literallayout class='monospaced'>
476 OVERRIDES = "foo"
477 A = "Y"
478 A_foo_append = "Z"
479 A_foo_append += "X"
480 </literallayout>
481 For this case, before any overrides are resolved,
482 <filename>A</filename> is set to "Y" using an immediate assignment.
483 After this immediate assignment, <filename>A_foo</filename> is set
484 to "Z", and then further appended with
485 "X" leaving the variable set to "Z X".
486 Finally, applying the override for "foo" results in the conditional
487 variable <filename>A</filename> becoming "Z X" (i.e.
488 <filename>A</filename> is replaced with <filename>A_foo</filename>).
489 </para>
490
491 <para>
492 This final example mixes in some varying operators:
493 <literallayout class='monospaced'>
494 A = "1"
495 A_append = "2"
496 A_append = "3"
497 A += "4"
498 A .= "5"
499 </literallayout>
500 For this case, the type of append operators are affecting the
501 order of assignments as BitBake passes through the code
502 multiple times.
503 Initially, <filename>A</filename> is set to "1 45" because
504 of the three statements that use immediate operators.
505 After these assignments are made, BitBake applies the
506 <filename>_append</filename> operations.
507 Those operations result in <filename>A</filename> becoming "1 4523".
508 </para>
509 </section>
510 </section>
511
512 <section id='sharing-functionality'>
513 <title>Sharing Functionality</title>
514
515 <para>
516 BitBake allows for metadata sharing through include files
517 (<filename>.inc</filename>) and class files
518 (<filename>.bbclass</filename>).
519 For example, suppose you have a piece of common functionality
520 such as a task definition that you want to share between
521 more than one recipe.
522 In this case, creating a <filename>.bbclass</filename>
523 file that contains the common functionality and then using
524 the <filename>inherit</filename> directive in your recipes to
525 inherit the class would be a common way to share the task.
526 </para>
527
528 <para>
529 This section presents the mechanisms BitBake provides to
530 allow you to share functionality between recipes.
531 Specifically, the mechanisms include <filename>include</filename>,
532 <filename>inherit</filename>, <filename>INHERIT</filename>, and
533 <filename>require</filename> directives.
534 </para>
535
536 <section id='locating-include-and-class-files'>
537 <title>Locating Include and Class Files</title>
538
539 <para>
540 BitBake uses the
541 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
542 variable to locate needed include and class files.
543 The <filename>BBPATH</filename> variable is analogous to
544 the environment variable <filename>PATH</filename>.
545 </para>
546
547 <para>
548 In order for include and class files to be found by BitBake,
549 they need to be located in a "classes" subdirectory that can
550 be found in <filename>BBPATH</filename>.
551 </para>
552 </section>
553
554 <section id='inherit-directive'>
555 <title><filename>inherit</filename> Directive</title>
556
557 <para>
558 When writing a recipe or class file, you can use the
559 <filename>inherit</filename> directive to inherit the
560 functionality of a class (<filename>.bbclass</filename>).
561 BitBake only supports this directive when used within recipe
562 and class files (i.e. <filename>.bb</filename> and
563 <filename>.bbclass</filename>).
564 </para>
565
566 <para>
567 The <filename>inherit</filename> directive is a rudimentary
568 means of specifying what classes of functionality your
569 recipes require.
570 For example, you can easily abstract out the tasks involved in
571 building a package that uses Autoconf and Automake and put
572 those tasks into a class file that can be used by your recipe.
573 </para>
574
575 <para>
576 As an example, your recipes could use the following directive
577 to inherit an <filename>autotools.bbclass</filename> file.
578 The class file would contain common functionality for using
579 Autotools that could be shared across recipes:
580 <literallayout class='monospaced'>
581 inherit autotools
582 </literallayout>
583 In this case, BitBake would search for the directory
584 <filename>classes/autotools.bbclass</filename>
585 in <filename>BBPATH</filename>.
586 <note>
587 You can override any values and functions of the
588 inherited class within your recipe by doing so
589 after the "inherit" statement.
590 </note>
591 </para>
592 </section>
593
594 <section id='include-directive'>
595 <title><filename>include</filename> Directive</title>
596
597 <para>
598 BitBake understands the <filename>include</filename>
599 directive.
600 This directive causes BitBake to parse whatever file you specify,
601 and to insert that file at that location.
602 The directive is much like its equivalent in Make except
603 that if the path specified on the include line is a relative
604 path, BitBake locates the first file it can find
605 within <filename>BBPATH</filename>.
606 </para>
607
608 <para>
609 As an example, suppose you needed a recipe to include some
610 self-test definitions:
611 <literallayout class='monospaced'>
612 include test_defs.inc
613 </literallayout>
614 <note>
615 The <filename>include</filename> directive does not
616 produce an error when the file cannot be found.
617 Consequently, it is recommended that if the file you
618 are including is expected to exist, you should use
619 <link linkend='require-inclusion'><filename>require</filename></link>
620 instead of <filename>include</filename>.
621 Doing so makes sure that an error is produced if the
622 file cannot be found.
623 </note>
624 </para>
625 </section>
626
627 <section id='require-inclusion'>
628 <title><filename>require</filename> Directive</title>
629
630 <para>
631 BitBake understands the <filename>require</filename>
632 directive.
633 This directive behaves just like the
634 <filename>include</filename> directive with the exception that
635 BitBake raises a parsing error if the file to be included cannot
636 be found.
637 Thus, any file you require is inserted into the file that is
638 being parsed at the location of the directive.
639 </para>
640
641 <para>
642 Similar to how BitBake handles
643 <link linkend='include-directive'><filename>include</filename></link>,
644 if the path specified
645 on the require line is a relative path, BitBake locates
646 the first file it can find within <filename>BBPATH</filename>.
647 </para>
648
649 <para>
650 As an example, suppose you have two versions of a recipe
651 (e.g. <filename>foo_1.2.2.bb</filename> and
652 <filename>foo_2.0.0.bb</filename>) where
653 each version contains some identical functionality that could be
654 shared.
655 You could create an include file named <filename>foo.inc</filename>
656 that contains the common definitions needed to build "foo".
657 You need to be sure <filename>foo.inc</filename> is located in the
658 same directory as your two recipe files as well.
659 Once these conditions are set up, you can share the functionality
660 using a <filename>require</filename> directive from within each
661 recipe:
662 <literallayout class='monospaced'>
663 require foo.inc
664 </literallayout>
665 </para>
666 </section>
667
668 <section id='inherit-configuration-directive'>
669 <title><filename>INHERIT</filename> Configuration Directive</title>
670
671 <para>
672 When creating a configuration file (<filename>.conf</filename>),
673 you can use the <filename>INHERIT</filename> directive to
674 inherit a class.
675 BitBake only supports this directive when used within
676 a configuration file.
677 </para>
678
679 <para>
680 As an example, suppose you needed to inherit a class
681 file called <filename>abc.bbclass</filename> from a
682 configuration file as follows:
683 <literallayout class='monospaced'>
684 INHERIT += "abc"
685 </literallayout>
686 This configuration directive causes the named
687 class to be inherited at the point of the directive
688 during parsing.
689 As with the <filename>inherit</filename> directive, the
690 <filename>.bbclass</filename> file must be located in a
691 "classes" subdirectory in one of the directories specified
692 in <filename>BBPATH</filename>.
693 <note>
694 Because <filename>.conf</filename> files are parsed
695 first during BitBake's execution, using
696 <filename>INHERIT</filename> to inherit a class effectively
697 inherits the class globally (i.e. for all recipes).
698 </note>
699 </para>
700 </section>
701 </section>
702
703 <section id='functions'>
704 <title>Functions</title>
705
706 <para>
707 As with most languages, functions are the building blocks that
708 are used to build up operations into tasks.
709 BitBake supports these types of functions:
710 <itemizedlist>
711 <listitem><para><emphasis>Shell Functions:</emphasis>
712 Functions written in shell script and executed either
713 directly as functions, tasks, or both.
714 They can also be called by other shell functions.
715 </para></listitem>
716 <listitem><para><emphasis>BitBake Style Python Functions:</emphasis>
717 Functions written in Python and executed by BitBake or other
718 Python functions using <filename>bb.build.exec_func()</filename>.
719 </para></listitem>
720 <listitem><para><emphasis>Python Functions:</emphasis>
721 Functions written in Python and executed by Python.
722 </para></listitem>
723 <listitem><para><emphasis>Anonymous Python Functions:</emphasis>
724 Python functions executed automatically during
725 parsing.
726 </para></listitem>
727 </itemizedlist>
728 Regardless of the type of function, you can only
729 define them in class (<filename>.bbclass</filename>)
730 and recipe (<filename>.bb</filename> or <filename>.inc</filename>)
731 files.
732 </para>
733
734 <section id='shell-functions'>
735 <title>Shell Functions</title>
736
737 <para>
738 Functions written in shell script and executed either
739 directly as functions, tasks, or both.
740 They can also be called by other shell functions.
741 Here is an example shell function definition:
742 <literallayout class='monospaced'>
743 some_function () {
744 echo "Hello World"
745 }
746 </literallayout>
747 When you create these types of functions in your recipe
748 or class files, you need to follow the shell programming
749 rules.
750 The scripts are executed by <filename>/bin/sh</filename>,
751 which may not be a bash shell but might be something
752 such as <filename>dash</filename>.
753 You should not use Bash-specific script (bashisms).
754 </para>
755 </section>
756
757 <section id='bitbake-style-python-functions'>
758 <title>BitBake Style Python Functions</title>
759
760 <para>
761 These functions are written in Python and executed by
762 BitBake or other Python functions using
763 <filename>bb.build.exec_func()</filename>.
764 </para>
765
766 <para>
767 An example BitBake function is:
768 <literallayout class='monospaced'>
769 python some_python_function () {
770 d.setVar("TEXT", "Hello World")
771 print d.getVar("TEXT", True)
772 }
773 </literallayout>
774 Because the Python "bb" and "os" modules are already
775 imported, you do not need to import these modules.
776 Also in these types of functions, the datastore ("d")
777 is a global variable and is always automatically
778 available.
779 </para>
780 </section>
781
782 <section id='python-functions'>
783 <title>Python Functions</title>
784
785 <para>
786 These functions are written in Python and are executed by
787 other Python code.
788 Examples of Python functions are utility functions
789 that you intend to call from in-line Python or
790 from within other Python functions.
791 Here is an example:
792 <literallayout class='monospaced'>
793 def get_depends(d):
794 if d.getVar('SOMECONDITION', True):
795 return "dependencywithcond"
796 else:
797 return "dependency"
798 SOMECONDITION = "1"
799 DEPENDS = "${@get_depends(d)}"
800 </literallayout>
801 This would result in <filename>DEPENDS</filename>
802 containing <filename>dependencywithcond</filename>.
803 </para>
804
805 <para>
806 Here are some things to know about Python functions:
807 <itemizedlist>
808 <listitem><para>Python functions can take parameters.
809 </para></listitem>
810 <listitem><para>The BitBake datastore is not
811 automatically available.
812 Consequently, you must pass it in as a
813 parameter to the function.
814 </para></listitem>
815 <listitem><para>The "bb" and "os" Python modules are
816 automatically available.
817 You do not need to import them.
818 </para></listitem>
819 </itemizedlist>
820 </para>
821 </section>
822
823 <section id='anonymous-python-functions'>
824 <title>Anonymous Python Functions</title>
825
826 <para>
827 Sometimes it is useful to run some code during
828 parsing to set variables or to perform other operations
829 programmatically.
830 To do this, you can define an anonymous Python function.
831 Here is an example that conditionally sets a
832 variable based on the value of another variable:
833 <literallayout class='monospaced'>
834 python __anonymous () {
835 if d.getVar('SOMEVAR', True) == 'value':
836 d.setVar('ANOTHERVAR', 'value2')
837 }
838 </literallayout>
839 The "__anonymous" function name is optional, so the
840 following example is functionally equivalent to the above:
841 <literallayout class='monospaced'>
842 python () {
843 if d.getVar('SOMEVAR', True) == 'value':
844 d.setVar('ANOTHERVAR', 'value2')
845 }
846 </literallayout>
847 Because unlike other Python functions anonymous
848 Python functions are executed during parsing, the
849 "d" variable within an anonymous Python function represents
850 the datastore for the entire recipe.
851 Consequently, you can set variable values here and
852 those values can be picked up by other functions.
853 </para>
854 </section>
855
856 <section id='flexible-inheritance-for-class-functions'>
857 <title>Flexible Inheritance for Class Functions</title>
858
859 <para>
860 Through coding techniques and the use of
861 <filename>EXPORT_FUNCTIONS</filename>, BitBake supports
862 exporting a function from a class such that the
863 class function appears as the default implementation
864 of the function, but can still be called if a recipe
865 inheriting the class needs to define its own version of
866 the function.
867 </para>
868
869 <para>
870 To understand the benefits of this feature, consider
871 the basic scenario where a class defines a task function
872 and your recipe inherits the class.
873 In this basic scenario, your recipe inherits the task
874 function as defined in the class.
875 If desired, your recipe can add to the start and end of the
876 function by using the "_prepend" or "_append" operations
877 respectively, or it can redefine the function completely.
878 However, if it redefines the function, there is
879 no means for it to call the class version of the function.
880 <filename>EXPORT_FUNCTIONS</filename> provides a mechanism
881 that enables the recipe's version of the function to call
882 the original version of the function.
883 </para>
884
885 <para>
886 To make use of this technique, you need the following
887 things in place:
888 <itemizedlist>
889 <listitem><para>
890 The class needs to define the function as follows:
891 <literallayout class='monospaced'>
892 &lt;classname&gt;_&lt;functionname&gt;
893 </literallayout>
894 For example, if you have a class file
895 <filename>bar.bbclass</filename> and a function named
896 <filename>do_foo</filename>, the class must define the function
897 as follows:
898 <literallayout class='monospaced'>
899 bar_do_foo
900 </literallayout>
901 </para></listitem>
902 <listitem><para>
903 The class needs to contain the <filename>EXPORT_FUNCTIONS</filename>
904 statement as follows:
905 <literallayout class='monospaced'>
906 EXPORT_FUNCTIONS &lt;functionname&gt;
907 </literallayout>
908 For example, continuing with the same example, the
909 statement in the <filename>bar.bbclass</filename> would be
910 as follows:
911 <literallayout class='monospaced'>
912 EXPORT_FUNCTIONS do_foo
913 </literallayout>
914 </para></listitem>
915 <listitem><para>
916 You need to call the function appropriately from within your
917 recipe.
918 Continuing with the same example, if your recipe
919 needs to call the class version of the function,
920 it should call <filename>bar_do_foo</filename>.
921 Assuming <filename>do_foo</filename> was a shell function
922 and <filename>EXPORT_FUNCTIONS</filename> was used as above,
923 the recipe's function could conditionally call the
924 class version of the function as follows:
925 <literallayout class='monospaced'>
926 do_foo() {
927 if [ somecondition ] ; then
928 bar_do_foo
929 else
930 # Do something else
931 fi
932 }
933 </literallayout>
934 To call your modified version of the function as defined
935 in your recipe, call it as <filename>do_foo</filename>.
936 </para></listitem>
937 </itemizedlist>
938 With these conditions met, your single recipe
939 can freely choose between the original function
940 as defined in the class file and the modified function in your recipe.
941 If you do not set up these conditions, you are limited to using one function
942 or the other.
943 </para>
944 </section>
945 </section>
946
947 <section id='tasks'>
948 <title>Tasks</title>
949
950 <para>
951 Tasks are BitBake execution units that originate as
952 functions and make up the steps that BitBake needs to run
953 for given recipe.
954 Tasks are only supported in recipe (<filename>.bb</filename>
955 or <filename>.inc</filename>) and class
956 (<filename>.bbclass</filename>) files.
957 By convention, task names begin with the string "do_".
958 </para>
959
960 <para>
961 Here is an example of a task that prints out the date:
962 <literallayout class='monospaced'>
963 python do_printdate () {
964 import time
965 print time.strftime('%Y%m%d', time.gmtime())
966 }
967 addtask printdate after do_fetch before do_build
968 </literallayout>
969 </para>
970
971 <section id='promoting-a-function-to-a-task'>
972 <title>Promoting a Function to a Task</title>
973
974 <para>
975 Any function can be promoted to a task by applying the
976 <filename>addtask</filename> command.
977 The <filename>addtask</filename> command also describes
978 inter-task dependencies.
979 Here is the function from the previous section but with the
980 <filename>addtask</filename> command promoting it to a task
981 and defining some dependencies:
982 <literallayout class='monospaced'>
983 python do_printdate () {
984 import time
985 print time.strftime('%Y%m%d', time.gmtime())
986 }
987 addtask printdate after do_fetch before do_build
988 </literallayout>
989 In the example, the function is defined and then promoted
990 as a task.
991 The <filename>do_printdate</filename> task becomes a dependency of
992 the <filename>do_build</filename> task, which is the default
993 task.
994 And, the <filename>do_printdate</filename> task is dependent upon
995 the <filename>do_fetch</filename> task.
996 Execution of the <filename>do_build</filename> task results
997 in the <filename>do_printdate</filename> task running first.
998 </para>
999 </section>
1000
1001 <section id='deleting-a-task'>
1002 <title>Deleting a Task</title>
1003
1004 <para>
1005 As well as being able to add tasks, tasks can also be deleted.
1006 This is done simply with <filename>deltask</filename> command.
1007 For example, to delete the example task used in the previous
1008 sections, you would use:
1009 <literallayout class='monospaced'>
1010 deltask printdate
1011 </literallayout>
1012 </para>
1013 </section>
1014
1015 <section id='passing-information-into-the-build-task-environment'>
1016 <title>Passing Information Into the Build Task Environment</title>
1017
1018 <para>
1019 When running a task, BitBake tightly controls the execution
1020 environment of the build tasks to make
1021 sure unwanted contamination from the build machine cannot
1022 influence the build.
1023 Consequently, if you do want something to get passed into the
1024 build task environment, you must take these two steps:
1025 <orderedlist>
1026 <listitem><para>
1027 Tell BitBake to load what you want from the environment
1028 into the datastore.
1029 You can do so through the
1030 <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
1031 variable.
1032 For example, assume you want to prevent the build system from
1033 accessing your <filename>$HOME/.ccache</filename>
1034 directory.
1035 The following command tells BitBake to load
1036 <filename>CCACHE_DIR</filename> from the environment into
1037 the datastore:
1038 <literallayout class='monospaced'>
1039 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1040 </literallayout></para></listitem>
1041 <listitem><para>
1042 Tell BitBake to export what you have loaded into the
1043 datastore to the task environment of every running task.
1044 Loading something from the environment into the datastore
1045 (previous step) only makes it available in the datastore.
1046 To export it to the task environment of every running task,
1047 use a command similar to the following in your local configuration
1048 file <filename>local.conf</filename> or your
1049 distribution configuration file:
1050 <literallayout class='monospaced'>
1051 export CCACHE_DIR
1052 </literallayout>
1053 <note>
1054 A side effect of the previous steps is that BitBake
1055 records the variable as a dependency of the build process
1056 in things like the setscene checksums.
1057 If doing so results in unnecessary rebuilds of tasks, you can
1058 whitelist the variable so that the setscene code
1059 ignores the dependency when it creates checksums.
1060 </note></para></listitem>
1061 </orderedlist>
1062 </para>
1063
1064 <para>
1065 Sometimes, it is useful to be able to obtain information
1066 from the original execution environment.
1067 Bitbake saves a copy of the original environment into
1068 a special variable named
1069 <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
1070 </para>
1071
1072 <para>
1073 The <filename>BB_ORIGENV</filename> variable returns a datastore
1074 object that can be queried using the standard datastore operators
1075 such as <filename>getVar()</filename>.
1076 The datastore object is useful, for example, to find the original
1077 <filename>DISPLAY</filename> variable.
1078 Here is an example:
1079 <literallayout class='monospaced'>
1080 BB_ORIGENV - add example?
1081
1082 origenv = d.getVar("BB_ORIGENV", False)
1083 bar = origenv.getVar("BAR", False)
1084 </literallayout>
1085 The previous example returns <filename>BAR</filename> from the original
1086 execution environment.
1087 </para>
1088
1089 <para>
1090 By default, BitBake cleans the environment to include only those
1091 things exported or listed in its whitelist to ensure that the build
1092 environment is reproducible and consistent.
1093 </para>
1094 </section>
1095 </section>
1096
1097 <section id='variable-flags'>
1098 <title>Variable Flags</title>
1099
1100 <para>
1101 Variable flags (varflags) help control a task's functionality
1102 and dependencies.
1103 BitBake reads and writes varflags to the datastore using the following
1104 command forms:
1105 <literallayout class='monospaced'>
1106 &lt;variable&gt; = d.getVarFlags("&lt;variable&gt;")
1107 self.d.setVarFlags("FOO", {"func": True})
1108 </literallayout>
1109 </para>
1110
1111 <para>
1112 When working with varflags, the same syntax, with the exception of
1113 overrides, applies.
1114 In other words, you can set, append, and prepend varflags just like
1115 variables.
1116 See the
1117 "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>"
1118 section for details.
1119 </para>
1120
1121 <para>
1122 BitBake has a defined set of varflags available for recipes and
1123 classes.
1124 Tasks support a number of these flags which control various
1125 functionality of the task:
1126 <itemizedlist>
1127 <listitem><para><emphasis>dirs:</emphasis>
1128 Directories that should be created before the task runs.
1129 </para></listitem>
1130 <listitem><para><emphasis>cleandirs:</emphasis>
1131 Empty directories that should created before the task runs.
1132 </para></listitem>
1133 <listitem><para><emphasis>noexec:</emphasis>
1134 Marks the tasks as being empty and no execution required.
1135 The <filename>noexec</filename> flag can be used to set up
1136 tasks as dependency placeholders, or to disable tasks defined
1137 elsewhere that are not needed in a particular recipe.
1138 </para></listitem>
1139 <listitem><para><emphasis>nostamp:</emphasis>
1140 Tells BitBake to not generate a stamp file for a task,
1141 which implies the task should always be executed.
1142 </para></listitem>
1143 <listitem><para><emphasis>fakeroot:</emphasis>
1144 Causes a task to be run in a fakeroot environment,
1145 obtained by adding the variables in
1146 <link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
1147 to the environment.
1148 </para></listitem>
1149 <listitem><para><emphasis>umask:</emphasis>
1150 The umask to run the task under.
1151 </para></listitem>
1152 <listitem><para><emphasis>deptask:</emphasis>
1153 Controls task build-time dependencies.
1154 See the
1155 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1156 variable and the
1157 "<link linkend='build-dependencies'>Build Dependencies</link>"
1158 section for more information.
1159 </para></listitem>
1160 <listitem><para><emphasis>rdeptask:</emphasis>
1161 Controls task runtime dependencies.
1162 See the
1163 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1164 variable, the
1165 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1166 variable, and the
1167 "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
1168 section for more information.
1169 </para></listitem>
1170 <listitem><para><emphasis>recrdeptask:</emphasis>
1171 Controls task recursive runtime dependencies.
1172 See the
1173 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1174 variable, the
1175 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1176 variable, and the
1177 "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
1178 section for more information.
1179 </para></listitem>
1180 <listitem><para><emphasis>depends:</emphasis>
1181 Controls inter-task dependencies.
1182 See the
1183 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1184 variable and the
1185 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1186 section for more information.
1187 </para></listitem>
1188 <listitem><para><emphasis>rdepends:</emphasis>
1189 Controls inter-task runtime dependencies.
1190 See the
1191 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1192 variable, the
1193 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1194 variable, and the
1195 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1196 section for more information.
1197 </para></listitem>
1198 <listitem><para><emphasis>postfuncs:</emphasis>
1199 List of functions to call after the completion of the task.
1200 </para></listitem>
1201 <listitem><para><emphasis>prefuncs:</emphasis>
1202 List of functions to call before the task executes.
1203 </para></listitem>
1204 <listitem><para><emphasis>stamp-extra-info:</emphasis>
1205 Extra stamp information to append to the task's stamp.
1206 As an example, OpenEmbedded uses this flag to allow
1207 machine-specific tasks.
1208 </para></listitem>
1209 </itemizedlist>
1210 </para>
1211
1212 <para>
1213 Several varflags are useful for controlling how signatures are
1214 calculated for variables.
1215 For more information on this process, see the
1216 "<link linkend='checksums'>Checksums (Signatures)</link>"
1217 section.
1218 <itemizedlist>
1219 <listitem><para><emphasis>vardeps:</emphasis>
1220 Specifies a space-separated list of additional
1221 variables to add to a variable's dependencies
1222 for the purposes of calculating its signature.
1223 Adding variables to this list is useful, for example, when
1224 a function refers to a variable in a manner that
1225 does not allow BitBake to automatically determine
1226 that the variable is referred to.
1227 </para></listitem>
1228 <listitem><para><emphasis>vardepvalue:</emphasis>
1229 If set, instructs BitBake to ignore the actual
1230 value of the variable and instead use the specified
1231 value when calculating the variable's signature.
1232 </para></listitem>
1233 <listitem><para><emphasis>vardepsexclude:</emphasis>
1234 Specifies a space-separated list of variables
1235 that should be excluded from a variable's dependencies
1236 for the purposes of calculating its signature.
1237 </para></listitem>
1238 <listitem><para><emphasis>vardepvalueexclude:</emphasis>
1239 Specifies a pipe-separated list of strings to exclude
1240 from the variable's value when calculating the
1241 variable's signature.
1242 </para></listitem>
1243 </itemizedlist>
1244 </para>
1245 </section>
1246
1247 <section id='events'>
1248 <title>Events</title>
1249
1250 <para>
1251 BitBake allows installation of event handlers within
1252 recipe and class files.
1253 Events are triggered at certain points during operation,
1254 such as the beginning of operation against a given
1255 <filename>.bb</filename>, the start of a given task,
1256 task failure, task success, and so forth.
1257 The intent is to make it easy to do things like email
1258 notification on build failure.
1259 </para>
1260
1261 <para>
1262 Following is an example event handler that
1263 prints the name of the event and the content of
1264 the <filename>FILE</filename> variable:
1265 <literallayout class='monospaced'>
1266 addhandler myclass_eventhandler
1267 python myclass_eventhandler() {
1268 from bb.event import getName
1269 from bb import data
1270 print("The name of the Event is %s" % getName(e))
1271 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
1272 }
1273 </literallayout>
1274 This event handler gets called every time an event is
1275 triggered.
1276 A global variable "<filename>e</filename>" is defined and
1277 "<filename>e.data</filename>" contains an instance of
1278 "<filename>bb.data</filename>".
1279 With the <filename>getName(e)</filename> method, one can get
1280 the name of the triggered event.
1281 </para>
1282
1283 <para>
1284 During a standard build, the following common events might occur:
1285 <itemizedlist>
1286 <listitem><para>
1287 <filename>bb.event.ConfigParsed()</filename>
1288 </para></listitem>
1289 <listitem><para>
1290 <filename>bb.event.ParseStarted()</filename>
1291 </para></listitem>
1292 <listitem><para>
1293 <filename>bb.event.ParseProgress()</filename>
1294 </para></listitem>
1295 <listitem><para>
1296 <filename>bb.event.ParseCompleted()</filename>
1297 </para></listitem>
1298 <listitem><para>
1299 <filename>bb.event.BuildStarted()</filename>
1300 </para></listitem>
1301 <listitem><para>
1302 <filename>bb.build.TaskStarted()</filename>
1303 </para></listitem>
1304 <listitem><para>
1305 <filename>bb.build.TaskInvalid()</filename>
1306 </para></listitem>
1307 <listitem><para>
1308 <filename>bb.build.TaskFailedSilent()</filename>
1309 </para></listitem>
1310 <listitem><para>
1311 <filename>bb.build.TaskFailed()</filename>
1312 </para></listitem>
1313 <listitem><para>
1314 <filename>bb.build.TaskSucceeded()</filename>
1315 </para></listitem>
1316 <listitem><para>
1317 <filename>bb.event.BuildCompleted()</filename>
1318 </para></listitem>
1319 <listitem><para>
1320 <filename>bb.cooker.CookerExit()</filename>
1321 </para></listitem>
1322 </itemizedlist>
1323 Here is a list of other events that occur based on specific requests
1324 to the server:
1325 <itemizedlist>
1326 <listitem><para>
1327 <filename>bb.event.TreeDataPreparationStarted()</filename>
1328 </para></listitem>
1329 <listitem><para>
1330 <filename>bb.event.TreeDataPreparationProgress</filename>
1331 </para></listitem>
1332 <listitem><para>
1333 <filename>bb.event.TreeDataPreparationCompleted</filename>
1334 </para></listitem>
1335 <listitem><para>
1336 <filename>bb.event.DepTreeGenerated</filename>
1337 </para></listitem>
1338 <listitem><para>
1339 <filename>bb.event.CoreBaseFilesFound</filename>
1340 </para></listitem>
1341 <listitem><para>
1342 <filename>bb.event.ConfigFilePathFound</filename>
1343 </para></listitem>
1344 <listitem><para>
1345 <filename>bb.event.FilesMatchingFound</filename>
1346 </para></listitem>
1347 <listitem><para>
1348 <filename>bb.event.ConfigFilesFound</filename>
1349 </para></listitem>
1350 <listitem><para>
1351 <filename>bb.event.TargetsTreeGenerated</filename>
1352 </para></listitem>
1353 </itemizedlist>
1354 </para>
1355 </section>
1356
1357 <section id='variants-class-extension-mechanism'>
1358 <title>Variants - Class Extension Mechanism</title>
1359
1360 <para>
1361 BitBake supports two features that facilitate creating
1362 from a single recipe file multiple incarnations of that
1363 recipe file where all incarnations are buildable.
1364 These features are enabled through the
1365 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
1366 and
1367 <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link>
1368 variables.
1369 <note>
1370 The mechanism for this class extension is extremely
1371 specific to the implementation.
1372 Usually, the recipe's
1373 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>,
1374 <link linkend='var-PN'><filename>PN</filename></link>, and
1375 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1376 variables would need to be modified by the extension class.
1377 For specific examples, see the OE-Core
1378 <filename>native</filename>, <filename>nativesdk</filename>,
1379 and <filename>multilib</filename> classes.
1380 </note>
1381 <itemizedlist>
1382 <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis>
1383 This variable is a space separated list of classes used to "extend" the
1384 recipe for each variant.
1385 Here is an example that results in a second incarnation of the current
1386 recipe being available.
1387 This second incarnation will have the "native" class inherited.
1388 <literallayout class='monospaced'>
1389 BBCLASSEXTEND = "native"
1390 </literallayout></para></listitem>
1391 <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis>
1392 This variable allows a single recipe to build multiple versions of a
1393 project from a single recipe file.
1394 You can also specify conditional metadata
1395 (using the
1396 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1397 mechanism) for a single version, or an optionally named range of versions.
1398 Here is an example:
1399 <literallayout class='monospaced'>
1400 BBVERSIONS = "1.0 2.0 git"
1401 SRC_URI_git = "git://someurl/somepath.git"
1402
1403 BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
1404 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
1405 </literallayout>
1406 The name of the range defaults to the original version of the
1407 recipe.
1408 For example, in OpenEmbedded, the recipe file
1409 <filename>foo_1.0.0+.bb</filename> creates a default name range
1410 of <filename>1.0.0+</filename>.
1411 This is useful because the range name is not only placed
1412 into overrides, but it is also made available for the metadata to use
1413 in the variable that defines the base recipe versions for use in
1414 <filename>file://</filename> search paths
1415 (<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>).
1416 </para></listitem>
1417 </itemizedlist>
1418 </para>
1419 </section>
1420
1421 <section id='dependencies'>
1422 <title>Dependencies</title>
1423
1424 <para>
1425 To allow for efficient operation given multiple processes
1426 executing in parallel, BitBake handles dependencies at
1427 the task level.
1428 BitBake supports a robust method to handle these dependencies.
1429 </para>
1430
1431 <para>
1432 This section describes several types of dependency mechanisms.
1433 </para>
1434
1435 <section id='dependencies-internal-to-the-bb-file'>
1436 <title>Dependencies Internal to the <filename>.bb</filename> File</title>
1437
1438 <para>
1439 BitBake uses the <filename>addtask</filename> directive
1440 to manage dependencies that are internal to a given recipe
1441 file.
1442 You can use the <filename>addtask</filename> directive to
1443 indicate when a task is dependent on other tasks or when
1444 other tasks depend on that recipe.
1445 Here is an example:
1446 <literallayout class='monospaced'>
1447 addtask printdate after do_fetch before do_build
1448 </literallayout>
1449 In this example, the <filename>printdate</filename> task is
1450 depends on the completion of the <filename>do_fetch</filename>
1451 task.
1452 And, the <filename>do_build</filename> depends on the completion
1453 of the <filename>printdate</filename> task.
1454 </para>
1455 </section>
1456
1457 <section id='build-dependencies'>
1458 <title>Build Dependencies</title>
1459
1460 <para>
1461 BitBake uses the
1462 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1463 variable to manage build time dependencies.
1464 The "deptask" varflag for tasks signifies the task of each
1465 item listed in <filename>DEPENDS</filename> that must
1466 complete before that task can be executed.
1467 Here is an example:
1468 <literallayout class='monospaced'>
1469 do_configure[deptask] = "do_populate_staging"
1470 </literallayout>
1471 In this example, the <filename>do_populate_staging</filename>
1472 task of each item in <filename>DEPENDS</filename> must complete before
1473 <filename>do_configure</filename> can execute.
1474 </para>
1475 </section>
1476
1477 <section id='runtime-dependencies'>
1478 <title>Runtime Dependencies</title>
1479
1480 <para>
1481 BitBake uses the
1482 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
1483 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, and
1484 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1485 variables to manage runtime dependencies.
1486 </para>
1487
1488 <para>
1489 The <filename>PACKAGES</filename> variable lists runtime
1490 packages.
1491 Each of those packages can have <filename>RDEPENDS</filename> and
1492 <filename>RRECOMMENDS</filename> runtime dependencies.
1493 The "rdeptask" flag for tasks is used to signify the task of each
1494 item runtime dependency which must have completed before that
1495 task can be executed.
1496 <literallayout class='monospaced'>
1497 do_package_write[rdeptask] = "do_package"
1498 </literallayout>
1499 In the previous example, the <filename>do_package</filename>
1500 task of each item in <filename>RDEPENDS</filename> must have
1501 completed before <filename>do_package_write</filename> can execute.
1502 </para>
1503 </section>
1504
1505 <section id='recursive-dependencies'>
1506 <title>Recursive Dependencies</title>
1507
1508 <para>
1509 BitBake uses the "recrdeptask" flag to manage
1510 recursive task dependencies.
1511 BitBake looks through the build-time and runtime
1512 dependencies of the current recipe, looks through
1513 the task's inter-task
1514 dependencies, and then adds dependencies for the
1515 listed task.
1516 Once BitBake has accomplished this, it recursively works through
1517 the dependencies of those tasks.
1518 Iterative passes continue until all dependencies are discovered
1519 and added.
1520 </para>
1521
1522 <para>
1523 You might want to not only have BitBake look for
1524 dependencies of those tasks, but also have BitBake look
1525 for build-time and runtime dependencies of the dependent
1526 tasks as well.
1527 If that is the case, you need to reference the task name
1528 itself in the task list:
1529 <literallayout class='monospaced'>
1530 do_a[recrdeptask] = "do_a do_b"
1531 </literallayout>
1532 </para>
1533 </section>
1534
1535 <section id='inter-task-dependencies'>
1536 <title>Inter-Task Dependencies</title>
1537
1538 <para>
1539 BitBake uses the "depends" flag in a more generic form
1540 to manage inter-task dependencies.
1541 This more generic form allows for inter-dependency
1542 checks for specific tasks rather than checks for
1543 the data in <filename>DEPENDS</filename>.
1544 Here is an example:
1545 <literallayout class='monospaced'>
1546 do_patch[depends] = "quilt-native:do_populate_staging"
1547 </literallayout>
1548 In this example, the <filename>do_populate_staging</filename>
1549 task of the target <filename>quilt-native</filename>
1550 must have completed before the
1551 <filename>do_patch</filename> task can execute.
1552 </para>
1553
1554 <para>
1555 The "rdepends" flag works in a similar way but takes targets
1556 in the runtime namespace instead of the build-time dependency
1557 namespace.
1558 </para>
1559 </section>
1560 </section>
1561
1562 <section id='accessing-datastore-variables-using-python'>
1563 <title>Accessing Datastore Variables Using Python</title>
1564
1565 <para>
1566 It is often necessary to access variables in the
1567 BitBake datastore using Python functions.
1568 The Bitbake datastore has an API that allows you this
1569 access.
1570 Here is a list of available operations:
1571 </para>
1572
1573 <para>
1574 <informaltable frame='none'>
1575 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
1576 <colspec colname='c1' colwidth='1*'/>
1577 <colspec colname='c2' colwidth='1*'/>
1578 <thead>
1579 <row>
1580 <entry align="left"><emphasis>Operation</emphasis></entry>
1581 <entry align="left"><emphasis>Description</emphasis></entry>
1582 </row>
1583 </thead>
1584 <tbody>
1585 <row>
1586 <entry align="left"><filename>d.getVar("X", expand=False)</filename></entry>
1587 <entry align="left">Returns the value of variable "X".
1588 Using "expand=True" expands the value.</entry>
1589 </row>
1590 <row>
1591 <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
1592 <entry align="left">Sets the variable "X" to "value".</entry>
1593 </row>
1594 <row>
1595 <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
1596 <entry align="left">Adds "value" to the end of the variable "X".</entry>
1597 </row>
1598 <row>
1599 <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
1600 <entry align="left">Adds "value" to the start of the variable "X".</entry>
1601 </row>
1602 <row>
1603 <entry align="left"><filename>d.delVar("X")</filename></entry>
1604 <entry align="left">Deletes the variable "X" from the datastore.</entry>
1605 </row>
1606 <row>
1607 <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
1608 <entry align="left">Renames the variable "X" to "Y".</entry>
1609 </row>
1610 <row>
1611 <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
1612 <entry align="left">Gets then named flag from the variable "X".
1613 Using "expand=True" expands the named flag.</entry>
1614 </row>
1615 <row>
1616 <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
1617 <entry align="left">Sets the named flag for variable "X" to "value".</entry>
1618 </row>
1619 <row>
1620 <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
1621 <entry align="left">Appends "value" to the named flag on the
1622 variable "X".</entry>
1623 </row>
1624 <row>
1625 <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
1626 <entry align="left">Prepends "value" to the named flag on
1627 the variable "X".</entry>
1628 </row>
1629 <row>
1630 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
1631 <entry align="left">Deletes the named flag on the variable
1632 "X" from the datastore.</entry>
1633 </row>
1634 <row>
1635 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
1636 <entry align="left">Sets the flags specified in
1637 the <filename>flagsdict()</filename> parameter.
1638 <filename>setVarFlags</filename> does not clear previous flags.
1639 Think of this operation as <filename>addVarFlags</filename>.</entry>
1640 </row>
1641 <row>
1642 <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
1643 <entry align="left">Returns a <filename>flagsdict</filename> of the flags for
1644 the variable "X".</entry>
1645 </row>
1646 <row>
1647 <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
1648 <entry align="left">Deletes all the flags for the variable "X".</entry>
1649 </row>
1650 </tbody>
1651 </tgroup>
1652 </informaltable>
1653 </para>
1654 </section>
1655
1656 <section id='task-checksums-and-setscene'>
1657 <title>Task Checksums and Setscene</title>
1658
1659 <para>
1660 BitBake uses checksums (or signatures) along with the setscene
1661 to determine if a task needs to be run.
1662 This section describes the process.
1663 To help understand how BitBake does this, the section assumes an
1664 OpenEmbedded metadata-based example.
1665 </para>
1666
1667 <para>
1668 This list is a place holder of content existed from previous work
1669 on the manual.
1670 Some or all of it probably needs integrated into the subsections
1671 that make up this section.
1672 For now, I have just provided a short glossary-like description
1673 for each variable.
1674 Ultimately, this list goes away.
1675 <itemizedlist>
1676 <listitem><para><filename>STAMP</filename>:
1677 The base path to create stamp files.</para></listitem>
1678 <listitem><para><filename>STAMPCLEAN</filename>
1679 Again, the base path to create stamp files but can use wildcards
1680 for matching a range of files for clean operations.
1681 </para></listitem>
1682 <listitem><para><filename>BB_STAMP_WHITELIST</filename>
1683 Lists stamp files that are looked at when the stamp policy
1684 is "whitelist".
1685 </para></listitem>
1686 <listitem><para><filename>BB_STAMP_POLICY</filename>
1687 Defines the mode for comparing timestamps of stamp files.
1688 </para></listitem>
1689 <listitem><para><filename>BB_HASHCHECK_FUNCTION</filename>
1690 Specifies the name of the function to call during
1691 the "setscene" part of the task's execution in order
1692 to validate the list of task hashes.
1693 </para></listitem>
1694 <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
1695 Specifies a function to call that verifies the list of
1696 planned task execution before the main task execution
1697 happens.
1698 </para></listitem>
1699 <listitem><para><filename>BB_SETSCENE_DEPVALID</filename>
1700 Specifies a function BitBake calls that determines
1701 whether BitBake requires a setscene dependency to
1702 be met.
1703 </para></listitem>
1704 <listitem><para><filename>BB_TASKHASH</filename>
1705 Within an executing task, this variable holds the hash
1706 of the task as returned by the currently enabled
1707 signature generator.
1708 </para></listitem>
1709 </itemizedlist>
1710 </para>
1711 </section>
1712</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..b33a457d63
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
@@ -0,0 +1,2132 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used by BitBake and gives an overview
12 of their function and contents.
13</para>
14
15<note>
16 Following are some points regarding the variables listed in this glossary:
17 <itemizedlist>
18 <listitem><para>The variables listed in this glossary
19 are specific to BitBake.
20 Consequently, the descriptions are limited to that context.
21 </para></listitem>
22 <listitem><para>Also, variables exist in other systems that use BitBake
23 (e.g. The Yocto Project and OpenEmbedded) that have names identical
24 to those found in this glossary.
25 For such cases, the variables in those systems extend the
26 functionality of the variable as it is described here in
27 this glossary.
28 </para></listitem>
29 <listitem><para>Finally, there are variables mentioned in this
30 glossary that do not appear in the BitBake glossary.
31 These other variables are variables used in systems that use
32 BitBake.
33 </para></listitem>
34 </itemizedlist>
35</note>
36
37<glossary id='ref-variables-glossary'>
38
39 <para>
40 <link linkend='var-ASSUME_PROVIDED'>A</link>
41 <link linkend='var-B'>B</link>
42 <link linkend='var-CACHE'>C</link>
43 <link linkend='var-DEFAULT_PREFERENCE'>D</link>
44 <link linkend='var-EXCLUDE_FROM_WORLD'>E</link>
45 <link linkend='var-FAKEROOT'>F</link>
46<!-- <link linkend='var-GROUPADD_PARAM'>G</link> -->
47 <link linkend='var-HOMEPAGE'>H</link>
48<!-- <link linkend='var-ICECC_DISABLED'>I</link> -->
49<!-- <link linkend='var-glossary-j'>J</link> -->
50<!-- <link linkend='var-KARCH'>K</link> -->
51 <link linkend='var-LAYERDEPENDS'>L</link>
52 <link linkend='var-MIRRORS'>M</link>
53<!-- <link linkend='var-glossary-n'>N</link> -->
54 <link linkend='var-OVERRIDES'>O</link>
55 <link linkend='var-PACKAGES'>P</link>
56<!-- <link linkend='var-QMAKE_PROFILES'>Q</link> -->
57 <link linkend='var-RDEPENDS'>R</link>
58 <link linkend='var-SECTION'>S</link>
59 <link linkend='var-T'>T</link>
60<!-- <link linkend='var-UBOOT_CONFIG'>U</link> -->
61<!-- <link linkend='var-glossary-v'>V</link> -->
62<!-- <link linkend='var-WARN_QA'>W</link> -->
63<!-- <link linkend='var-glossary-x'>X</link> -->
64<!-- <link linkend='var-glossary-y'>Y</link> -->
65<!-- <link linkend='var-glossary-z'>Z</link>-->
66 </para>
67
68 <glossdiv id='var-glossary-a'><title>A</title>
69
70 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
71 <glossdef>
72 <para>
73 Lists recipe names
74 (<link linkend='var-PN'><filename>PN</filename></link>
75 values) BitBake does not attempt to build.
76 Instead, BitBake assumes these recipes have already been
77 built.
78 </para>
79
80 <para>
81 In OpenEmbedded Core, <filename>ASSUME_PROVIDED</filename>
82 mostly specifies native tools that should not be built.
83 An example is <filename>git-native</filename>, which
84 when specified allows for the Git binary from the host to
85 be used rather than building
86 <filename>git-native</filename>.
87 </para>
88 </glossdef>
89 </glossentry>
90
91 </glossdiv>
92
93
94 <glossdiv id='var-glossary-b'><title>B</title>
95
96 <glossentry id='var-B'><glossterm>B</glossterm>
97 <glossdef>
98 <para>
99 The directory in which BitBake executes functions
100 during a recipe's build process.
101 </para>
102 </glossdef>
103 </glossentry>
104
105 <glossentry id='var-BB_CONSOLELOG'><glossterm>BB_CONSOLELOG</glossterm>
106 <glossdef>
107 <para>
108 Specifies the path to a log file into which BitBake's user
109 interface writes output during the build.
110 </para>
111 </glossdef>
112 </glossentry>
113
114 <glossentry id='var-BB_CURRENTTASK'><glossterm>BB_CURRENTTASK</glossterm>
115 <glossdef>
116 <para>
117 Contains the name of the currently running task.
118 The name does not include the
119 <filename>do_</filename> prefix.
120 </para>
121 </glossdef>
122 </glossentry>
123
124 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
125 <glossdef>
126 <para>
127 Defines how BitBake handles situations where an append
128 file (<filename>.bbappend</filename>) has no
129 corresponding recipe file (<filename>.bb</filename>).
130 This condition often occurs when layers get out of sync
131 (e.g. <filename>oe-core</filename> bumps a
132 recipe version and the old recipe no longer exists and the
133 other layer has not been updated to the new version
134 of the recipe yet).
135 </para>
136
137 <para>
138 The default fatal behavior is safest because it is
139 the sane reaction given something is out of sync.
140 It is important to realize when your changes are no longer
141 being applied.
142 </para>
143 </glossdef>
144 </glossentry>
145
146 <glossentry id='var-BB_DEFAULT_TASK'><glossterm>BB_DEFAULT_TASK</glossterm>
147 <glossdef>
148 <para>
149 The default task to use when none is specified (e.g.
150 with the <filename>-c</filename> command line option).
151 The task name specified should not include the
152 <filename>do_</filename> prefix.
153 </para>
154 </glossdef>
155 </glossentry>
156
157 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
158 <glossdef>
159 <para>
160 Monitors disk space and available inodes during the build
161 and allows you to control the build based on these
162 parameters.
163 </para>
164
165 <para>
166 Disk space monitoring is disabled by default.
167 When setting this variable, use the following form:
168 <literallayout class='monospaced'>
169 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
170
171 where:
172
173 &lt;action&gt; is:
174 ABORT: Immediately abort the build when
175 a threshold is broken.
176 STOPTASKS: Stop the build after the currently
177 executing tasks have finished when
178 a threshold is broken.
179 WARN: Issue a warning but continue the
180 build when a threshold is broken.
181 Subsequent warnings are issued as
182 defined by the
183 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
184 which must be defined.
185
186 &lt;dir&gt; is:
187 Any directory you choose. You can specify one or
188 more directories to monitor by separating the
189 groupings with a space. If two directories are
190 on the same device, only the first directory
191 is monitored.
192
193 &lt;threshold&gt; is:
194 Either the minimum available disk space,
195 the minimum number of free inodes, or
196 both. You must specify at least one. To
197 omit one or the other, simply omit the value.
198 Specify the threshold using G, M, K for Gbytes,
199 Mbytes, and Kbytes, respectively. If you do
200 not specify G, M, or K, Kbytes is assumed by
201 default. Do not use GB, MB, or KB.
202 </literallayout>
203 </para>
204
205 <para>
206 Here are some examples:
207 <literallayout class='monospaced'>
208 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
209 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
210 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
211 </literallayout>
212 The first example works only if you also set
213 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable.
214 This example causes the build system to immediately
215 abort when either the disk space in <filename>${TMPDIR}</filename> drops
216 below 1 Gbyte or the available free inodes drops below
217 100 Kbytes.
218 Because two directories are provided with the variable, the
219 build system also issues a
220 warning when the disk space in the
221 <filename>${SSTATE_DIR}</filename> directory drops
222 below 1 Gbyte or the number of free inodes drops
223 below 100 Kbytes.
224 Subsequent warnings are issued during intervals as
225 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
226 variable.
227 </para>
228
229 <para>
230 The second example stops the build after all currently
231 executing tasks complete when the minimum disk space
232 in the <filename>${TMPDIR}</filename>
233 directory drops below 1 Gbyte.
234 No disk monitoring occurs for the free inodes in this case.
235 </para>
236
237 <para>
238 The final example immediately aborts the build when the
239 number of free inodes in the <filename>${TMPDIR}</filename> directory
240 drops below 100 Kbytes.
241 No disk space monitoring for the directory itself occurs
242 in this case.
243 </para>
244 </glossdef>
245 </glossentry>
246
247 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
248 <glossdef>
249 <para>
250 Defines the disk space and free inode warning intervals.
251 </para>
252
253 <para>
254 If you are going to use the
255 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
256 also use the
257 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
258 and define its action as "WARN".
259 During the build, subsequent warnings are issued each time
260 disk space or number of free inodes further reduces by
261 the respective interval.
262 </para>
263
264 <para>
265 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
266 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
267 the "WARN" action, the disk monitoring interval defaults to
268 the following:
269 <literallayout class='monospaced'>
270 BB_DISKMON_WARNINTERVAL = "50M,5K"
271 </literallayout>
272 </para>
273
274 <para>
275 When specifying the variable in your configuration file,
276 use the following form:
277 <literallayout class='monospaced'>
278 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
279
280 where:
281
282 &lt;disk_space_interval&gt; is:
283 An interval of memory expressed in either
284 G, M, or K for Gbytes, Mbytes, or Kbytes,
285 respectively. You cannot use GB, MB, or KB.
286
287 &lt;disk_inode_interval&gt; is:
288 An interval of free inodes expressed in either
289 G, M, or K for Gbytes, Mbytes, or Kbytes,
290 respectively. You cannot use GB, MB, or KB.
291 </literallayout>
292 </para>
293
294 <para>
295 Here is an example:
296 <literallayout class='monospaced'>
297 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
298 BB_DISKMON_WARNINTERVAL = "50M,5K"
299 </literallayout>
300 These variables cause BitBake to
301 issue subsequent warnings each time the available
302 disk space further reduces by 50 Mbytes or the number
303 of free inodes further reduces by 5 Kbytes in the
304 <filename>${SSTATE_DIR}</filename> directory.
305 Subsequent warnings based on the interval occur each time
306 a respective interval is reached beyond the initial warning
307 (i.e. 1 Gbytes and 100 Kbytes).
308 </para>
309 </glossdef>
310 </glossentry>
311
312 <glossentry id='var-BB_ENV_WHITELIST'><glossterm>BB_ENV_WHITELIST</glossterm>
313 <glossdef>
314 <para>
315 Specifies the internal whitelist of variables to allow
316 through from the external environment into BitBake's
317 datastore.
318 If the value of this variable is not specified
319 (which is the default), the following list is used:
320 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>,
321 <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>,
322 <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>,
323 and
324 <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>.
325 <note>
326 You must set this variable in the external environment
327 in order for it to work.
328 </note>
329 </para>
330 </glossdef>
331 </glossentry>
332
333 <glossentry id='var-BB_ENV_EXTRAWHITE'><glossterm>BB_ENV_EXTRAWHITE</glossterm>
334 <glossdef>
335 <para>
336 Specifies an additional set of variables to allow through
337 (whitelist) from the external environment into BitBake's
338 datastore.
339 This list of variables are on top of the internal list
340 set in
341 <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>.
342 <note>
343 You must set this variable in the external
344 environment in order for it to work.
345 </note>
346 </para>
347 </glossdef>
348 </glossentry>
349
350 <glossentry id='var-BB_FETCH_PREMIRRORONLY'><glossterm>BB_FETCH_PREMIRRORONLY</glossterm>
351 <glossdef>
352 <para>
353 When set to "1", causes BitBake's fetcher module to only
354 search
355 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
356 for files.
357 BitBake will not search the main
358 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
359 or
360 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>.
361 </para>
362 </glossdef>
363 </glossentry>
364
365 <glossentry id='var-BB_FILENAME'><glossterm>BB_FILENAME</glossterm>
366 <glossdef>
367 <para>
368 Contains the filename of the recipe that owns the currently
369 running task.
370 For example, if the <filename>do_fetch</filename> task that
371 resides in the <filename>my-recipe.bb</filename> is
372 executing, the <filename>BB_FILENAME</filename> variable
373 contains "/foo/path/my-recipe.bb".
374 </para>
375 </glossdef>
376 </glossentry>
377
378 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
379 <glossdef>
380 <para>
381 Causes tarballs of the Git repositories, including the
382 Git metadata, to be placed in the
383 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
384 directory.
385 Anyone wishing to create a source mirror would want to
386 enable this variable.
387 </para>
388
389 <para>
390 For performance reasons, creating and placing tarballs of
391 the Git repositories is not the default action by BitBake.
392 <literallayout class='monospaced'>
393 BB_GENERATE_MIRROR_TARBALLS = "1"
394 </literallayout>
395 </para>
396 </glossdef>
397 </glossentry>
398
399 <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm>
400 <glossdef>
401 <para>
402 Lists variables that are excluded from base configuration
403 checksum, which is used to determine if the cache can
404 be reused.
405 </para>
406
407 <para>
408 One of the ways BitBake determines whether to re-parse the
409 main metadata is through checksums of the variables in the
410 datastore of the base configuration data.
411 There are variables that you typically want to exclude when
412 checking whether or not to re-parse and thus rebuild the
413 cache.
414 As an example, you would usually exclude
415 <filename>TIME</filename> and <filename>DATE</filename>
416 because these variables are always changing.
417 If you did not exclude them, BitBake would never reuse the
418 cache.
419 </para>
420 </glossdef>
421 </glossentry>
422
423 <glossentry id='var-BB_HASHBASE_WHITELIST'><glossterm>BB_HASHBASE_WHITELIST</glossterm>
424 <glossdef>
425 <para>
426 Lists variables that are excluded from checksum and
427 dependency data.
428 Variables that are excluded can therefore change without
429 affecting the checksum mechanism.
430 A common example would be the variable for the path of
431 the build.
432 BitBake's output should not (and usually does not) depend
433 on the directory in which it was built.
434 </para>
435 </glossdef>
436 </glossentry>
437
438 <glossentry id='var-BB_HASHCHECK_FUNCTION'><glossterm>BB_HASHCHECK_FUNCTION</glossterm>
439 <glossdef>
440 <para>
441 Specifies the name of the function to call during the
442 "setscene" part of the task's execution in order to
443 validate the list of task hashes.
444 The function returns the list of setscene tasks that should
445 be executed.
446 </para>
447
448 <para>
449 At this point in the execution of the code, the objective
450 is to quickly verify if a given setscene function is likely
451 to work or not.
452 It's easier to check the list of setscene functions in
453 one pass than to call many individual tasks.
454 The returned list need not be completely accurate.
455 A given setscene task can still later fail.
456 However, the more accurate the data returned, the more
457 efficient the build will be.
458 </para>
459 </glossdef>
460 </glossentry>
461
462 <glossentry id='var-BB_INVALIDCONF'><glossterm>BB_INVALIDCONF</glossterm>
463 <glossdef>
464 <para>
465 Used in combination with the
466 <filename>ConfigParsed</filename> event to trigger
467 re-parsing the base metadata (i.e. all the
468 recipes).
469 The <filename>ConfigParsed</filename> event can set the
470 variable to trigger the re-parse.
471 You must be careful to avoid recursive loops with this
472 functionality.
473 </para>
474 </glossdef>
475 </glossentry>
476
477 <glossentry id='var-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
478 <glossdef>
479 <para>
480 Specifies the name of the log files saved into
481 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
482 By default, the <filename>BB_LOGFMT</filename> variable
483 is undefined and the log file names get created using the
484 following form:
485 <literallayout class='monospaced'>
486 log.{task}.{pid}
487 </literallayout>
488 If you want to force log files to take a specific name,
489 you can set this variable in a configuration file.
490 </para>
491 </glossdef>
492 </glossentry>
493
494 <glossentry id='var-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm>
495 <glossdef>
496 <para>
497 Allows BitBake to run at a specific priority
498 (i.e. nice level).
499 System permissions usually mean that BitBake can reduce its
500 priority but not raise it again.
501 See
502 <link linkend='var-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link>
503 for additional information.
504 </para>
505 </glossdef>
506 </glossentry>
507
508 <glossentry id='var-BB_NO_NETWORK'><glossterm>BB_NO_NETWORK</glossterm>
509 <glossdef>
510 <para>
511 Disables network access in the BitBake fetcher modules.
512 With this access disabled, any command that attempts to
513 access the network becomes an error.
514 </para>
515
516 <para>
517 Disabling network access is useful for testing source
518 mirrors, running builds when not connected to the Internet,
519 and when operating in certain kinds of firewall
520 environments.
521 </para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
526 <glossdef>
527 <para>
528 The maximum number of tasks BitBake should run in parallel
529 at any one time.
530 If your host development system supports multiple cores,
531 a good rule of thumb is to set this variable to twice the
532 number of cores.
533 </para>
534 </glossdef>
535 </glossentry>
536
537 <glossentry id='var-BB_NUMBER_PARSE_THREADS'><glossterm>BB_NUMBER_PARSE_THREADS</glossterm>
538 <glossdef>
539 <para>
540 Sets the number of threads BitBake uses when parsing.
541 By default, the number of threads is equal to the number
542 of cores on the system.
543 </para>
544 </glossdef>
545 </glossentry>
546
547 <glossentry id='var-BB_ORIGENV'><glossterm>BB_ORIGENV</glossterm>
548 <glossdef>
549 <para>
550 Contains a copy of the original external environment in
551 which BitBake was run.
552 The copy is taken before any whitelisted variable values
553 are filtered into BitBake's datastore.
554 <note>
555 The contents of this variable is a datastore object
556 that can be queried using the normal datastore
557 operations.
558 </note>
559 </para>
560 </glossdef>
561 </glossentry>
562
563 <glossentry id='var-BB_PRESERVE_ENV'><glossterm>BB_PRESERVE_ENV</glossterm>
564 <glossdef>
565 <para>
566 Disables whitelisting and instead allows all variables
567 through from the external environment into BitBake's
568 datastore.
569 <note>
570 You must set this variable in the external
571 environment in order for it to work.
572 </note>
573 </para>
574 </glossdef>
575 </glossentry>
576
577 <glossentry id='var-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm>
578 <glossdef>
579 <para>
580 Specifies the name of the executable script files
581 (i.e. run files) saved into
582 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
583 By default, the <filename>BB_RUNFMT</filename> variable
584 is undefined and the run file names get created using the
585 following form:
586 <literallayout class='monospaced'>
587 run.{task}.{pid}
588 </literallayout>
589 If you want to force run files to take a specific name,
590 you can set this variable in a configuration file.
591 </para>
592 </glossdef>
593 </glossentry>
594
595 <glossentry id='var-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm>
596 <glossdef>
597 <para>
598 Contains the name of the currently executing task.
599 The value does not include the "do_" prefix.
600 For example, if the currently executing task is
601 <filename>do_config</filename>, the value is
602 "config".
603 </para>
604 </glossdef>
605 </glossentry>
606
607 <glossentry id='var-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm>
608 <glossdef>
609 <para>
610 Selects the name of the scheduler to use for the
611 scheduling of BitBake tasks.
612 Three options exist:
613 <itemizedlist>
614 <listitem><para><emphasis>basic</emphasis> -
615 The basic framework from which everything derives.
616 Using this option causes tasks to be ordered
617 numerically as they are parsed.
618 </para></listitem>
619 <listitem><para><emphasis>speed</emphasis> -
620 Executes tasks first that have more tasks
621 depending on them.
622 The "speed" option is the default.
623 </para></listitem>
624 <listitem><para><emphasis>completion</emphasis> -
625 Causes the scheduler to try to complete a given
626 recipe once its build has started.
627 </para></listitem>
628 </itemizedlist>
629 </para>
630 </glossdef>
631 </glossentry>
632
633 <glossentry id='var-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm>
634 <glossdef>
635 <para>
636 Defines custom schedulers to import.
637 Custom schedulers need to be derived from the
638 <filename>RunQueueScheduler</filename> class.
639 </para>
640
641 <para>
642 For information how to select a scheduler, see the
643 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
644 variable.
645 </para>
646 </glossdef>
647 </glossentry>
648
649 <glossentry id='var-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm>
650 <glossdef>
651 <para>
652 Specifies a function BitBake calls that determines
653 whether BitBake requires a setscene dependency to be met.
654 </para>
655
656 <para>
657 When running a setscene task, BitBake needs to
658 know which dependencies of that setscene task also need
659 to be run.
660 Whether dependencies also need to be run is highly
661 dependent on the metadata.
662 The function specified by this variable returns a
663 "True" or "False" depending on whether the dependency needs
664 to be met.
665 </para>
666 </glossdef>
667 </glossentry>
668
669 <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION'><glossterm>BB_SETSCENE_VERIFY_FUNCTION</glossterm>
670 <glossdef>
671 <para>
672 Specifies a function to call that verifies the list of
673 planned task execution before the main task execution
674 happens.
675 The function is called once BitBake has a list of setscene
676 tasks that have run and either succeeded or failed.
677 </para>
678
679 <para>
680 The function allows for a task list check to see if they
681 make sense.
682 Even if BitBake was planning to skip a task, the
683 returned value of the function can force BitBake to run
684 the task, which is necessary under certain metadata
685 defined circumstances.
686 </para>
687 </glossdef>
688 </glossentry>
689
690 <glossentry id='var-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm>
691 <glossdef>
692 <para>
693 Lists variable flags (varflags)
694 that can be safely excluded from checksum
695 and dependency data for keys in the datastore.
696 When generating checksum or dependency data for keys in the
697 datastore, the flags set against that key are normally
698 included in the checksum.
699 </para>
700
701 <para>
702 For more information on varflags, see the
703 "<link linkend='variable-flags'>Variable Flags</link>"
704 section.
705 </para>
706 </glossdef>
707 </glossentry>
708
709 <glossentry id='var-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm>
710 <glossdef>
711 <para>
712 Defines the name of the signature handler BitBake uses.
713 The signature handler defines the way stamp files are
714 created and handled, if and how the signature is
715 incorporated into the stamps, and how the signature
716 itself is generated.
717 </para>
718
719 <para>
720 A new signature handler can be added by injecting a class
721 derived from the
722 <filename>SignatureGenerator</filename> class into the
723 global namespace.
724 </para>
725 </glossdef>
726 </glossentry>
727
728 <glossentry id='var-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm>
729 <glossdef>
730 <para>
731 Defines the behavior of the fetcher when it interacts with
732 source control systems and dynamic source revisions.
733 The <filename>BB_SRCREV_POLICY</filename> variable is
734 useful when working without a network.
735 </para>
736
737 <para>
738 The variable can be set using one of two policies:
739 <itemizedlist>
740 <listitem><para><emphasis>cache</emphasis> -
741 Retains the value the system obtained previously
742 rather than querying the source control system
743 each time.
744 </para></listitem>
745 <listitem><para><emphasis>clear</emphasis> -
746 Queries the source controls system every time.
747 With this policy, there is no cache.
748 The "clear" policy is the default.
749 </para></listitem>
750 </itemizedlist>
751 </para>
752 </glossdef>
753 </glossentry>
754
755 <glossentry id='var-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm>
756 <glossdef>
757 <para>
758 Defines the mode used for how timestamps of stamp files
759 are compared.
760 You can set the variable to one of the following modes:
761 <itemizedlist>
762 <listitem><para><emphasis>perfile</emphasis> -
763 Timestamp comparisons are only made
764 between timestamps of a specific recipe.
765 This is the default mode.
766 </para></listitem>
767 <listitem><para><emphasis>full</emphasis> -
768 Timestamp comparisons are made for all
769 dependencies.
770 </para></listitem>
771 <listitem><para><emphasis>whitelist</emphasis> -
772 Identical to "full" mode except timestamp
773 comparisons are made for recipes listed in the
774 <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>
775 variable.
776 </para></listitem>
777 </itemizedlist>
778 <note>
779 Stamp policies are largely obsolete with the
780 introduction of setscene tasks.
781 </note>
782 </para>
783 </glossdef>
784 </glossentry>
785
786 <glossentry id='var-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm>
787 <glossdef>
788 <para>
789 Lists files whose stamp file timestamps are compared when
790 the stamp policy mode is set to "whitelist".
791 For information on stamp policies, see the
792 <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>
793 variable.
794 </para>
795 </glossdef>
796 </glossentry>
797
798 <glossentry id='var-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm>
799 <glossdef>
800 <para>
801 Sets a more strict checksum mechanism for non-local URLs.
802 Setting this variable to a value causes BitBake
803 to report an error if it encounters a non-local URL
804 that does not have at least one checksum specified.
805 </para>
806 </glossdef>
807 </glossentry>
808
809 <glossentry id='var-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm>
810 <glossdef>
811 <para>
812 Allows specific tasks to change their priority
813 (i.e. nice level).
814 </para>
815
816 <para>
817 You can use this variable in combination with task
818 overrides to raise or lower priorities of specific tasks.
819 For example, on the
820 <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>
821 autobuilder, QEMU emulation in images is given a higher
822 priority as compared to build tasks to ensure that images
823 do not suffer timeouts on loaded systems.
824 </para>
825 </glossdef>
826 </glossentry>
827
828 <glossentry id='var-BB_TASKHASH'><glossterm>BB_TASKHASH</glossterm>
829 <glossdef>
830 <para>
831 Within an executing task, this variable holds the hash
832 of the task as returned by the currently enabled
833 signature generator.
834 </para>
835 </glossdef>
836 </glossentry>
837
838 <glossentry id='var-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm>
839 <glossdef>
840 <para>
841 Controls how verbose BitBake is during builds.
842 If set, shell scripts echo commands and shell script output
843 appears on standard out (stdout).
844 </para>
845 </glossdef>
846 </glossentry>
847
848 <glossentry id='var-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm>
849 <glossdef>
850 <para>
851 Specifies if the current context is executing a task.
852 BitBake sets this variable to "1" when a task is
853 being executed.
854 The value is not set when the task is in server context
855 during parsing or event handling.
856 </para>
857 </glossdef>
858 </glossentry>
859
860
861 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
862 <glossdef>
863 <para>
864 Allows you to extend a recipe so that it builds variants
865 of the software.
866 Some examples of these variants for recipes from the
867 OpenEmbedded Core metadata are "natives" such as
868 <filename>quilt-native</filename>, which is a copy of
869 Quilt built to run on the build system; "crosses" such
870 as <filename>gcc-cross</filename>, which is a compiler
871 built to run on the build machine but produces binaries
872 that run on the target <filename>MACHINE</filename>;
873 "nativesdk", which targets the SDK machine instead of
874 <filename>MACHINE</filename>; and "mulitlibs" in the form
875 "<filename>multilib:&lt;multilib_name&gt;</filename>".
876 </para>
877
878 <para>
879 To build a different variant of the recipe with a minimal
880 amount of code, it usually is as simple as adding the
881 variable to your recipe.
882 Here are two examples.
883 The "native" variants are from the OpenEmbedded Core
884 metadata:
885 <literallayout class='monospaced'>
886 BBCLASSEXTEND =+ "native nativesdk"
887 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
888 </literallayout>
889 </para>
890 </glossdef>
891 </glossentry>
892
893 <glossentry id='var-BBDEBUG'><glossterm>BBDEBUG</glossterm>
894 <glossdef>
895 <para>
896 Sets the BitBake debug output level to a specific value
897 as incremented by the <filename>-d</filename> command line
898 option.
899 <note>
900 You must set this variable in the external environment
901 in order for it to work.
902 </note>
903 </para>
904 </glossdef>
905 </glossentry>
906
907 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
908 <glossdef>
909 <para>Lists the names of configured layers.
910 These names are used to find the other <filename>BBFILE_*</filename>
911 variables.
912 Typically, each layer appends its name to this variable in its
913 <filename>conf/layer.conf</filename> file.
914 </para>
915 </glossdef>
916 </glossentry>
917
918 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
919 <glossdef>
920 <para>Variable that expands to match files from
921 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
922 in a particular layer.
923 This variable is used in the <filename>conf/layer.conf</filename> file and must
924 be suffixed with the name of the specific layer (e.g.
925 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
926 </glossdef>
927 </glossentry>
928
929 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
930 <glossdef>
931 <para>Assigns the priority for recipe files in each layer.</para>
932 <para>This variable is useful in situations where the same recipe appears in
933 more than one layer.
934 Setting this variable allows you to prioritize a
935 layer against other layers that contain the same recipe - effectively
936 letting you control the precedence for the multiple layers.
937 The precedence established through this variable stands regardless of a
938 recipe's version
939 (<link linkend='var-PV'><filename>PV</filename></link> variable).
940 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
941 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
942 lower precedence.</para>
943 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
944 precedence.
945 For example, the value 6 has a higher precedence than the value 5.
946 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
947 dependencies (see the
948 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
949 more information.
950 The default priority, if unspecified
951 for a layer with no dependencies, is the lowest defined priority + 1
952 (or 1 if no priorities are defined).</para>
953 <tip>
954 You can use the command <filename>bitbake-layers show-layers</filename> to list
955 all configured layers along with their priorities.
956 </tip>
957 </glossdef>
958 </glossentry>
959
960 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
961 <glossdef>
962 <para>List of recipe files BitBake uses to build software.</para>
963 </glossdef>
964 </glossentry>
965
966 <glossentry id='var-BBINCLUDED'><glossterm>BBINCLUDED</glossterm>
967 <glossdef>
968 <para>
969 Contains a space-separated list of all of all files that
970 BitBake's parser included during parsing of the current
971 file.
972 </para>
973 </glossdef>
974 </glossentry>
975
976 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
977 <glossdef>
978 <para>
979 If set to a value, enables printing the task log when
980 reporting a failed task.
981 </para>
982 </glossdef>
983 </glossentry>
984
985 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
986 <glossdef>
987 <para>
988 If
989 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
990 is set, specifies the maximum number of lines from the
991 task log file to print when reporting a failed task.
992 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
993 the entire log is printed.
994 </para>
995 </glossdef>
996 </glossentry>
997
998 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
999 <glossdef>
1000 <para>Lists the layers to enable during the build.
1001 This variable is defined in the <filename>bblayers.conf</filename> configuration
1002 file in the build directory.
1003 Here is an example:
1004 <literallayout class='monospaced'>
1005 BBLAYERS = " \
1006 /home/scottrif/poky/meta \
1007 /home/scottrif/poky/meta-yocto \
1008 /home/scottrif/poky/meta-yocto-bsp \
1009 /home/scottrif/poky/meta-mykernel \
1010 "
1011
1012 </literallayout>
1013 This example enables four layers, one of which is a custom, user-defined layer
1014 named <filename>meta-mykernel</filename>.
1015 </para>
1016 </glossdef>
1017 </glossentry>
1018
1019 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1020 <glossdef>
1021 <para>
1022 Prevents BitBake from processing recipes and recipe
1023 append files.
1024 </para>
1025
1026 <para>
1027 You can use the <filename>BBMASK</filename> variable
1028 to "hide" these <filename>.bb</filename> and
1029 <filename>.bbappend</filename> files.
1030 BitBake ignores any recipe or recipe append files that
1031 match the expression.
1032 It is as if BitBake does not see them at all.
1033 Consequently, matching files are not parsed or otherwise
1034 used by BitBake.</para>
1035 <para>
1036 The value you provide is passed to Python's regular
1037 expression compiler.
1038 The expression is compared against the full paths to
1039 the files.
1040 For complete syntax information, see Python's
1041 documentation at
1042 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
1043 </para>
1044
1045 <para>
1046 The following example uses a complete regular expression
1047 to tell BitBake to ignore all recipe and recipe append
1048 files in the <filename>meta-ti/recipes-misc/</filename>
1049 directory:
1050 <literallayout class='monospaced'>
1051 BBMASK = "meta-ti/recipes-misc/"
1052 </literallayout>
1053 If you want to mask out multiple directories or recipes,
1054 use the vertical bar to separate the regular expression
1055 fragments.
1056 This next example masks out multiple directories and
1057 individual recipes:
1058 <literallayout class='monospaced'>
1059 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
1060 BBMASK .= "|.*meta-oe/recipes-support/"
1061 BBMASK .= "|.*openldap"
1062 BBMASK .= "|.*opencv"
1063 BBMASK .= "|.*lzma"
1064 </literallayout>
1065 Notice how the vertical bar is used to append the fragments.
1066 <note>
1067 When specifying a directory name, use the trailing
1068 slash character to ensure you match just that directory
1069 name.
1070 </note>
1071 </para>
1072 </glossdef>
1073 </glossentry>
1074
1075 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1076 <glossdef>
1077 <para>
1078 Used by BitBake to locate class
1079 (<filename>.bbclass</filename>) and configuration
1080 (<filename>.conf</filename>) files.
1081 This variable is analogous to the
1082 <filename>PATH</filename> variable.
1083 </para>
1084
1085 <para>
1086 If you run BitBake from a directory outside of the
1087 build directory,
1088 you must be sure to set
1089 <filename>BBPATH</filename> to point to the
1090 build directory.
1091 Set the variable as you would any environment variable
1092 and then run BitBake:
1093 <literallayout class='monospaced'>
1094 $ BBPATH="&lt;build_directory&gt;"
1095 $ export BBPATH
1096 $ bitbake &lt;target&gt;
1097 </literallayout>
1098 </para>
1099 </glossdef>
1100 </glossentry>
1101
1102 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1103 <glossdef>
1104 <para>
1105 Points to the server that runs memory-resident BitBake.
1106 The variable is only used when you employ memory-resident
1107 BitBake.
1108 </para>
1109 </glossdef>
1110 </glossentry>
1111
1112 <glossentry id='var-BBVERSIONS'><glossterm>BBVERSIONS</glossterm>
1113 <glossdef>
1114 <para>
1115 Allows a single recipe to build multiple versions of a
1116 project from a single recipe file.
1117 You also able to specify conditional metadata
1118 using the
1119 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1120 mechanism for a single version or for an optionally named
1121 range of versions.
1122 </para>
1123
1124 <para>
1125 For more information on <filename>BBVERSIONS</filename>,
1126 see the
1127 "<link linkend='variants-class-extension-mechanism'>Variants - Class Extension Mechanism</link>"
1128 section.
1129 </para>
1130 </glossdef>
1131 </glossentry>
1132
1133 <glossentry id='var-BITBAKE_UI'><glossterm>BITBAKE_UI</glossterm>
1134 <glossdef>
1135 <para>
1136 Used to specify the UI module to use when running BitBake.
1137 Using this variable is equivalent to using the
1138 <filename>-u</filename> command-line option.
1139 <note>
1140 You must set this variable in the external environment
1141 in order for it to work.
1142 </note>
1143 </para>
1144 </glossdef>
1145 </glossentry>
1146
1147 <glossentry id='var-BUILDNAME'><glossterm>BUILDNAME</glossterm>
1148 <glossdef>
1149 <para>
1150 A name assigned to the build.
1151 The name defaults to a datetime stamp of when the build was
1152 started but can be defined by the metadata.
1153 </para>
1154 </glossdef>
1155 </glossentry>
1156
1157 </glossdiv>
1158
1159 <glossdiv id='var-glossary-c'><title>C</title>
1160
1161 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
1162 <glossdef>
1163 <para>
1164 Specifies the directory BitBake uses to store a cache
1165 of the metadata so it does not need to be parsed every
1166 time BitBake is started.
1167 </para>
1168 </glossdef>
1169 </glossentry>
1170
1171 </glossdiv>
1172
1173 <glossdiv id='var-glossary-d'><title>D</title>
1174
1175 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1176 <glossdef>
1177 <para>
1178 Specifies a weak bias for recipe selection priority.
1179 </para>
1180 <para>
1181 The most common usage of this is variable is to set
1182 it to "-1" within a recipe for a development version of a
1183 piece of software.
1184 Using the variable in this way causes the stable version
1185 of the recipe to build by default in the absence of
1186 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1187 being used to build the development version.
1188 </para>
1189 <note>
1190 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1191 is weak and is overridden by
1192 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1193 if that variable is different between two layers
1194 that contain different versions of the same recipe.
1195 </note>
1196 </glossdef>
1197 </glossentry>
1198
1199 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1200 <glossdef>
1201 <para>
1202 Lists a recipe's build-time dependencies
1203 (i.e. other recipe files).
1204 </para>
1205
1206 <para>
1207 Consider this simple example for two recipes named "a" and
1208 "b" that produce similarly named packages.
1209 In this example, the <filename>DEPENDS</filename>
1210 statement appears in the "a" recipe:
1211 <literallayout class='monospaced'>
1212 DEPENDS = "b"
1213 </literallayout>
1214 Here, the dependency is such that the
1215 <filename>do_configure</filename> task for recipe "a"
1216 depends on the <filename>do_populate_sysroot</filename>
1217 task of recipe "b".
1218 This means anything that recipe "b" puts into sysroot
1219 is available when recipe "a" is configuring itself.
1220 </para>
1221
1222 <para>
1223 For information on runtime dependencies, see the
1224 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1225 variable.
1226 </para>
1227 </glossdef>
1228 </glossentry>
1229
1230 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1231 <glossdef>
1232 <para>
1233 A long description for the recipe.
1234 </para>
1235 </glossdef>
1236 </glossentry>
1237
1238 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1239 <glossdef>
1240 <para>
1241 The central download directory used by the build process to
1242 store downloads.
1243 By default, <filename>DL_DIR</filename> gets files
1244 suitable for mirroring for everything except Git
1245 repositories.
1246 If you want tarballs of Git repositories, use the
1247 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1248 variable.
1249 </para>
1250 </glossdef>
1251
1252 </glossentry>
1253 </glossdiv>
1254
1255 <glossdiv id='var-glossary-e'><title>E</title>
1256
1257 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1258 <glossdef>
1259 <para>
1260 Directs BitBake to exclude a recipe from world builds (i.e.
1261 <filename>bitbake world</filename>).
1262 During world builds, BitBake locates, parses and builds all
1263 recipes found in every layer exposed in the
1264 <filename>bblayers.conf</filename> configuration file.
1265 </para>
1266
1267 <para>
1268 To exclude a recipe from a world build using this variable,
1269 set the variable to "1" in the recipe.
1270 </para>
1271
1272 <note>
1273 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1274 may still be built during a world build in order to satisfy
1275 dependencies of other recipes.
1276 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1277 only ensures that the recipe is not explicitly added
1278 to the list of build targets in a world build.
1279 </note>
1280 </glossdef>
1281 </glossentry>
1282
1283 </glossdiv>
1284
1285 <glossdiv id='var-glossary-f'><title>F</title>
1286
1287 <glossentry id='var-FAKEROOT'><glossterm>FAKEROOT</glossterm>
1288 <glossdef>
1289 <para>
1290 Contains the command to use when running a shell script
1291 in a fakeroot environment.
1292 The <filename>FAKEROOT</filename> variable is obsolete
1293 and has been replaced by the other
1294 <filename>FAKEROOT*</filename> variables.
1295 See these entries in the glossary for more information.
1296 </para>
1297 </glossdef>
1298 </glossentry>
1299
1300 <glossentry id='var-FAKEROOTBASEENV'><glossterm>FAKEROOTBASEENV</glossterm>
1301 <glossdef>
1302 <para>
1303 Lists environment variables to set when executing
1304 the command defined by
1305 <link linkend='var-FAKEROOTCMD'><filename>FAKEROOTCMD</filename></link>
1306 that starts the bitbake-worker process
1307 in the fakeroot environment.
1308 </para>
1309 </glossdef>
1310 </glossentry>
1311
1312 <glossentry id='var-FAKEROOTCMD'><glossterm>FAKEROOTCMD</glossterm>
1313 <glossdef>
1314 <para>
1315 Contains the command that starts the bitbake-worker
1316 process in the fakeroot environment.
1317 </para>
1318 </glossdef>
1319 </glossentry>
1320
1321 <glossentry id='var-FAKEROOTDIRS'><glossterm>FAKEROOTDIRS</glossterm>
1322 <glossdef>
1323 <para>
1324 Lists directories to create before running a task in
1325 the fakeroot environment.
1326 </para>
1327 </glossdef>
1328 </glossentry>
1329
1330 <glossentry id='var-FAKEROOTENV'><glossterm>FAKEROOTENV</glossterm>
1331 <glossdef>
1332 <para>
1333 Lists environment variables to set when running a task
1334 in the fakeroot environment.
1335 For additional information on environment variables and
1336 the fakeroot environment, see the
1337 <link linkend='var-FAKEROOTBASEENV'><filename>FAKEROOTBASEENV</filename></link>
1338 variable.
1339 </para>
1340 </glossdef>
1341 </glossentry>
1342
1343 <glossentry id='var-FAKEROOTNOENV'><glossterm>FAKEROOTNOENV</glossterm>
1344 <glossdef>
1345 <para>
1346 Lists environment variables to set when running a task
1347 that is not in the fakeroot environment.
1348 For additional information on environment variables and
1349 the fakeroot environment, see the
1350 <link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
1351 variable.
1352 </para>
1353 </glossdef>
1354 </glossentry>
1355
1356 <glossentry id='var-FETCHCMD'><glossterm>FETCHCMD</glossterm>
1357 <glossdef>
1358 <para>
1359 Defines the command the BitBake fetcher module
1360 executes when running fetch operations.
1361 You need to use an override suffix when you use the
1362 variable (e.g. <filename>FETCHCMD_git</filename>
1363 or <filename>FETCHCMD_svn</filename>).
1364 </para>
1365 </glossdef>
1366 </glossentry>
1367
1368 <glossentry id='var-FILE'><glossterm>FILE</glossterm>
1369 <glossdef>
1370 <para>
1371 Points at the current file.
1372 BitBake sets this variable during the parsing process
1373 to identify the file being parsed.
1374 BitBake also sets this variable when a recipe is being
1375 executed to identify the recipe file.
1376 </para>
1377 </glossdef>
1378 </glossentry>
1379
1380 <glossentry id='var-FILESDIR'><glossterm>FILESDIR</glossterm>
1381 <glossdef>
1382 <para>
1383 Specifies directories BitBake uses when searching for
1384 patches and files.
1385 The "local" fetcher module uses these directories when
1386 handling <filename>file://</filename> URLs if the file
1387 was not found using
1388 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
1389 <note>
1390 The <filename>FILESDIR</filename> variable is
1391 deprecated and you should use
1392 <filename>FILESPATH</filename> in all new code.
1393 </note>
1394 </para>
1395 </glossdef>
1396 </glossentry>
1397
1398 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1399 <glossdef>
1400 <para>
1401 Specifies directories BitBake uses when searching for
1402 patches and files.
1403 The "local" fetcher module uses these directories when
1404 handling <filename>file://</filename> URLs.
1405 The variable behaves like a shell <filename>PATH</filename>
1406 environment variable.
1407 The value is a colon-separated list of directories that
1408 are searched left-to-right in order.
1409 </para>
1410 </glossdef>
1411 </glossentry>
1412
1413 </glossdiv>
1414
1415<!--
1416 <glossdiv id='var-glossary-g'><title>G</title>
1417 </glossdiv>
1418-->
1419
1420 <glossdiv id='var-glossary-h'><title>H</title>
1421
1422 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1423 <glossdef>
1424 <para>Website where more information about the software the recipe is building
1425 can be found.</para>
1426 </glossdef>
1427 </glossentry>
1428
1429 </glossdiv>
1430
1431 <glossdiv id='var-glossary-i'><title>I</title>
1432
1433 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
1434 <glossdef>
1435 <para>
1436 Causes the named class to be inherited at
1437 this point during parsing.
1438 The variable is only valid in configuration files.
1439 </para>
1440 </glossdef>
1441 </glossentry>
1442
1443 </glossdiv>
1444
1445<!--
1446 <glossdiv id='var-glossary-j'><title>J</title>
1447 </glossdiv>
1448
1449 <glossdiv id='var-glossary-k'><title>K</title>
1450 </glossdiv>
1451-->
1452
1453 <glossdiv id='var-glossary-l'><title>L</title>
1454
1455 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
1456 <glossdef>
1457 <para>Lists the layers, separated by spaces, upon which this recipe depends.
1458 Optionally, you can specify a specific layer version for a dependency
1459 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1460 to be compared against
1461 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
1462 in this case).
1463 BitBake produces an error if any dependency is missing or
1464 the version numbers do not match exactly (if specified).</para>
1465 <para>
1466 You use this variable in the <filename>conf/layer.conf</filename> file.
1467 You must also use the specific layer name as a suffix
1468 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1469 </glossdef>
1470 </glossentry>
1471
1472 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
1473 <glossdef>
1474 <para>When used inside the <filename>layer.conf</filename> configuration
1475 file, this variable provides the path of the current layer.
1476 This variable is not available outside of <filename>layer.conf</filename>
1477 and references are expanded immediately when parsing of the file completes.</para>
1478 </glossdef>
1479 </glossentry>
1480
1481 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
1482 <glossdef>
1483 <para>Optionally specifies the version of a layer as a single number.
1484 You can use this variable within
1485 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
1486 for another layer in order to depend on a specific version
1487 of the layer.</para>
1488 <para>
1489 You use this variable in the <filename>conf/layer.conf</filename> file.
1490 You must also use the specific layer name as a suffix
1491 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1492 </glossdef>
1493 </glossentry>
1494
1495 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
1496 <glossdef>
1497 <para>
1498 The list of source licenses for the recipe.
1499 </para>
1500 </glossdef>
1501 </glossentry>
1502
1503 </glossdiv>
1504
1505 <glossdiv id='var-glossary-m'><title>M</title>
1506
1507 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
1508 <glossdef>
1509 <para>
1510 Specifies additional paths from which BitBake gets source code.
1511 When the build system searches for source code, it first
1512 tries the local download directory.
1513 If that location fails, the build system tries locations
1514 defined by
1515 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
1516 the upstream source, and then locations specified by
1517 <filename>MIRRORS</filename> in that order.
1518 </para>
1519 </glossdef>
1520 </glossentry>
1521
1522 <glossentry id='var-MULTI_PROVIDER_WHITELIST'><glossterm>MULTI_PROVIDER_WHITELIST</glossterm>
1523 <glossdef>
1524 <para>
1525 Allows you to suppress BitBake warnings caused when
1526 building two separate recipes that provide the same
1527 output.
1528 </para>
1529
1530 <para>
1531 Bitbake normally issues a warning when building two
1532 different recipes where each provides the same output.
1533 This scenario is usually something the user does not
1534 want.
1535 However, cases do exist where it makes sense, particularly
1536 in the <filename>virtual/*</filename> namespace.
1537 You can use this variable to suppress BitBake's warnings.
1538 </para>
1539
1540 <para>
1541 To use the variable, list provider names (e.g.
1542 recipe names, <filename>virtual/kernel</filename>,
1543 and so forth).
1544 </para>
1545 </glossdef>
1546 </glossentry>
1547
1548 </glossdiv>
1549
1550<!--
1551 <glossdiv id='var-glossary-n'><title>N</title>
1552 </glossdiv>
1553-->
1554
1555 <glossdiv id='var-glossary-o'><title>O</title>
1556
1557 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
1558 <glossdef>
1559 <para>
1560 BitBake uses <filename>OVERRIDES</filename> to control
1561 what variables are overridden after BitBake parses
1562 recipes and configuration files.
1563 You can find more information on how overrides are handled
1564 in the
1565 "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
1566 section.
1567 </para>
1568 </glossdef>
1569 </glossentry>
1570 </glossdiv>
1571
1572 <glossdiv id='var-glossary-p'><title>P</title>
1573
1574 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
1575 <glossdef>
1576 <para>The list of packages the recipe creates.
1577 </para>
1578 </glossdef>
1579 </glossentry>
1580
1581 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
1582 <glossdef>
1583 <para>
1584 A promise that your recipe satisfies runtime dependencies
1585 for optional modules that are found in other recipes.
1586 <filename>PACKAGES_DYNAMIC</filename>
1587 does not actually satisfy the dependencies, it only states that
1588 they should be satisfied.
1589 For example, if a hard, runtime dependency
1590 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
1591 of another package is satisfied during the build
1592 through the <filename>PACKAGES_DYNAMIC</filename>
1593 variable, but a package with the module name is never actually
1594 produced, then the other package will be broken.
1595 </para>
1596 </glossdef>
1597 </glossentry>
1598
1599 <glossentry id='var-PE'><glossterm>PE</glossterm>
1600 <glossdef>
1601 <para>
1602 The epoch of the recipe.
1603 By default, this variable is unset.
1604 The variable is used to make upgrades possible when the
1605 versioning scheme changes in some backwards incompatible
1606 way.
1607 </para>
1608 </glossdef>
1609 </glossentry>
1610
1611 <glossentry id='var-PERSISTENT_DIR'><glossterm>PERSISTENT_DIR</glossterm>
1612 <glossdef>
1613 <para>
1614 Specifies the directory BitBake uses to store data that
1615 should be preserved between builds.
1616 In particular, the data stored is the data that uses
1617 BitBake's persistent data API and the data used by the
1618 PR Server and PR Service.
1619 </para>
1620 </glossdef>
1621 </glossentry>
1622
1623 <glossentry id='var-PF'><glossterm>PF</glossterm>
1624 <glossdef>
1625 <para>
1626 Specifies the recipe or package name and includes all version and revision
1627 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
1628 <filename>bash-4.2-r1/</filename>).
1629 </para>
1630 </glossdef>
1631 </glossentry>
1632
1633 <glossentry id='var-PN'><glossterm>PN</glossterm>
1634 <glossdef>
1635 <para>The recipe name.</para>
1636 </glossdef>
1637 </glossentry>
1638
1639 <glossentry id='var-PR'><glossterm>PR</glossterm>
1640 <glossdef>
1641 <para>The revision of the recipe.
1642 </para>
1643 </glossdef>
1644 </glossentry>
1645
1646 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
1647 <glossdef>
1648 <para>
1649 Determines which recipe should be given preference when
1650 multiple recipes provide the same item.
1651 You should always suffix the variable with the name of the
1652 provided item, and you should set it to the
1653 <link linkend='var-PN'><filename>PN</filename></link>
1654 of the recipe to which you want to give precedence.
1655 Some examples:
1656 <literallayout class='monospaced'>
1657 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1658 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1659 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1660 </literallayout>
1661 </para>
1662 </glossdef>
1663 </glossentry>
1664
1665 <glossentry id='var-PREFERRED_PROVIDERS'><glossterm>PREFERRED_PROVIDERS</glossterm>
1666 <glossdef>
1667 <para>
1668 Determines which recipe should be given preference for
1669 cases where multiple recipes provide the same item.
1670 Functionally,
1671 <filename>PREFERRED_PROVIDERS</filename> is identical to
1672 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>.
1673 However, the <filename>PREFERRED_PROVIDERS</filename>
1674 variable lets you define preferences for multiple
1675 situations using the following form:
1676 <literallayout class='monospaced'>
1677 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1678 </literallayout>
1679 This form is a convenient replacement for the following:
1680 <literallayout class='monospaced'>
1681 PREFERRED_PROVIDER_xxx = "yyy"
1682 PREFERRED_PROVIDER_aaa = "bbb"
1683 </literallayout>
1684 </para>
1685 </glossdef>
1686 </glossentry>
1687
1688 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
1689 <glossdef>
1690 <para>
1691 If there are multiple versions of recipes available, this
1692 variable determines which recipe should be given preference.
1693 You must always suffix the variable with the
1694 <link linkend='var-PN'><filename>PN</filename></link>
1695 you want to select, and you should set
1696 <link linkend='var-PV'><filename>PV</filename></link>
1697 accordingly for precedence.
1698 You can use the "<filename>%</filename>" character as a
1699 wildcard to match any number of characters, which can be
1700 useful when specifying versions that contain long revision
1701 numbers that could potentially change.
1702 Here are two examples:
1703 <literallayout class='monospaced'>
1704 PREFERRED_VERSION_python = "2.7.3"
1705 PREFERRED_VERSION_linux-yocto = "3.10%"
1706 </literallayout>
1707 </para>
1708 </glossdef>
1709 </glossentry>
1710
1711 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
1712 <glossdef>
1713 <para>
1714 Specifies additional paths from which BitBake gets source code.
1715 When the build system searches for source code, it first
1716 tries the local download directory.
1717 If that location fails, the build system tries locations
1718 defined by <filename>PREMIRRORS</filename>, the upstream
1719 source, and then locations specified by
1720 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
1721 in that order.
1722 </para>
1723
1724 <para>
1725 Typically, you would add a specific server for the
1726 build system to attempt before any others by adding
1727 something like the following to your configuration:
1728 <literallayout class='monospaced'>
1729 PREMIRRORS_prepend = "\
1730 git://.*/.* http://www.yoctoproject.org/sources/ \n \
1731 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
1732 http://.*/.* http://www.yoctoproject.org/sources/ \n \
1733 https://.*/.* http://www.yoctoproject.org/sources/ \n"
1734 </literallayout>
1735 These changes cause the build system to intercept
1736 Git, FTP, HTTP, and HTTPS requests and direct them to
1737 the <filename>http://</filename> sources mirror.
1738 You can use <filename>file://</filename> URLs to point
1739 to local directories or network shares as well.
1740 </para>
1741 </glossdef>
1742 </glossentry>
1743
1744 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
1745 <glossdef>
1746 <para>
1747 A list of aliases that a recipe also provides.
1748 These aliases are useful for satisfying dependencies of
1749 other recipes during the build (as specified by
1750 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
1751 <note>
1752 A recipe's own
1753 <filename><link linkend='var-PN'>PN</link></filename>
1754 is implicitly already in its
1755 <filename>PROVIDES</filename> list.
1756 </note>
1757 </para>
1758 </glossdef>
1759 </glossentry>
1760
1761 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
1762 <glossdef>
1763 <para>
1764 The network based
1765 <link linkend='var-PR'><filename>PR</filename></link>
1766 service host and port.
1767 </para>
1768
1769 <para>
1770 Following is an example of how the <filename>PRSERV_HOST</filename> variable is
1771 set:
1772 <literallayout class='monospaced'>
1773 PRSERV_HOST = "localhost:0"
1774 </literallayout>
1775 You must set the variable if you want to automatically
1776 start a local PR service.
1777 You can set <filename>PRSERV_HOST</filename> to other
1778 values to use a remote PR service.
1779 </para>
1780 </glossdef>
1781 </glossentry>
1782
1783 <glossentry id='var-PV'><glossterm>PV</glossterm>
1784 <glossdef>
1785 <para>The version of the recipe.
1786 </para>
1787 </glossdef>
1788 </glossentry>
1789
1790 </glossdiv>
1791
1792<!--
1793 <glossdiv id='var-glossary-q'><title>Q</title>
1794 </glossdiv>
1795-->
1796
1797 <glossdiv id='var-glossary-r'><title>R</title>
1798
1799 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
1800 <glossdef>
1801 <para>
1802 Lists a package's runtime dependencies (i.e. other packages)
1803 that must be installed in order for the built package to run
1804 correctly.
1805 If a package in this list cannot be found during the build,
1806 you will get a build error.
1807 </para>
1808
1809 <para>
1810 Because the <filename>RDEPENDS</filename> variable applies
1811 to packages being built, you should always use the variable
1812 in a form with an attached package name.
1813 For example, suppose you are building a development package
1814 that depends on the <filename>perl</filename> package.
1815 In this case, you would use the following
1816 <filename>RDEPENDS</filename> statement:
1817 <literallayout class='monospaced'>
1818 RDEPENDS_${PN}-dev += "perl"
1819 </literallayout>
1820 In the example, the development package depends on
1821 the <filename>perl</filename> package.
1822 Thus, the <filename>RDEPENDS</filename> variable has the
1823 <filename>${PN}-dev</filename> package name as part of the
1824 variable.
1825 </para>
1826
1827 <para>
1828 BitBake supports specifying versioned dependencies.
1829 Although the syntax varies depending on the packaging
1830 format, BitBake hides these differences from you.
1831 Here is the general syntax to specify versions with
1832 the <filename>RDEPENDS</filename> variable:
1833 <literallayout class='monospaced'>
1834 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
1835 </literallayout>
1836 For <filename>operator</filename>, you can specify the
1837 following:
1838 <literallayout class='monospaced'>
1839 =
1840 &lt;
1841 &gt;
1842 &lt;=
1843 &gt;=
1844 </literallayout>
1845 For example, the following sets up a dependency on version
1846 1.2 or greater of the package <filename>foo</filename>:
1847 <literallayout class='monospaced'>
1848 RDEPENDS_${PN} = "foo (>= 1.2)"
1849 </literallayout>
1850 </para>
1851
1852 <para>
1853 For information on build-time dependencies, see the
1854 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1855 variable.
1856 </para>
1857 </glossdef>
1858 </glossentry>
1859
1860 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
1861 <glossdef>
1862 <para>
1863 A list of package name aliases that a package also provides.
1864 These aliases are useful for satisfying runtime dependencies
1865 of other packages both during the build and on the target
1866 (as specified by
1867 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
1868 </para>
1869 <para>
1870 As with all package-controlling variables, you must always
1871 use the variable in conjunction with a package name override.
1872 Here is an example:
1873 <literallayout class='monospaced'>
1874 RPROVIDES_${PN} = "widget-abi-2"
1875 </literallayout>
1876 </para>
1877 </glossdef>
1878 </glossentry>
1879
1880 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
1881 <glossdef>
1882 <para>
1883 A list of packages that extends the usability of a package
1884 being built.
1885 The package being built does not depend on this list of
1886 packages in order to successfully build, but needs them for
1887 the extended usability.
1888 To specify runtime dependencies for packages, see the
1889 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
1890 variable.
1891 </para>
1892
1893 <para>
1894 BitBake supports specifying versioned recommends.
1895 Although the syntax varies depending on the packaging
1896 format, BitBake hides these differences from you.
1897 Here is the general syntax to specify versions with
1898 the <filename>RRECOMMENDS</filename> variable:
1899 <literallayout class='monospaced'>
1900 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
1901 </literallayout>
1902 For <filename>operator</filename>, you can specify the
1903 following:
1904 <literallayout class='monospaced'>
1905 =
1906 &lt;
1907 &gt;
1908 &lt;=
1909 &gt;=
1910 </literallayout>
1911 For example, the following sets up a recommend on version
1912 1.2 or greater of the package <filename>foo</filename>:
1913 <literallayout class='monospaced'>
1914 RRECOMMENDS_${PN} = "foo (>= 1.2)"
1915 </literallayout>
1916 </para>
1917 </glossdef>
1918 </glossentry>
1919
1920 </glossdiv>
1921
1922 <glossdiv id='var-glossary-s'><title>S</title>
1923
1924 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
1925 <glossdef>
1926 <para>The section in which packages should be categorized.</para>
1927 </glossdef>
1928 </glossentry>
1929
1930 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
1931 <glossdef>
1932 <para>
1933 The list of source files - local or remote.
1934 This variable tells BitBake which bits
1935 to pull for the build and how to pull them.
1936 For example, if the recipe or append file needs to
1937 fetch a single tarball from the Internet, the recipe or
1938 append file uses a <filename>SRC_URI</filename>
1939 entry that specifies that tarball.
1940 On the other hand, if the recipe or append file needs to
1941 fetch a tarball and include a custom file, the recipe or
1942 append file needs an <filename>SRC_URI</filename> variable
1943 that specifies all those sources.</para>
1944 <para>The following list explains the available URI protocols:
1945 <itemizedlist>
1946 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
1947 Fetches files, which are usually files shipped with
1948 the metadata,
1949 from the local machine.
1950 The path is relative to the
1951 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
1952 variable.</para></listitem>
1953 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
1954 Bazaar revision control repository.</para></listitem>
1955 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
1956 Git revision control repository.</para></listitem>
1957 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
1958 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
1959 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
1960 a repo (Git) repository.</para></listitem>
1961 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
1962 the Internet using HTTP.</para></listitem>
1963 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
1964 from the Internet using HTTPS.</para></listitem>
1965 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
1966 from the Internet using FTP.</para></listitem>
1967 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
1968 a CVS revision control repository.</para></listitem>
1969 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
1970 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
1971 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
1972 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
1973 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
1974 a secure shell.</para></listitem>
1975 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
1976 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
1977 </itemizedlist>
1978 </para>
1979 <para>Here are some additional options worth mentioning:
1980 <itemizedlist>
1981 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
1982 whether or not to unpack the file if it is an archive.
1983 The default action is to unpack the file.</para></listitem>
1984 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
1985 (or extracts its contents) into the specified
1986 subdirectory.
1987 This option is useful for unusual tarballs or other archives that
1988 do not have their files already in a subdirectory within the archive.
1989 </para></listitem>
1990 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
1991 name to be used for association with <filename>SRC_URI</filename> checksums
1992 when you have more than one file specified in <filename>SRC_URI</filename>.
1993 </para></listitem>
1994 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
1995 the filename used when storing the downloaded file.</para></listitem>
1996 </itemizedlist>
1997 </para>
1998 </glossdef>
1999 </glossentry>
2000
2001 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
2002 <glossdef>
2003 <para>
2004 The date of the source code used to build the package.
2005 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2006 </para>
2007 </glossdef>
2008 </glossentry>
2009
2010 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
2011 <glossdef>
2012 <para>
2013 The revision of the source code used to build the package.
2014 This variable applies only when using Subversion, Git, Mercurial and Bazaar.
2015 If you want to build a fixed revision and you want
2016 to avoid performing a query on the remote repository every time
2017 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
2018 full revision identifier and not just a tag.
2019 </para>
2020 </glossdef>
2021 </glossentry>
2022
2023 <glossentry id='var-SRCREV_FORMAT'><glossterm>SRCREV_FORMAT</glossterm>
2024 <glossdef>
2025 <para>
2026 Helps construct valid
2027 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2028 values when multiple source controlled URLs are used in
2029 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
2030 </para>
2031
2032 <para>
2033 The system needs help constructing these values under these
2034 circumstances.
2035 Each component in the <filename>SRC_URI</filename>
2036 is assigned a name and these are referenced
2037 in the <filename>SRCREV_FORMAT</filename> variable.
2038 Consider an example with URLs named "machine" and "meta".
2039 In this case, <filename>SRCREV_FORMAT</filename> could look
2040 like "machine_meta" and those names would have the SCM
2041 versions substituted into each position.
2042 Only one <filename>AUTOINC</filename> placeholder is added
2043 and if needed.
2044 And, this placeholder is placed at the start of the
2045 returned string.
2046 </para>
2047 </glossdef>
2048 </glossentry>
2049
2050 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
2051 <glossdef>
2052 <para>
2053 Specifies the base path used to create recipe stamp files.
2054 The path to an actual stamp file is constructed by evaluating this
2055 string and then appending additional information.
2056 </para>
2057 </glossdef>
2058 </glossentry>
2059
2060 <glossentry id='var-STAMPCLEAN'><glossterm>STAMPCLEAN</glossterm>
2061 <glossdef>
2062 <para>
2063 Specifies the base path used to create recipe stamp files.
2064 Unlike the
2065 <link linkend='var-STAMP'><filename>STAMP</filename></link>
2066 variable, <filename>STAMPCLEAN</filename> can contain
2067 wildcards to match the range of files a clean operation
2068 should remove.
2069 BitBake uses a clean operation to remove any other stamps
2070 it should be removing when creating a new stamp.
2071 </para>
2072 </glossdef>
2073 </glossentry>
2074
2075 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
2076 <glossdef>
2077 <para>
2078 A short summary for the recipe, which is 72 characters or less.
2079 </para>
2080 </glossdef>
2081 </glossentry>
2082
2083 </glossdiv>
2084
2085 <glossdiv id='var-glossary-t'><title>T</title>
2086
2087 <glossentry id='var-T'><glossterm>T</glossterm>
2088 <glossdef>
2089 <para>Points to a directory were BitBake places
2090 temporary files, which consist mostly of task logs and
2091 scripts, when building a particular recipe.
2092 </para>
2093 </glossdef>
2094 </glossentry>
2095
2096 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
2097 <glossdef>
2098 <para>
2099 Points to the build directory.
2100 BitBake automatically sets this variable.
2101 </para>
2102 </glossdef>
2103 </glossentry>
2104
2105 </glossdiv>
2106
2107<!--
2108 <glossdiv id='var-glossary-u'><title>U</title>
2109 </glossdiv>
2110
2111 <glossdiv id='var-glossary-v'><title>V</title>
2112 </glossdiv>
2113
2114 <glossdiv id='var-glossary-w'><title>W</title>
2115 </glossdiv>
2116
2117 <glossdiv id='var-glossary-x'><title>X</title>
2118 </glossdiv>
2119
2120 <glossdiv id='var-glossary-y'><title>Y</title>
2121 </glossdiv>
2122
2123 <glossdiv id='var-glossary-z'><title>Z</title>
2124 </glossdiv>
2125-->
2126
2127
2128</glossary>
2129</chapter>
2130<!--
2131vim: expandtab tw=80 ts=4
2132-->
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 2024-04-25 01:51:06 +0000