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