diff options
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst')
-rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 1372 |
1 files changed, 1372 insertions, 0 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst new file mode 100644 index 0000000000..74a3eb8095 --- /dev/null +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | |||
@@ -0,0 +1,1372 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.5 | ||
2 | |||
3 | ================== | ||
4 | Variables Glossary | ||
5 | ================== | ||
6 | |||
7 | | | ||
8 | |||
9 | This chapter lists common variables used by BitBake and gives an | ||
10 | overview of their function and contents. | ||
11 | |||
12 | .. note:: | ||
13 | |||
14 | Following are some points regarding the variables listed in this | ||
15 | glossary: | ||
16 | |||
17 | - The variables listed in this glossary are specific to BitBake. | ||
18 | Consequently, the descriptions are limited to that context. | ||
19 | |||
20 | - Also, variables exist in other systems that use BitBake (e.g. The | ||
21 | Yocto Project and OpenEmbedded) that have names identical to those | ||
22 | found in this glossary. For such cases, the variables in those | ||
23 | systems extend the functionality of the variable as it is | ||
24 | described here in this glossary. | ||
25 | |||
26 | - Finally, there are variables mentioned in this glossary that do | ||
27 | not appear in the BitBake glossary. These other variables are | ||
28 | variables used in systems that use BitBake. | ||
29 | |||
30 | .. glossary:: | ||
31 | |||
32 | :term:`ASSUME_PROVIDED` | ||
33 | Lists recipe names (:term:`PN` values) BitBake does not | ||
34 | attempt to build. Instead, BitBake assumes these recipes have already | ||
35 | been built. | ||
36 | |||
37 | In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native | ||
38 | tools that should not be built. An example is ``git-native``, which | ||
39 | when specified allows for the Git binary from the host to be used | ||
40 | rather than building ``git-native``. | ||
41 | |||
42 | :term:`B` | ||
43 | The directory in which BitBake executes functions during a recipe's | ||
44 | build process. | ||
45 | |||
46 | :term:`BB_ALLOWED_NETWORKS` | ||
47 | Specifies a space-delimited list of hosts that the fetcher is allowed | ||
48 | to use to obtain the required source code. Following are | ||
49 | considerations surrounding this variable: | ||
50 | |||
51 | - This host list is only used if | ||
52 | :term:`BB_NO_NETWORK` is either not set or | ||
53 | set to "0". | ||
54 | |||
55 | - Limited support for the "``*``" wildcard character for matching | ||
56 | against the beginning of host names exists. For example, the | ||
57 | following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and | ||
58 | ``foo.git.gnu.org``. :: | ||
59 | |||
60 | BB_ALLOWED_NETWORKS = "\*.gnu.org" | ||
61 | |||
62 | .. important:: | ||
63 | |||
64 | The use of the "``*``" character only works at the beginning of | ||
65 | a host name and it must be isolated from the remainder of the | ||
66 | host name. You cannot use the wildcard character in any other | ||
67 | location of the name or combined with the front part of the | ||
68 | name. | ||
69 | |||
70 | For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` | ||
71 | is not. | ||
72 | |||
73 | - Mirrors not in the host list are skipped and logged in debug. | ||
74 | |||
75 | - Attempts to access networks not in the host list cause a failure. | ||
76 | |||
77 | Using ``BB_ALLOWED_NETWORKS`` in conjunction with | ||
78 | :term:`PREMIRRORS` is very useful. Adding the | ||
79 | host you want to use to ``PREMIRRORS`` results in the source code | ||
80 | being fetched from an allowed location and avoids raising an error | ||
81 | when a host that is not allowed is in a | ||
82 | :term:`SRC_URI` statement. This is because the | ||
83 | fetcher does not attempt to use the host listed in ``SRC_URI`` after | ||
84 | a successful fetch from the ``PREMIRRORS`` occurs. | ||
85 | |||
86 | :term:`BB_CONSOLELOG` | ||
87 | Specifies the path to a log file into which BitBake's user interface | ||
88 | writes output during the build. | ||
89 | |||
90 | :term:`BB_CURRENTTASK` | ||
91 | Contains the name of the currently running task. The name does not | ||
92 | include the ``do_`` prefix. | ||
93 | |||
94 | :term:`BB_DANGLINGAPPENDS_WARNONLY` | ||
95 | Defines how BitBake handles situations where an append file | ||
96 | (``.bbappend``) has no corresponding recipe file (``.bb``). This | ||
97 | condition often occurs when layers get out of sync (e.g. ``oe-core`` | ||
98 | bumps a recipe version and the old recipe no longer exists and the | ||
99 | other layer has not been updated to the new version of the recipe | ||
100 | yet). | ||
101 | |||
102 | The default fatal behavior is safest because it is the sane reaction | ||
103 | given something is out of sync. It is important to realize when your | ||
104 | changes are no longer being applied. | ||
105 | |||
106 | :term:`BB_DEFAULT_TASK` | ||
107 | The default task to use when none is specified (e.g. with the ``-c`` | ||
108 | command line option). The task name specified should not include the | ||
109 | ``do_`` prefix. | ||
110 | |||
111 | :term:`BB_DISKMON_DIRS` | ||
112 | Monitors disk space and available inodes during the build and allows | ||
113 | you to control the build based on these parameters. | ||
114 | |||
115 | Disk space monitoring is disabled by default. When setting this | ||
116 | variable, use the following form: :: | ||
117 | |||
118 | BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" | ||
119 | |||
120 | where: | ||
121 | |||
122 | <action> is: | ||
123 | ABORT: Immediately abort the build when | ||
124 | a threshold is broken. | ||
125 | STOPTASKS: Stop the build after the currently | ||
126 | executing tasks have finished when | ||
127 | a threshold is broken. | ||
128 | WARN: Issue a warning but continue the | ||
129 | build when a threshold is broken. | ||
130 | Subsequent warnings are issued as | ||
131 | defined by the | ||
132 | BB_DISKMON_WARNINTERVAL variable, | ||
133 | which must be defined. | ||
134 | |||
135 | <dir> is: | ||
136 | Any directory you choose. You can specify one or | ||
137 | more directories to monitor by separating the | ||
138 | groupings with a space. If two directories are | ||
139 | on the same device, only the first directory | ||
140 | is monitored. | ||
141 | |||
142 | <threshold> is: | ||
143 | Either the minimum available disk space, | ||
144 | the minimum number of free inodes, or | ||
145 | both. You must specify at least one. To | ||
146 | omit one or the other, simply omit the value. | ||
147 | Specify the threshold using G, M, K for Gbytes, | ||
148 | Mbytes, and Kbytes, respectively. If you do | ||
149 | not specify G, M, or K, Kbytes is assumed by | ||
150 | default. Do not use GB, MB, or KB. | ||
151 | |||
152 | Here are some examples: :: | ||
153 | |||
154 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" | ||
155 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" | ||
156 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" | ||
157 | |||
158 | The first example works only if you also set the | ||
159 | :term:`BB_DISKMON_WARNINTERVAL` | ||
160 | variable. This example causes the build system to immediately abort | ||
161 | when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or | ||
162 | the available free inodes drops below 100 Kbytes. Because two | ||
163 | directories are provided with the variable, the build system also | ||
164 | issues a warning when the disk space in the ``${SSTATE_DIR}`` | ||
165 | directory drops below 1 Gbyte or the number of free inodes drops | ||
166 | below 100 Kbytes. Subsequent warnings are issued during intervals as | ||
167 | defined by the ``BB_DISKMON_WARNINTERVAL`` variable. | ||
168 | |||
169 | The second example stops the build after all currently executing | ||
170 | tasks complete when the minimum disk space in the ``${TMPDIR}`` | ||
171 | directory drops below 1 Gbyte. No disk monitoring occurs for the free | ||
172 | inodes in this case. | ||
173 | |||
174 | The final example immediately aborts the build when the number of | ||
175 | free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No | ||
176 | disk space monitoring for the directory itself occurs in this case. | ||
177 | |||
178 | :term:`BB_DISKMON_WARNINTERVAL` | ||
179 | Defines the disk space and free inode warning intervals. | ||
180 | |||
181 | If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you | ||
182 | must also use the :term:`BB_DISKMON_DIRS` | ||
183 | variable and define its action as "WARN". During the build, | ||
184 | subsequent warnings are issued each time disk space or number of free | ||
185 | inodes further reduces by the respective interval. | ||
186 | |||
187 | If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you | ||
188 | do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk | ||
189 | monitoring interval defaults to the following: | ||
190 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
191 | |||
192 | When specifying the variable in your configuration file, use the | ||
193 | following form: :: | ||
194 | |||
195 | BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" | ||
196 | |||
197 | where: | ||
198 | |||
199 | <disk_space_interval> is: | ||
200 | An interval of memory expressed in either | ||
201 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
202 | respectively. You cannot use GB, MB, or KB. | ||
203 | |||
204 | <disk_inode_interval> is: | ||
205 | An interval of free inodes expressed in either | ||
206 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
207 | respectively. You cannot use GB, MB, or KB. | ||
208 | |||
209 | Here is an example: :: | ||
210 | |||
211 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" | ||
212 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
213 | |||
214 | These variables cause BitBake to | ||
215 | issue subsequent warnings each time the available disk space further | ||
216 | reduces by 50 Mbytes or the number of free inodes further reduces by | ||
217 | 5 Kbytes in the ``${SSTATE_DIR}`` directory. Subsequent warnings | ||
218 | based on the interval occur each time a respective interval is | ||
219 | reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes). | ||
220 | |||
221 | :term:`BB_ENV_WHITELIST` | ||
222 | Specifies the internal whitelist of variables to allow through from | ||
223 | the external environment into BitBake's datastore. If the value of | ||
224 | this variable is not specified (which is the default), the following | ||
225 | list is used: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`, | ||
226 | :term:`BB_ENV_WHITELIST`, and :term:`BB_ENV_EXTRAWHITE`. | ||
227 | |||
228 | .. note:: | ||
229 | |||
230 | You must set this variable in the external environment in order | ||
231 | for it to work. | ||
232 | |||
233 | :term:`BB_ENV_EXTRAWHITE` | ||
234 | Specifies an additional set of variables to allow through (whitelist) | ||
235 | from the external environment into BitBake's datastore. This list of | ||
236 | variables are on top of the internal list set in | ||
237 | :term:`BB_ENV_WHITELIST`. | ||
238 | |||
239 | .. note:: | ||
240 | |||
241 | You must set this variable in the external environment in order | ||
242 | for it to work. | ||
243 | |||
244 | :term:`BB_FETCH_PREMIRRORONLY` | ||
245 | When set to "1", causes BitBake's fetcher module to only search | ||
246 | :term:`PREMIRRORS` for files. BitBake will not | ||
247 | search the main :term:`SRC_URI` or | ||
248 | :term:`MIRRORS`. | ||
249 | |||
250 | :term:`BB_FILENAME` | ||
251 | Contains the filename of the recipe that owns the currently running | ||
252 | task. For example, if the ``do_fetch`` task that resides in the | ||
253 | ``my-recipe.bb`` is executing, the ``BB_FILENAME`` variable contains | ||
254 | "/foo/path/my-recipe.bb". | ||
255 | |||
256 | :term:`BBFILES_DYNAMIC` | ||
257 | Activates content depending on presence of identified layers. You | ||
258 | identify the layers by the collections that the layers define. | ||
259 | |||
260 | Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose | ||
261 | corresponding ``.bb`` file is in a layer that attempts to modify other | ||
262 | layers through ``.bbappend`` but does not want to introduce a hard | ||
263 | dependency on those other layers. | ||
264 | |||
265 | Additionally you can prefix the rule with "!" to add ``.bbappend`` and | ||
266 | ``.bb`` files in case a layer is not present. Use this avoid hard | ||
267 | dependency on those other layers. | ||
268 | |||
269 | Use the following form for ``BBFILES_DYNAMIC``: :: | ||
270 | |||
271 | collection_name:filename_pattern | ||
272 | |||
273 | The following example identifies two collection names and two filename | ||
274 | patterns: :: | ||
275 | |||
276 | BBFILES_DYNAMIC += "\ | ||
277 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ | ||
278 | core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ | ||
279 | " | ||
280 | |||
281 | When the collection name is prefixed with "!" it will add the file pattern in case | ||
282 | the layer is absent: :: | ||
283 | |||
284 | BBFILES_DYNAMIC += "\ | ||
285 | !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ | ||
286 | " | ||
287 | |||
288 | This next example shows an error message that occurs because invalid | ||
289 | entries are found, which cause parsing to abort: :: | ||
290 | |||
291 | ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not: | ||
292 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend | ||
293 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend | ||
294 | |||
295 | :term:`BB_GENERATE_MIRROR_TARBALLS` | ||
296 | Causes tarballs of the Git repositories, including the Git metadata, | ||
297 | to be placed in the :term:`DL_DIR` directory. Anyone | ||
298 | wishing to create a source mirror would want to enable this variable. | ||
299 | |||
300 | For performance reasons, creating and placing tarballs of the Git | ||
301 | repositories is not the default action by BitBake. :: | ||
302 | |||
303 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
304 | |||
305 | :term:`BB_HASHCONFIG_WHITELIST` | ||
306 | Lists variables that are excluded from base configuration checksum, | ||
307 | which is used to determine if the cache can be reused. | ||
308 | |||
309 | One of the ways BitBake determines whether to re-parse the main | ||
310 | metadata is through checksums of the variables in the datastore of | ||
311 | the base configuration data. There are variables that you typically | ||
312 | want to exclude when checking whether or not to re-parse and thus | ||
313 | rebuild the cache. As an example, you would usually exclude ``TIME`` | ||
314 | and ``DATE`` because these variables are always changing. If you did | ||
315 | not exclude them, BitBake would never reuse the cache. | ||
316 | |||
317 | :term:`BB_HASHBASE_WHITELIST` | ||
318 | Lists variables that are excluded from checksum and dependency data. | ||
319 | Variables that are excluded can therefore change without affecting | ||
320 | the checksum mechanism. A common example would be the variable for | ||
321 | the path of the build. BitBake's output should not (and usually does | ||
322 | not) depend on the directory in which it was built. | ||
323 | |||
324 | :term:`BB_HASHCHECK_FUNCTION` | ||
325 | Specifies the name of the function to call during the "setscene" part | ||
326 | of the task's execution in order to validate the list of task hashes. | ||
327 | The function returns the list of setscene tasks that should be | ||
328 | executed. | ||
329 | |||
330 | At this point in the execution of the code, the objective is to | ||
331 | quickly verify if a given setscene function is likely to work or not. | ||
332 | It's easier to check the list of setscene functions in one pass than | ||
333 | to call many individual tasks. The returned list need not be | ||
334 | completely accurate. A given setscene task can still later fail. | ||
335 | However, the more accurate the data returned, the more efficient the | ||
336 | build will be. | ||
337 | |||
338 | :term:`BB_INVALIDCONF` | ||
339 | Used in combination with the ``ConfigParsed`` event to trigger | ||
340 | re-parsing the base metadata (i.e. all the recipes). The | ||
341 | ``ConfigParsed`` event can set the variable to trigger the re-parse. | ||
342 | You must be careful to avoid recursive loops with this functionality. | ||
343 | |||
344 | :term:`BB_LOGCONFIG` | ||
345 | Specifies the name of a config file that contains the user logging | ||
346 | configuration. See | ||
347 | :ref:`bitbake-user-manual/bitbake-user-manual-execution:logging` | ||
348 | for additional information | ||
349 | |||
350 | :term:`BB_LOGFMT` | ||
351 | Specifies the name of the log files saved into | ||
352 | ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT`` | ||
353 | variable is undefined and the log file names get created using the | ||
354 | following form: :: | ||
355 | |||
356 | log.{task}.{pid} | ||
357 | |||
358 | If you want to force log files to take a specific name, you can set this | ||
359 | variable in a configuration file. | ||
360 | |||
361 | :term:`BB_NICE_LEVEL` | ||
362 | Allows BitBake to run at a specific priority (i.e. nice level). | ||
363 | System permissions usually mean that BitBake can reduce its priority | ||
364 | but not raise it again. See :term:`BB_TASK_NICE_LEVEL` for | ||
365 | additional information. | ||
366 | |||
367 | :term:`BB_NO_NETWORK` | ||
368 | Disables network access in the BitBake fetcher modules. With this | ||
369 | access disabled, any command that attempts to access the network | ||
370 | becomes an error. | ||
371 | |||
372 | Disabling network access is useful for testing source mirrors, | ||
373 | running builds when not connected to the Internet, and when operating | ||
374 | in certain kinds of firewall environments. | ||
375 | |||
376 | :term:`BB_NUMBER_THREADS` | ||
377 | The maximum number of tasks BitBake should run in parallel at any one | ||
378 | time. If your host development system supports multiple cores, a good | ||
379 | rule of thumb is to set this variable to twice the number of cores. | ||
380 | |||
381 | :term:`BB_NUMBER_PARSE_THREADS` | ||
382 | Sets the number of threads BitBake uses when parsing. By default, the | ||
383 | number of threads is equal to the number of cores on the system. | ||
384 | |||
385 | :term:`BB_ORIGENV` | ||
386 | Contains a copy of the original external environment in which BitBake | ||
387 | was run. The copy is taken before any whitelisted variable values are | ||
388 | filtered into BitBake's datastore. | ||
389 | |||
390 | .. note:: | ||
391 | |||
392 | The contents of this variable is a datastore object that can be | ||
393 | queried using the normal datastore operations. | ||
394 | |||
395 | :term:`BB_PRESERVE_ENV` | ||
396 | Disables whitelisting and instead allows all variables through from | ||
397 | the external environment into BitBake's datastore. | ||
398 | |||
399 | .. note:: | ||
400 | |||
401 | You must set this variable in the external environment in order | ||
402 | for it to work. | ||
403 | |||
404 | :term:`BB_RUNFMT` | ||
405 | Specifies the name of the executable script files (i.e. run files) | ||
406 | saved into ``${``\ :term:`T`\ ``}``. By default, the | ||
407 | ``BB_RUNFMT`` variable is undefined and the run file names get | ||
408 | created using the following form: :: | ||
409 | |||
410 | run.{task}.{pid} | ||
411 | |||
412 | If you want to force run files to take a specific name, you can set this | ||
413 | variable in a configuration file. | ||
414 | |||
415 | :term:`BB_RUNTASK` | ||
416 | Contains the name of the currently executing task. The value includes | ||
417 | the "do\_" prefix. For example, if the currently executing task is | ||
418 | ``do_config``, the value is "do_config". | ||
419 | |||
420 | :term:`BB_SCHEDULER` | ||
421 | Selects the name of the scheduler to use for the scheduling of | ||
422 | BitBake tasks. Three options exist: | ||
423 | |||
424 | - *basic* - The basic framework from which everything derives. Using | ||
425 | this option causes tasks to be ordered numerically as they are | ||
426 | parsed. | ||
427 | |||
428 | - *speed* - Executes tasks first that have more tasks depending on | ||
429 | them. The "speed" option is the default. | ||
430 | |||
431 | - *completion* - Causes the scheduler to try to complete a given | ||
432 | recipe once its build has started. | ||
433 | |||
434 | :term:`BB_SCHEDULERS` | ||
435 | Defines custom schedulers to import. Custom schedulers need to be | ||
436 | derived from the ``RunQueueScheduler`` class. | ||
437 | |||
438 | For information how to select a scheduler, see the | ||
439 | :term:`BB_SCHEDULER` variable. | ||
440 | |||
441 | :term:`BB_SETSCENE_DEPVALID` | ||
442 | Specifies a function BitBake calls that determines whether BitBake | ||
443 | requires a setscene dependency to be met. | ||
444 | |||
445 | When running a setscene task, BitBake needs to know which | ||
446 | dependencies of that setscene task also need to be run. Whether | ||
447 | dependencies also need to be run is highly dependent on the metadata. | ||
448 | The function specified by this variable returns a "True" or "False" | ||
449 | depending on whether the dependency needs to be met. | ||
450 | |||
451 | :term:`BB_SETSCENE_VERIFY_FUNCTION2` | ||
452 | Specifies a function to call that verifies the list of planned task | ||
453 | execution before the main task execution happens. The function is | ||
454 | called once BitBake has a list of setscene tasks that have run and | ||
455 | either succeeded or failed. | ||
456 | |||
457 | The function allows for a task list check to see if they make sense. | ||
458 | Even if BitBake was planning to skip a task, the returned value of | ||
459 | the function can force BitBake to run the task, which is necessary | ||
460 | under certain metadata defined circumstances. | ||
461 | |||
462 | :term:`BB_SIGNATURE_EXCLUDE_FLAGS` | ||
463 | Lists variable flags (varflags) that can be safely excluded from | ||
464 | checksum and dependency data for keys in the datastore. When | ||
465 | generating checksum or dependency data for keys in the datastore, the | ||
466 | flags set against that key are normally included in the checksum. | ||
467 | |||
468 | For more information on varflags, see the | ||
469 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" | ||
470 | section. | ||
471 | |||
472 | :term:`BB_SIGNATURE_HANDLER` | ||
473 | Defines the name of the signature handler BitBake uses. The signature | ||
474 | handler defines the way stamp files are created and handled, if and | ||
475 | how the signature is incorporated into the stamps, and how the | ||
476 | signature itself is generated. | ||
477 | |||
478 | A new signature handler can be added by injecting a class derived | ||
479 | from the ``SignatureGenerator`` class into the global namespace. | ||
480 | |||
481 | :term:`BB_SRCREV_POLICY` | ||
482 | Defines the behavior of the fetcher when it interacts with source | ||
483 | control systems and dynamic source revisions. The | ||
484 | ``BB_SRCREV_POLICY`` variable is useful when working without a | ||
485 | network. | ||
486 | |||
487 | The variable can be set using one of two policies: | ||
488 | |||
489 | - *cache* - Retains the value the system obtained previously rather | ||
490 | than querying the source control system each time. | ||
491 | |||
492 | - *clear* - Queries the source controls system every time. With this | ||
493 | policy, there is no cache. The "clear" policy is the default. | ||
494 | |||
495 | :term:`BB_STAMP_POLICY` | ||
496 | Defines the mode used for how timestamps of stamp files are compared. | ||
497 | You can set the variable to one of the following modes: | ||
498 | |||
499 | - *perfile* - Timestamp comparisons are only made between timestamps | ||
500 | of a specific recipe. This is the default mode. | ||
501 | |||
502 | - *full* - Timestamp comparisons are made for all dependencies. | ||
503 | |||
504 | - *whitelist* - Identical to "full" mode except timestamp | ||
505 | comparisons are made for recipes listed in the | ||
506 | :term:`BB_STAMP_WHITELIST` variable. | ||
507 | |||
508 | .. note:: | ||
509 | |||
510 | Stamp policies are largely obsolete with the introduction of | ||
511 | setscene tasks. | ||
512 | |||
513 | :term:`BB_STAMP_WHITELIST` | ||
514 | Lists files whose stamp file timestamps are compared when the stamp | ||
515 | policy mode is set to "whitelist". For information on stamp policies, | ||
516 | see the :term:`BB_STAMP_POLICY` variable. | ||
517 | |||
518 | :term:`BB_STRICT_CHECKSUM` | ||
519 | Sets a more strict checksum mechanism for non-local URLs. Setting | ||
520 | this variable to a value causes BitBake to report an error if it | ||
521 | encounters a non-local URL that does not have at least one checksum | ||
522 | specified. | ||
523 | |||
524 | :term:`BB_TASK_IONICE_LEVEL` | ||
525 | Allows adjustment of a task's Input/Output priority. During | ||
526 | Autobuilder testing, random failures can occur for tasks due to I/O | ||
527 | starvation. These failures occur during various QEMU runtime | ||
528 | timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust | ||
529 | the I/O priority of these tasks. | ||
530 | |||
531 | .. note:: | ||
532 | |||
533 | This variable works similarly to the :term:`BB_TASK_NICE_LEVEL` | ||
534 | variable except with a task's I/O priorities. | ||
535 | |||
536 | Set the variable as follows: :: | ||
537 | |||
538 | BB_TASK_IONICE_LEVEL = "class.prio" | ||
539 | |||
540 | For *class*, the default value is "2", which is a best effort. You can use | ||
541 | "1" for realtime and "3" for idle. If you want to use realtime, you | ||
542 | must have superuser privileges. | ||
543 | |||
544 | For *prio*, you can use any value from "0", which is the highest | ||
545 | priority, to "7", which is the lowest. The default value is "4". You | ||
546 | do not need any special privileges to use this range of priority | ||
547 | values. | ||
548 | |||
549 | .. note:: | ||
550 | |||
551 | In order for your I/O priority settings to take effect, you need the | ||
552 | Completely Fair Queuing (CFQ) Scheduler selected for the backing block | ||
553 | device. To select the scheduler, use the following command form where | ||
554 | device is the device (e.g. sda, sdb, and so forth): :: | ||
555 | |||
556 | $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler" | ||
557 | |||
558 | :term:`BB_TASK_NICE_LEVEL` | ||
559 | Allows specific tasks to change their priority (i.e. nice level). | ||
560 | |||
561 | You can use this variable in combination with task overrides to raise | ||
562 | or lower priorities of specific tasks. For example, on the `Yocto | ||
563 | Project <http://www.yoctoproject.org>`__ autobuilder, QEMU emulation | ||
564 | in images is given a higher priority as compared to build tasks to | ||
565 | ensure that images do not suffer timeouts on loaded systems. | ||
566 | |||
567 | :term:`BB_TASKHASH` | ||
568 | Within an executing task, this variable holds the hash of the task as | ||
569 | returned by the currently enabled signature generator. | ||
570 | |||
571 | :term:`BB_VERBOSE_LOGS` | ||
572 | Controls how verbose BitBake is during builds. If set, shell scripts | ||
573 | echo commands and shell script output appears on standard out | ||
574 | (stdout). | ||
575 | |||
576 | :term:`BB_WORKERCONTEXT` | ||
577 | Specifies if the current context is executing a task. BitBake sets | ||
578 | this variable to "1" when a task is being executed. The value is not | ||
579 | set when the task is in server context during parsing or event | ||
580 | handling. | ||
581 | |||
582 | :term:`BBCLASSEXTEND` | ||
583 | Allows you to extend a recipe so that it builds variants of the | ||
584 | software. Some examples of these variants for recipes from the | ||
585 | OpenEmbedded-Core metadata are "natives" such as ``quilt-native``, | ||
586 | which is a copy of Quilt built to run on the build system; "crosses" | ||
587 | such as ``gcc-cross``, which is a compiler built to run on the build | ||
588 | machine but produces binaries that run on the target ``MACHINE``; | ||
589 | "nativesdk", which targets the SDK machine instead of ``MACHINE``; | ||
590 | and "mulitlibs" in the form "``multilib:``\ multilib_name". | ||
591 | |||
592 | To build a different variant of the recipe with a minimal amount of | ||
593 | code, it usually is as simple as adding the variable to your recipe. | ||
594 | Here are two examples. The "native" variants are from the | ||
595 | OpenEmbedded-Core metadata: :: | ||
596 | |||
597 | BBCLASSEXTEND =+ "native nativesdk" | ||
598 | BBCLASSEXTEND =+ "multilib:multilib_name" | ||
599 | |||
600 | .. note:: | ||
601 | |||
602 | Internally, the ``BBCLASSEXTEND`` mechanism generates recipe | ||
603 | variants by rewriting variable values and applying overrides such | ||
604 | as ``_class-native``. For example, to generate a native version of | ||
605 | a recipe, a :term:`DEPENDS` on "foo" is | ||
606 | rewritten to a ``DEPENDS`` on "foo-native". | ||
607 | |||
608 | Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. | ||
609 | Parsing once adds some limitations. For example, it is not | ||
610 | possible to include a different file depending on the variant, | ||
611 | since ``include`` statements are processed when the recipe is | ||
612 | parsed. | ||
613 | |||
614 | :term:`BBDEBUG` | ||
615 | Sets the BitBake debug output level to a specific value as | ||
616 | incremented by the ``-D`` command line option. | ||
617 | |||
618 | .. note:: | ||
619 | |||
620 | You must set this variable in the external environment in order | ||
621 | for it to work. | ||
622 | |||
623 | :term:`BBFILE_COLLECTIONS` | ||
624 | Lists the names of configured layers. These names are used to find | ||
625 | the other ``BBFILE_*`` variables. Typically, each layer appends its | ||
626 | name to this variable in its ``conf/layer.conf`` file. | ||
627 | |||
628 | :term:`BBFILE_PATTERN` | ||
629 | Variable that expands to match files from | ||
630 | :term:`BBFILES` in a particular layer. This | ||
631 | variable is used in the ``conf/layer.conf`` file and must be suffixed | ||
632 | with the name of the specific layer (e.g. | ||
633 | ``BBFILE_PATTERN_emenlow``). | ||
634 | |||
635 | :term:`BBFILE_PRIORITY` | ||
636 | Assigns the priority for recipe files in each layer. | ||
637 | |||
638 | This variable is useful in situations where the same recipe appears | ||
639 | in more than one layer. Setting this variable allows you to | ||
640 | prioritize a layer against other layers that contain the same recipe | ||
641 | - effectively letting you control the precedence for the multiple | ||
642 | layers. The precedence established through this variable stands | ||
643 | regardless of a recipe's version (:term:`PV` variable). | ||
644 | For example, a layer that has a recipe with a higher ``PV`` value but | ||
645 | for which the ``BBFILE_PRIORITY`` is set to have a lower precedence | ||
646 | still has a lower precedence. | ||
647 | |||
648 | A larger value for the ``BBFILE_PRIORITY`` variable results in a | ||
649 | higher precedence. For example, the value 6 has a higher precedence | ||
650 | than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable | ||
651 | is set based on layer dependencies (see the ``LAYERDEPENDS`` variable | ||
652 | for more information. The default priority, if unspecified for a | ||
653 | layer with no dependencies, is the lowest defined priority + 1 (or 1 | ||
654 | if no priorities are defined). | ||
655 | |||
656 | .. tip:: | ||
657 | |||
658 | You can use the command bitbake-layers show-layers to list all | ||
659 | configured layers along with their priorities. | ||
660 | |||
661 | :term:`BBFILES` | ||
662 | A space-separated list of recipe files BitBake uses to build | ||
663 | software. | ||
664 | |||
665 | When specifying recipe files, you can pattern match using Python's | ||
666 | `glob <https://docs.python.org/3/library/glob.html>`_ syntax. | ||
667 | For details on the syntax, see the documentation by following the | ||
668 | previous link. | ||
669 | |||
670 | :term:`BBINCLUDED` | ||
671 | Contains a space-separated list of all of all files that BitBake's | ||
672 | parser included during parsing of the current file. | ||
673 | |||
674 | :term:`BBINCLUDELOGS` | ||
675 | If set to a value, enables printing the task log when reporting a | ||
676 | failed task. | ||
677 | |||
678 | :term:`BBINCLUDELOGS_LINES` | ||
679 | If :term:`BBINCLUDELOGS` is set, specifies | ||
680 | the maximum number of lines from the task log file to print when | ||
681 | reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, | ||
682 | the entire log is printed. | ||
683 | |||
684 | :term:`BBLAYERS` | ||
685 | Lists the layers to enable during the build. This variable is defined | ||
686 | in the ``bblayers.conf`` configuration file in the build directory. | ||
687 | Here is an example: :: | ||
688 | |||
689 | BBLAYERS = " \ | ||
690 | /home/scottrif/poky/meta \ | ||
691 | /home/scottrif/poky/meta-yocto \ | ||
692 | /home/scottrif/poky/meta-yocto-bsp \ | ||
693 | /home/scottrif/poky/meta-mykernel \ | ||
694 | " | ||
695 | |||
696 | This example enables four layers, one of which is a custom, user-defined | ||
697 | layer named ``meta-mykernel``. | ||
698 | |||
699 | :term:`BBLAYERS_FETCH_DIR` | ||
700 | Sets the base location where layers are stored. This setting is used | ||
701 | in conjunction with ``bitbake-layers layerindex-fetch`` and tells | ||
702 | ``bitbake-layers`` where to place the fetched layers. | ||
703 | |||
704 | :term:`BBMASK` | ||
705 | Prevents BitBake from processing recipes and recipe append files. | ||
706 | |||
707 | You can use the ``BBMASK`` variable to "hide" these ``.bb`` and | ||
708 | ``.bbappend`` files. BitBake ignores any recipe or recipe append | ||
709 | files that match any of the expressions. It is as if BitBake does not | ||
710 | see them at all. Consequently, matching files are not parsed or | ||
711 | otherwise used by BitBake. | ||
712 | |||
713 | The values you provide are passed to Python's regular expression | ||
714 | compiler. Consequently, the syntax follows Python's Regular | ||
715 | Expression (re) syntax. The expressions are compared against the full | ||
716 | paths to the files. For complete syntax information, see Python's | ||
717 | documentation at http://docs.python.org/3/library/re.html. | ||
718 | |||
719 | The following example uses a complete regular expression to tell | ||
720 | BitBake to ignore all recipe and recipe append files in the | ||
721 | ``meta-ti/recipes-misc/`` directory: :: | ||
722 | |||
723 | BBMASK = "meta-ti/recipes-misc/" | ||
724 | |||
725 | If you want to mask out multiple directories or recipes, you can | ||
726 | specify multiple regular expression fragments. This next example | ||
727 | masks out multiple directories and individual recipes: :: | ||
728 | |||
729 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" | ||
730 | BBMASK += "/meta-oe/recipes-support/" | ||
731 | BBMASK += "/meta-foo/.*/openldap" | ||
732 | BBMASK += "opencv.*\.bbappend" | ||
733 | BBMASK += "lzma" | ||
734 | |||
735 | .. note:: | ||
736 | |||
737 | When specifying a directory name, use the trailing slash character | ||
738 | to ensure you match just that directory name. | ||
739 | |||
740 | :term:`BBMULTICONFIG` | ||
741 | Enables BitBake to perform multiple configuration builds and lists | ||
742 | each separate configuration (multiconfig). You can use this variable | ||
743 | to cause BitBake to build multiple targets where each target has a | ||
744 | separate configuration. Define ``BBMULTICONFIG`` in your | ||
745 | ``conf/local.conf`` configuration file. | ||
746 | |||
747 | As an example, the following line specifies three multiconfigs, each | ||
748 | having a separate configuration file: :: | ||
749 | |||
750 | BBMULTIFONFIG = "configA configB configC" | ||
751 | |||
752 | Each configuration file you use must reside in the | ||
753 | build directory within a directory named ``conf/multiconfig`` (e.g. | ||
754 | build_directory\ ``/conf/multiconfig/configA.conf``). | ||
755 | |||
756 | For information on how to use ``BBMULTICONFIG`` in an environment | ||
757 | that supports building targets with multiple configurations, see the | ||
758 | ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`" | ||
759 | section. | ||
760 | |||
761 | :term:`BBPATH` | ||
762 | Used by BitBake to locate class (``.bbclass``) and configuration | ||
763 | (``.conf``) files. This variable is analogous to the ``PATH`` | ||
764 | variable. | ||
765 | |||
766 | If you run BitBake from a directory outside of the build directory, | ||
767 | you must be sure to set ``BBPATH`` to point to the build directory. | ||
768 | Set the variable as you would any environment variable and then run | ||
769 | BitBake: :: | ||
770 | |||
771 | $ BBPATH="build_directory" | ||
772 | $ export BBPATH | ||
773 | $ bitbake target | ||
774 | |||
775 | :term:`BBSERVER` | ||
776 | Points to the server that runs memory-resident BitBake. The variable | ||
777 | is only used when you employ memory-resident BitBake. | ||
778 | |||
779 | :term:`BBTARGETS` | ||
780 | Allows you to use a configuration file to add to the list of | ||
781 | command-line target recipes you want to build. | ||
782 | |||
783 | :term:`BBVERSIONS` | ||
784 | Allows a single recipe to build multiple versions of a project from a | ||
785 | single recipe file. You also able to specify conditional metadata | ||
786 | using the :term:`OVERRIDES` mechanism for a | ||
787 | single version or for an optionally named range of versions. | ||
788 | |||
789 | For more information on ``BBVERSIONS``, see the | ||
790 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variants - class extension mechanism`" | ||
791 | section. | ||
792 | |||
793 | :term:`BITBAKE_UI` | ||
794 | Used to specify the UI module to use when running BitBake. Using this | ||
795 | variable is equivalent to using the ``-u`` command-line option. | ||
796 | |||
797 | .. note:: | ||
798 | |||
799 | You must set this variable in the external environment in order | ||
800 | for it to work. | ||
801 | |||
802 | :term:`BUILDNAME` | ||
803 | A name assigned to the build. The name defaults to a datetime stamp | ||
804 | of when the build was started but can be defined by the metadata. | ||
805 | |||
806 | :term:`BZRDIR` | ||
807 | The directory in which files checked out of a Bazaar system are | ||
808 | stored. | ||
809 | |||
810 | :term:`CACHE` | ||
811 | Specifies the directory BitBake uses to store a cache of the metadata | ||
812 | so it does not need to be parsed every time BitBake is started. | ||
813 | |||
814 | :term:`CVSDIR` | ||
815 | The directory in which files checked out under the CVS system are | ||
816 | stored. | ||
817 | |||
818 | :term:`DEFAULT_PREFERENCE` | ||
819 | Specifies a weak bias for recipe selection priority. | ||
820 | |||
821 | The most common usage of this is variable is to set it to "-1" within | ||
822 | a recipe for a development version of a piece of software. Using the | ||
823 | variable in this way causes the stable version of the recipe to build | ||
824 | by default in the absence of ``PREFERRED_VERSION`` being used to | ||
825 | build the development version. | ||
826 | |||
827 | .. note:: | ||
828 | |||
829 | The bias provided by DEFAULT_PREFERENCE is weak and is overridden by | ||
830 | :term:`BBFILE_PRIORITY` if that variable is different between two | ||
831 | layers that contain different versions of the same recipe. | ||
832 | |||
833 | :term:`DEPENDS` | ||
834 | Lists a recipe's build-time dependencies (i.e. other recipe files). | ||
835 | |||
836 | Consider this simple example for two recipes named "a" and "b" that | ||
837 | produce similarly named packages. In this example, the ``DEPENDS`` | ||
838 | statement appears in the "a" recipe: :: | ||
839 | |||
840 | DEPENDS = "b" | ||
841 | |||
842 | Here, the dependency is such that the ``do_configure`` task for recipe "a" | ||
843 | depends on the ``do_populate_sysroot`` task of recipe "b". This means | ||
844 | anything that recipe "b" puts into sysroot is available when recipe "a" is | ||
845 | configuring itself. | ||
846 | |||
847 | For information on runtime dependencies, see the :term:`RDEPENDS` | ||
848 | variable. | ||
849 | |||
850 | :term:`DESCRIPTION` | ||
851 | A long description for the recipe. | ||
852 | |||
853 | :term:`DL_DIR` | ||
854 | The central download directory used by the build process to store | ||
855 | downloads. By default, ``DL_DIR`` gets files suitable for mirroring for | ||
856 | everything except Git repositories. If you want tarballs of Git | ||
857 | repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. | ||
858 | |||
859 | :term:`EXCLUDE_FROM_WORLD` | ||
860 | Directs BitBake to exclude a recipe from world builds (i.e. | ||
861 | ``bitbake world``). During world builds, BitBake locates, parses and | ||
862 | builds all recipes found in every layer exposed in the | ||
863 | ``bblayers.conf`` configuration file. | ||
864 | |||
865 | To exclude a recipe from a world build using this variable, set the | ||
866 | variable to "1" in the recipe. | ||
867 | |||
868 | .. note:: | ||
869 | |||
870 | Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a world | ||
871 | build in order to satisfy dependencies of other recipes. Adding a | ||
872 | recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not | ||
873 | explicitly added to the list of build targets in a world build. | ||
874 | |||
875 | :term:`FAKEROOT` | ||
876 | Contains the command to use when running a shell script in a fakeroot | ||
877 | environment. The ``FAKEROOT`` variable is obsolete and has been | ||
878 | replaced by the other ``FAKEROOT*`` variables. See these entries in | ||
879 | the glossary for more information. | ||
880 | |||
881 | :term:`FAKEROOTBASEENV` | ||
882 | Lists environment variables to set when executing the command defined | ||
883 | by :term:`FAKEROOTCMD` that starts the | ||
884 | bitbake-worker process in the fakeroot environment. | ||
885 | |||
886 | :term:`FAKEROOTCMD` | ||
887 | Contains the command that starts the bitbake-worker process in the | ||
888 | fakeroot environment. | ||
889 | |||
890 | :term:`FAKEROOTDIRS` | ||
891 | Lists directories to create before running a task in the fakeroot | ||
892 | environment. | ||
893 | |||
894 | :term:`FAKEROOTENV` | ||
895 | Lists environment variables to set when running a task in the | ||
896 | fakeroot environment. For additional information on environment | ||
897 | variables and the fakeroot environment, see the | ||
898 | :term:`FAKEROOTBASEENV` variable. | ||
899 | |||
900 | :term:`FAKEROOTNOENV` | ||
901 | Lists environment variables to set when running a task that is not in | ||
902 | the fakeroot environment. For additional information on environment | ||
903 | variables and the fakeroot environment, see the | ||
904 | :term:`FAKEROOTENV` variable. | ||
905 | |||
906 | :term:`FETCHCMD` | ||
907 | Defines the command the BitBake fetcher module executes when running | ||
908 | fetch operations. You need to use an override suffix when you use the | ||
909 | variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``). | ||
910 | |||
911 | :term:`FILE` | ||
912 | Points at the current file. BitBake sets this variable during the | ||
913 | parsing process to identify the file being parsed. BitBake also sets | ||
914 | this variable when a recipe is being executed to identify the recipe | ||
915 | file. | ||
916 | |||
917 | :term:`FILESPATH` | ||
918 | Specifies directories BitBake uses when searching for patches and | ||
919 | files. The "local" fetcher module uses these directories when | ||
920 | handling ``file://`` URLs. The variable behaves like a shell ``PATH`` | ||
921 | environment variable. The value is a colon-separated list of | ||
922 | directories that are searched left-to-right in order. | ||
923 | |||
924 | :term:`GITDIR` | ||
925 | The directory in which a local copy of a Git repository is stored | ||
926 | when it is cloned. | ||
927 | |||
928 | :term:`HGDIR` | ||
929 | The directory in which files checked out of a Mercurial system are | ||
930 | stored. | ||
931 | |||
932 | :term:`HOMEPAGE` | ||
933 | Website where more information about the software the recipe is | ||
934 | building can be found. | ||
935 | |||
936 | :term:`INHERIT` | ||
937 | Causes the named class or classes to be inherited globally. Anonymous | ||
938 | functions in the class or classes are not executed for the base | ||
939 | configuration and in each individual recipe. The OpenEmbedded build | ||
940 | system ignores changes to ``INHERIT`` in individual recipes. | ||
941 | |||
942 | For more information on ``INHERIT``, see the | ||
943 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" | ||
944 | section. | ||
945 | |||
946 | :term:`LAYERDEPENDS` | ||
947 | Lists the layers, separated by spaces, upon which this recipe | ||
948 | depends. Optionally, you can specify a specific layer version for a | ||
949 | dependency by adding it to the end of the layer name with a colon, | ||
950 | (e.g. "anotherlayer:3" to be compared against | ||
951 | :term:`LAYERVERSION`\ ``_anotherlayer`` in | ||
952 | this case). BitBake produces an error if any dependency is missing or | ||
953 | the version numbers do not match exactly (if specified). | ||
954 | |||
955 | You use this variable in the ``conf/layer.conf`` file. You must also | ||
956 | use the specific layer name as a suffix to the variable (e.g. | ||
957 | ``LAYERDEPENDS_mylayer``). | ||
958 | |||
959 | :term:`LAYERDIR` | ||
960 | When used inside the ``layer.conf`` configuration file, this variable | ||
961 | provides the path of the current layer. This variable is not | ||
962 | available outside of ``layer.conf`` and references are expanded | ||
963 | immediately when parsing of the file completes. | ||
964 | |||
965 | :term:`LAYERDIR_RE` | ||
966 | When used inside the ``layer.conf`` configuration file, this variable | ||
967 | provides the path of the current layer, escaped for use in a regular | ||
968 | expression (:term:`BBFILE_PATTERN`). This | ||
969 | variable is not available outside of ``layer.conf`` and references | ||
970 | are expanded immediately when parsing of the file completes. | ||
971 | |||
972 | :term:`LAYERVERSION` | ||
973 | Optionally specifies the version of a layer as a single number. You | ||
974 | can use this variable within | ||
975 | :term:`LAYERDEPENDS` for another layer in | ||
976 | order to depend on a specific version of the layer. | ||
977 | |||
978 | You use this variable in the ``conf/layer.conf`` file. You must also | ||
979 | use the specific layer name as a suffix to the variable (e.g. | ||
980 | ``LAYERDEPENDS_mylayer``). | ||
981 | |||
982 | :term:`LICENSE` | ||
983 | The list of source licenses for the recipe. | ||
984 | |||
985 | :term:`MIRRORS` | ||
986 | Specifies additional paths from which BitBake gets source code. When | ||
987 | the build system searches for source code, it first tries the local | ||
988 | download directory. If that location fails, the build system tries | ||
989 | locations defined by :term:`PREMIRRORS`, the | ||
990 | upstream source, and then locations specified by ``MIRRORS`` in that | ||
991 | order. | ||
992 | |||
993 | :term:`MULTI_PROVIDER_WHITELIST` | ||
994 | Allows you to suppress BitBake warnings caused when building two | ||
995 | separate recipes that provide the same output. | ||
996 | |||
997 | BitBake normally issues a warning when building two different recipes | ||
998 | where each provides the same output. This scenario is usually | ||
999 | something the user does not want. However, cases do exist where it | ||
1000 | makes sense, particularly in the ``virtual/*`` namespace. You can use | ||
1001 | this variable to suppress BitBake's warnings. | ||
1002 | |||
1003 | To use the variable, list provider names (e.g. recipe names, | ||
1004 | ``virtual/kernel``, and so forth). | ||
1005 | |||
1006 | :term:`OVERRIDES` | ||
1007 | BitBake uses ``OVERRIDES`` to control what variables are overridden | ||
1008 | after BitBake parses recipes and configuration files. | ||
1009 | |||
1010 | Following is a simple example that uses an overrides list based on | ||
1011 | machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can | ||
1012 | find information on how to use ``OVERRIDES`` in the | ||
1013 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax | ||
1014 | (overrides)`" section. | ||
1015 | |||
1016 | :term:`P4DIR` | ||
1017 | The directory in which a local copy of a Perforce depot is stored | ||
1018 | when it is fetched. | ||
1019 | |||
1020 | :term:`PACKAGES` | ||
1021 | The list of packages the recipe creates. | ||
1022 | |||
1023 | :term:`PACKAGES_DYNAMIC` | ||
1024 | A promise that your recipe satisfies runtime dependencies for | ||
1025 | optional modules that are found in other recipes. | ||
1026 | ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it | ||
1027 | only states that they should be satisfied. For example, if a hard, | ||
1028 | runtime dependency (:term:`RDEPENDS`) of another | ||
1029 | package is satisfied during the build through the | ||
1030 | ``PACKAGES_DYNAMIC`` variable, but a package with the module name is | ||
1031 | never actually produced, then the other package will be broken. | ||
1032 | |||
1033 | :term:`PE` | ||
1034 | The epoch of the recipe. By default, this variable is unset. The | ||
1035 | variable is used to make upgrades possible when the versioning scheme | ||
1036 | changes in some backwards incompatible way. | ||
1037 | |||
1038 | :term:`PERSISTENT_DIR` | ||
1039 | Specifies the directory BitBake uses to store data that should be | ||
1040 | preserved between builds. In particular, the data stored is the data | ||
1041 | that uses BitBake's persistent data API and the data used by the PR | ||
1042 | Server and PR Service. | ||
1043 | |||
1044 | :term:`PF` | ||
1045 | Specifies the recipe or package name and includes all version and | ||
1046 | revision numbers (i.e. ``eglibc-2.13-r20+svnr15508/`` and | ||
1047 | ``bash-4.2-r1/``). | ||
1048 | |||
1049 | :term:`PN` | ||
1050 | The recipe name. | ||
1051 | |||
1052 | :term:`PR` | ||
1053 | The revision of the recipe. | ||
1054 | |||
1055 | :term:`PREFERRED_PROVIDER` | ||
1056 | Determines which recipe should be given preference when multiple | ||
1057 | recipes provide the same item. You should always suffix the variable | ||
1058 | with the name of the provided item, and you should set it to the | ||
1059 | :term:`PN` of the recipe to which you want to give | ||
1060 | precedence. Some examples: :: | ||
1061 | |||
1062 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | ||
1063 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" | ||
1064 | PREFERRED_PROVIDER_virtual/libgl ?= "mesa" | ||
1065 | |||
1066 | :term:`PREFERRED_PROVIDERS` | ||
1067 | Determines which recipe should be given preference for cases where | ||
1068 | multiple recipes provide the same item. Functionally, | ||
1069 | ``PREFERRED_PROVIDERS`` is identical to | ||
1070 | :term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable | ||
1071 | lets you define preferences for multiple situations using the following | ||
1072 | form: :: | ||
1073 | |||
1074 | PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..." | ||
1075 | |||
1076 | This form is a convenient replacement for the following: :: | ||
1077 | |||
1078 | PREFERRED_PROVIDER_xxx = "yyy" | ||
1079 | PREFERRED_PROVIDER_aaa = "bbb" | ||
1080 | |||
1081 | :term:`PREFERRED_VERSION` | ||
1082 | If there are multiple versions of recipes available, this variable | ||
1083 | determines which recipe should be given preference. You must always | ||
1084 | suffix the variable with the :term:`PN` you want to | ||
1085 | select, and you should set :term:`PV` accordingly for | ||
1086 | precedence. | ||
1087 | |||
1088 | The ``PREFERRED_VERSION`` variable supports limited wildcard use | ||
1089 | through the "``%``" character. You can use the character to match any | ||
1090 | number of characters, which can be useful when specifying versions | ||
1091 | that contain long revision numbers that potentially change. Here are | ||
1092 | two examples: :: | ||
1093 | |||
1094 | PREFERRED_VERSION_python = "2.7.3" | ||
1095 | PREFERRED_VERSION_linux-yocto = "4.12%" | ||
1096 | |||
1097 | .. important:: | ||
1098 | |||
1099 | The use of the " % " character is limited in that it only works at the | ||
1100 | end of the string. You cannot use the wildcard character in any other | ||
1101 | location of the string. | ||
1102 | |||
1103 | :term:`PREMIRRORS` | ||
1104 | Specifies additional paths from which BitBake gets source code. When | ||
1105 | the build system searches for source code, it first tries the local | ||
1106 | download directory. If that location fails, the build system tries | ||
1107 | locations defined by ``PREMIRRORS``, the upstream source, and then | ||
1108 | locations specified by :term:`MIRRORS` in that order. | ||
1109 | |||
1110 | Typically, you would add a specific server for the build system to | ||
1111 | attempt before any others by adding something like the following to | ||
1112 | your configuration: :: | ||
1113 | |||
1114 | PREMIRRORS_prepend = "\ | ||
1115 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
1116 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
1117 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
1118 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
1119 | |||
1120 | These changes cause the build system to intercept Git, FTP, HTTP, and | ||
1121 | HTTPS requests and direct them to the ``http://`` sources mirror. You can | ||
1122 | use ``file://`` URLs to point to local directories or network shares as | ||
1123 | well. | ||
1124 | |||
1125 | :term:`PROVIDES` | ||
1126 | A list of aliases by which a particular recipe can be known. By | ||
1127 | default, a recipe's own ``PN`` is implicitly already in its | ||
1128 | ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional | ||
1129 | aliases are synonyms for the recipe and can be useful satisfying | ||
1130 | dependencies of other recipes during the build as specified by | ||
1131 | ``DEPENDS``. | ||
1132 | |||
1133 | Consider the following example ``PROVIDES`` statement from a recipe | ||
1134 | file ``libav_0.8.11.bb``: :: | ||
1135 | |||
1136 | PROVIDES += "libpostproc" | ||
1137 | |||
1138 | The ``PROVIDES`` statement results in the "libav" recipe also being known | ||
1139 | as "libpostproc". | ||
1140 | |||
1141 | In addition to providing recipes under alternate names, the | ||
1142 | ``PROVIDES`` mechanism is also used to implement virtual targets. A | ||
1143 | virtual target is a name that corresponds to some particular | ||
1144 | functionality (e.g. a Linux kernel). Recipes that provide the | ||
1145 | functionality in question list the virtual target in ``PROVIDES``. | ||
1146 | Recipes that depend on the functionality in question can include the | ||
1147 | virtual target in :term:`DEPENDS` to leave the | ||
1148 | choice of provider open. | ||
1149 | |||
1150 | Conventionally, virtual targets have names on the form | ||
1151 | "virtual/function" (e.g. "virtual/kernel"). The slash is simply part | ||
1152 | of the name and has no syntactical significance. | ||
1153 | |||
1154 | :term:`PRSERV_HOST` | ||
1155 | The network based :term:`PR` service host and port. | ||
1156 | |||
1157 | Following is an example of how the ``PRSERV_HOST`` variable is set: :: | ||
1158 | |||
1159 | PRSERV_HOST = "localhost:0" | ||
1160 | |||
1161 | You must set the variable if you want to automatically start a local PR | ||
1162 | service. You can set ``PRSERV_HOST`` to other values to use a remote PR | ||
1163 | service. | ||
1164 | |||
1165 | :term:`PV` | ||
1166 | The version of the recipe. | ||
1167 | |||
1168 | :term:`RDEPENDS` | ||
1169 | Lists a package's runtime dependencies (i.e. other packages) that | ||
1170 | must be installed in order for the built package to run correctly. If | ||
1171 | a package in this list cannot be found during the build, you will get | ||
1172 | a build error. | ||
1173 | |||
1174 | Because the ``RDEPENDS`` variable applies to packages being built, | ||
1175 | you should always use the variable in a form with an attached package | ||
1176 | name. For example, suppose you are building a development package | ||
1177 | that depends on the ``perl`` package. In this case, you would use the | ||
1178 | following ``RDEPENDS`` statement: :: | ||
1179 | |||
1180 | RDEPENDS_${PN}-dev += "perl" | ||
1181 | |||
1182 | In the example, the development package depends on the ``perl`` package. | ||
1183 | Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part | ||
1184 | of the variable. | ||
1185 | |||
1186 | BitBake supports specifying versioned dependencies. Although the | ||
1187 | syntax varies depending on the packaging format, BitBake hides these | ||
1188 | differences from you. Here is the general syntax to specify versions | ||
1189 | with the ``RDEPENDS`` variable: :: | ||
1190 | |||
1191 | RDEPENDS_${PN} = "package (operator version)" | ||
1192 | |||
1193 | For ``operator``, you can specify the following: :: | ||
1194 | |||
1195 | = | ||
1196 | < | ||
1197 | > | ||
1198 | <= | ||
1199 | >= | ||
1200 | |||
1201 | For example, the following sets up a dependency on version 1.2 or | ||
1202 | greater of the package ``foo``: :: | ||
1203 | |||
1204 | RDEPENDS_${PN} = "foo (>= 1.2)" | ||
1205 | |||
1206 | For information on build-time dependencies, see the :term:`DEPENDS` | ||
1207 | variable. | ||
1208 | |||
1209 | :term:`REPODIR` | ||
1210 | The directory in which a local copy of a ``google-repo`` directory is | ||
1211 | stored when it is synced. | ||
1212 | |||
1213 | :term:`RPROVIDES` | ||
1214 | A list of package name aliases that a package also provides. These | ||
1215 | aliases are useful for satisfying runtime dependencies of other | ||
1216 | packages both during the build and on the target (as specified by | ||
1217 | ``RDEPENDS``). | ||
1218 | |||
1219 | As with all package-controlling variables, you must always use the | ||
1220 | variable in conjunction with a package name override. Here is an | ||
1221 | example: :: | ||
1222 | |||
1223 | RPROVIDES_${PN} = "widget-abi-2" | ||
1224 | |||
1225 | :term:`RRECOMMENDS` | ||
1226 | A list of packages that extends the usability of a package being | ||
1227 | built. The package being built does not depend on this list of | ||
1228 | packages in order to successfully build, but needs them for the | ||
1229 | extended usability. To specify runtime dependencies for packages, see | ||
1230 | the ``RDEPENDS`` variable. | ||
1231 | |||
1232 | BitBake supports specifying versioned recommends. Although the syntax | ||
1233 | varies depending on the packaging format, BitBake hides these | ||
1234 | differences from you. Here is the general syntax to specify versions | ||
1235 | with the ``RRECOMMENDS`` variable: :: | ||
1236 | |||
1237 | RRECOMMENDS_${PN} = "package (operator version)" | ||
1238 | |||
1239 | For ``operator``, you can specify the following: :: | ||
1240 | |||
1241 | = | ||
1242 | < | ||
1243 | > | ||
1244 | <= | ||
1245 | >= | ||
1246 | |||
1247 | For example, the following sets up a recommend on version | ||
1248 | 1.2 or greater of the package ``foo``: :: | ||
1249 | |||
1250 | RRECOMMENDS_${PN} = "foo (>= 1.2)" | ||
1251 | |||
1252 | :term:`SECTION` | ||
1253 | The section in which packages should be categorized. | ||
1254 | |||
1255 | :term:`SRC_URI` | ||
1256 | The list of source files - local or remote. This variable tells | ||
1257 | BitBake which bits to pull for the build and how to pull them. For | ||
1258 | example, if the recipe or append file needs to fetch a single tarball | ||
1259 | from the Internet, the recipe or append file uses a ``SRC_URI`` entry | ||
1260 | that specifies that tarball. On the other hand, if the recipe or | ||
1261 | append file needs to fetch a tarball and include a custom file, the | ||
1262 | recipe or append file needs an ``SRC_URI`` variable that specifies | ||
1263 | all those sources. | ||
1264 | |||
1265 | The following list explains the available URI protocols: | ||
1266 | |||
1267 | - ``file://`` : Fetches files, which are usually files shipped | ||
1268 | with the metadata, from the local machine. The path is relative to | ||
1269 | the :term:`FILESPATH` variable. | ||
1270 | |||
1271 | - ``bzr://`` : Fetches files from a Bazaar revision control | ||
1272 | repository. | ||
1273 | |||
1274 | - ``git://`` : Fetches files from a Git revision control | ||
1275 | repository. | ||
1276 | |||
1277 | - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service) | ||
1278 | revision control repository. | ||
1279 | |||
1280 | - ``repo://`` : Fetches files from a repo (Git) repository. | ||
1281 | |||
1282 | - ``http://`` : Fetches files from the Internet using HTTP. | ||
1283 | |||
1284 | - ``https://`` : Fetches files from the Internet using HTTPS. | ||
1285 | |||
1286 | - ``ftp://`` : Fetches files from the Internet using FTP. | ||
1287 | |||
1288 | - ``cvs://`` : Fetches files from a CVS revision control | ||
1289 | repository. | ||
1290 | |||
1291 | - ``hg://`` : Fetches files from a Mercurial (``hg``) revision | ||
1292 | control repository. | ||
1293 | |||
1294 | - ``p4://`` : Fetches files from a Perforce (``p4``) revision | ||
1295 | control repository. | ||
1296 | |||
1297 | - ``ssh://`` : Fetches files from a secure shell. | ||
1298 | |||
1299 | - ``svn://`` : Fetches files from a Subversion (``svn``) revision | ||
1300 | control repository. | ||
1301 | |||
1302 | Here are some additional options worth mentioning: | ||
1303 | |||
1304 | - ``unpack`` : Controls whether or not to unpack the file if it is | ||
1305 | an archive. The default action is to unpack the file. | ||
1306 | |||
1307 | - ``subdir`` : Places the file (or extracts its contents) into the | ||
1308 | specified subdirectory. This option is useful for unusual tarballs | ||
1309 | or other archives that do not have their files already in a | ||
1310 | subdirectory within the archive. | ||
1311 | |||
1312 | - ``name`` : Specifies a name to be used for association with | ||
1313 | ``SRC_URI`` checksums when you have more than one file specified | ||
1314 | in ``SRC_URI``. | ||
1315 | |||
1316 | - ``downloadfilename`` : Specifies the filename used when storing | ||
1317 | the downloaded file. | ||
1318 | |||
1319 | :term:`SRCDATE` | ||
1320 | The date of the source code used to build the package. This variable | ||
1321 | applies only if the source was fetched from a Source Code Manager | ||
1322 | (SCM). | ||
1323 | |||
1324 | :term:`SRCREV` | ||
1325 | The revision of the source code used to build the package. This | ||
1326 | variable applies only when using Subversion, Git, Mercurial and | ||
1327 | Bazaar. If you want to build a fixed revision and you want to avoid | ||
1328 | performing a query on the remote repository every time BitBake parses | ||
1329 | your recipe, you should specify a ``SRCREV`` that is a full revision | ||
1330 | identifier and not just a tag. | ||
1331 | |||
1332 | :term:`SRCREV_FORMAT` | ||
1333 | Helps construct valid :term:`SRCREV` values when | ||
1334 | multiple source controlled URLs are used in | ||
1335 | :term:`SRC_URI`. | ||
1336 | |||
1337 | The system needs help constructing these values under these | ||
1338 | circumstances. Each component in the ``SRC_URI`` is assigned a name | ||
1339 | and these are referenced in the ``SRCREV_FORMAT`` variable. Consider | ||
1340 | an example with URLs named "machine" and "meta". In this case, | ||
1341 | ``SRCREV_FORMAT`` could look like "machine_meta" and those names | ||
1342 | would have the SCM versions substituted into each position. Only one | ||
1343 | ``AUTOINC`` placeholder is added and if needed. And, this placeholder | ||
1344 | is placed at the start of the returned string. | ||
1345 | |||
1346 | :term:`STAMP` | ||
1347 | Specifies the base path used to create recipe stamp files. The path | ||
1348 | to an actual stamp file is constructed by evaluating this string and | ||
1349 | then appending additional information. | ||
1350 | |||
1351 | :term:`STAMPCLEAN` | ||
1352 | Specifies the base path used to create recipe stamp files. Unlike the | ||
1353 | :term:`STAMP` variable, ``STAMPCLEAN`` can contain | ||
1354 | wildcards to match the range of files a clean operation should | ||
1355 | remove. BitBake uses a clean operation to remove any other stamps it | ||
1356 | should be removing when creating a new stamp. | ||
1357 | |||
1358 | :term:`SUMMARY` | ||
1359 | A short summary for the recipe, which is 72 characters or less. | ||
1360 | |||
1361 | :term:`SVNDIR` | ||
1362 | The directory in which files checked out of a Subversion system are | ||
1363 | stored. | ||
1364 | |||
1365 | :term:`T` | ||
1366 | Points to a directory were BitBake places temporary files, which | ||
1367 | consist mostly of task logs and scripts, when building a particular | ||
1368 | recipe. | ||
1369 | |||
1370 | :term:`TOPDIR` | ||
1371 | Points to the build directory. BitBake automatically sets this | ||
1372 | variable. | ||