blob: 74a3eb8095122ca8a89fa778d61b37c4d4defb3a [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001.. SPDX-License-Identifier: CC-BY-2.5
2
3==================
4Variables Glossary
5==================
6
7|
8
9This chapter lists common variables used by BitBake and gives an
10overview 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
Andrew Geisslerf0343792020-11-18 10:42:21 -060032 :term:`ASSUME_PROVIDED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050033 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
Andrew Geisslerf0343792020-11-18 10:42:21 -060042 :term:`B`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043 The directory in which BitBake executes functions during a recipe's
44 build process.
45
Andrew Geisslerf0343792020-11-18 10:42:21 -060046 :term:`BB_ALLOWED_NETWORKS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047 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
Andrew Geisslerf0343792020-11-18 10:42:21 -060086 :term:`BB_CONSOLELOG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050087 Specifies the path to a log file into which BitBake's user interface
88 writes output during the build.
89
Andrew Geisslerf0343792020-11-18 10:42:21 -060090 :term:`BB_CURRENTTASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050091 Contains the name of the currently running task. The name does not
92 include the ``do_`` prefix.
93
Andrew Geisslerf0343792020-11-18 10:42:21 -060094 :term:`BB_DANGLINGAPPENDS_WARNONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050095 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600106 :term:`BB_DEFAULT_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500107 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600111 :term:`BB_DISKMON_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600178 :term:`BB_DISKMON_WARNINTERVAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600221 :term:`BB_ENV_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500222 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600233 :term:`BB_ENV_EXTRAWHITE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600244 :term:`BB_FETCH_PREMIRRORONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500245 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600250 :term:`BB_FILENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500251 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600256 :term:`BBFILES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500257 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600295 :term:`BB_GENERATE_MIRROR_TARBALLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600305 :term:`BB_HASHCONFIG_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500306 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600317 :term:`BB_HASHBASE_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500318 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600324 :term:`BB_HASHCHECK_FUNCTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600338 :term:`BB_INVALIDCONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500339 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600344 :term:`BB_LOGCONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500345 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600350 :term:`BB_LOGFMT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500351 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600361 :term:`BB_NICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500362 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600367 :term:`BB_NO_NETWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500368 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600376 :term:`BB_NUMBER_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600381 :term:`BB_NUMBER_PARSE_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500382 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600385 :term:`BB_ORIGENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500386 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600395 :term:`BB_PRESERVE_ENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500396 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600404 :term:`BB_RUNFMT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500405 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600415 :term:`BB_RUNTASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500416 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600420 :term:`BB_SCHEDULER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500421 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600434 :term:`BB_SCHEDULERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500435 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600441 :term:`BB_SETSCENE_DEPVALID`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500442 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600451 :term:`BB_SETSCENE_VERIFY_FUNCTION2`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500452 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600462 :term:`BB_SIGNATURE_EXCLUDE_FLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500463 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600472 :term:`BB_SIGNATURE_HANDLER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600481 :term:`BB_SRCREV_POLICY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500482 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600495 :term:`BB_STAMP_POLICY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500496 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600513 :term:`BB_STAMP_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500514 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600518 :term:`BB_STRICT_CHECKSUM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500519 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600524 :term:`BB_TASK_IONICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500525 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600556 $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500557
Andrew Geisslerf0343792020-11-18 10:42:21 -0600558 :term:`BB_TASK_NICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600567 :term:`BB_TASKHASH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568 Within an executing task, this variable holds the hash of the task as
569 returned by the currently enabled signature generator.
570
Andrew Geisslerf0343792020-11-18 10:42:21 -0600571 :term:`BB_VERBOSE_LOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500572 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600576 :term:`BB_WORKERCONTEXT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500577 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600582 :term:`BBCLASSEXTEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500583 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600614 :term:`BBDEBUG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500615 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600623 :term:`BBFILE_COLLECTIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500624 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600628 :term:`BBFILE_PATTERN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500629 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600635 :term:`BBFILE_PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500636 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600661 :term:`BBFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500662 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600670 :term:`BBINCLUDED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500671 Contains a space-separated list of all of all files that BitBake's
672 parser included during parsing of the current file.
673
Andrew Geisslerf0343792020-11-18 10:42:21 -0600674 :term:`BBINCLUDELOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500675 If set to a value, enables printing the task log when reporting a
676 failed task.
677
Andrew Geisslerf0343792020-11-18 10:42:21 -0600678 :term:`BBINCLUDELOGS_LINES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500679 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600684 :term:`BBLAYERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500685 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600699 :term:`BBLAYERS_FETCH_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500700 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600704 :term:`BBMASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500705 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600740 :term:`BBMULTICONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500741 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600761 :term:`BBPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500762 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600775 :term:`BBSERVER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500776 Points to the server that runs memory-resident BitBake. The variable
777 is only used when you employ memory-resident BitBake.
778
Andrew Geisslerf0343792020-11-18 10:42:21 -0600779 :term:`BBTARGETS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500780 Allows you to use a configuration file to add to the list of
781 command-line target recipes you want to build.
782
Andrew Geisslerf0343792020-11-18 10:42:21 -0600783 :term:`BBVERSIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500784 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600793 :term:`BITBAKE_UI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500794 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600802 :term:`BUILDNAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500803 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600806 :term:`BZRDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500807 The directory in which files checked out of a Bazaar system are
808 stored.
809
Andrew Geisslerf0343792020-11-18 10:42:21 -0600810 :term:`CACHE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500811 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600814 :term:`CVSDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500815 The directory in which files checked out under the CVS system are
816 stored.
817
Andrew Geisslerf0343792020-11-18 10:42:21 -0600818 :term:`DEFAULT_PREFERENCE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500819 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600833 :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500834 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600850 :term:`DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500851 A long description for the recipe.
852
Andrew Geisslerf0343792020-11-18 10:42:21 -0600853 :term:`DL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500854 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600859 :term:`EXCLUDE_FROM_WORLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500860 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600875 :term:`FAKEROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500876 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600881 :term:`FAKEROOTBASEENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500882 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600886 :term:`FAKEROOTCMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500887 Contains the command that starts the bitbake-worker process in the
888 fakeroot environment.
889
Andrew Geisslerf0343792020-11-18 10:42:21 -0600890 :term:`FAKEROOTDIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500891 Lists directories to create before running a task in the fakeroot
892 environment.
893
Andrew Geisslerf0343792020-11-18 10:42:21 -0600894 :term:`FAKEROOTENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500895 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600900 :term:`FAKEROOTNOENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500901 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600906 :term:`FETCHCMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500907 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600911 :term:`FILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500912 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600917 :term:`FILESPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500918 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600924 :term:`GITDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500925 The directory in which a local copy of a Git repository is stored
926 when it is cloned.
927
Andrew Geisslerf0343792020-11-18 10:42:21 -0600928 :term:`HGDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500929 The directory in which files checked out of a Mercurial system are
930 stored.
931
Andrew Geisslerf0343792020-11-18 10:42:21 -0600932 :term:`HOMEPAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500933 Website where more information about the software the recipe is
934 building can be found.
935
Andrew Geisslerf0343792020-11-18 10:42:21 -0600936 :term:`INHERIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500937 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600946 :term:`LAYERDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500947 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600959 :term:`LAYERDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500960 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600965 :term:`LAYERDIR_RE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500966 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600972 :term:`LAYERVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500973 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600982 :term:`LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500983 The list of source licenses for the recipe.
984
Andrew Geisslerf0343792020-11-18 10:42:21 -0600985 :term:`MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500986 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
Andrew Geisslerf0343792020-11-18 10:42:21 -0600993 :term:`MULTI_PROVIDER_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500994 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001006 :term:`OVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001007 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001016 :term:`P4DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001017 The directory in which a local copy of a Perforce depot is stored
1018 when it is fetched.
1019
Andrew Geisslerf0343792020-11-18 10:42:21 -06001020 :term:`PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001021 The list of packages the recipe creates.
1022
Andrew Geisslerf0343792020-11-18 10:42:21 -06001023 :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001024 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001033 :term:`PE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001034 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001038 :term:`PERSISTENT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001039 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001044 :term:`PF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001045 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001049 :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001050 The recipe name.
1051
Andrew Geisslerf0343792020-11-18 10:42:21 -06001052 :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001053 The revision of the recipe.
1054
Andrew Geisslerf0343792020-11-18 10:42:21 -06001055 :term:`PREFERRED_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001056 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001066 :term:`PREFERRED_PROVIDERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001067 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001081 :term:`PREFERRED_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001082 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001103 :term:`PREMIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001104 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001125 :term:`PROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001126 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001154 :term:`PRSERV_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001155 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001165 :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001166 The version of the recipe.
1167
Andrew Geisslerf0343792020-11-18 10:42:21 -06001168 :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001169 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001209 :term:`REPODIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001210 The directory in which a local copy of a ``google-repo`` directory is
1211 stored when it is synced.
1212
Andrew Geisslerf0343792020-11-18 10:42:21 -06001213 :term:`RPROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001214 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001225 :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001226 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001252 :term:`SECTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001253 The section in which packages should be categorized.
1254
Andrew Geisslerf0343792020-11-18 10:42:21 -06001255 :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001256 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001319 :term:`SRCDATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001320 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001324 :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001325 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001332 :term:`SRCREV_FORMAT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001333 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001346 :term:`STAMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001347 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001351 :term:`STAMPCLEAN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001352 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001358 :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001359 A short summary for the recipe, which is 72 characters or less.
1360
Andrew Geisslerf0343792020-11-18 10:42:21 -06001361 :term:`SVNDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001362 The directory in which files checked out of a Subversion system are
1363 stored.
1364
Andrew Geisslerf0343792020-11-18 10:42:21 -06001365 :term:`T`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001366 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
Andrew Geisslerf0343792020-11-18 10:42:21 -06001370 :term:`TOPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001371 Points to the build directory. BitBake automatically sets this
1372 variable.