blob: 1bb55fc501717cf27df68660eef5f3abf0c49489 [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
Andrew Geisslerc9f78652020-09-18 14:11:35 -050026.. glossary::
Patrick Williams213cb262021-08-07 19:21:33 -050027 :sorted:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050028
Andrew Geisslerf0343792020-11-18 10:42:21 -060029 :term:`ASSUME_PROVIDED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050030 Lists recipe names (:term:`PN` values) BitBake does not
31 attempt to build. Instead, BitBake assumes these recipes have already
32 been built.
33
Patrick Williams213cb262021-08-07 19:21:33 -050034 In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native
Andrew Geisslerc9f78652020-09-18 14:11:35 -050035 tools that should not be built. An example is ``git-native``, which
36 when specified allows for the Git binary from the host to be used
37 rather than building ``git-native``.
38
Andrew Geissler95ac1b82021-03-31 14:34:31 -050039 :term:`AZ_SAS`
40 Azure Storage Shared Access Signature, when using the
41 :ref:`Azure Storage fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
42 This variable can be defined to be used by the fetcher to authenticate
43 and gain access to non-public artifacts.
44 ::
45
46 AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""
47
48 For more information see Microsoft's Azure Storage documentation at
49 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
50
51
Andrew Geisslerf0343792020-11-18 10:42:21 -060052 :term:`B`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050053 The directory in which BitBake executes functions during a recipe's
54 build process.
55
Andrew Geisslerf0343792020-11-18 10:42:21 -060056 :term:`BB_ALLOWED_NETWORKS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050057 Specifies a space-delimited list of hosts that the fetcher is allowed
58 to use to obtain the required source code. Following are
59 considerations surrounding this variable:
60
61 - This host list is only used if
62 :term:`BB_NO_NETWORK` is either not set or
63 set to "0".
64
65 - Limited support for the "``*``" wildcard character for matching
66 against the beginning of host names exists. For example, the
67 following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and
68 ``foo.git.gnu.org``. ::
69
70 BB_ALLOWED_NETWORKS = "\*.gnu.org"
71
72 .. important::
73
74 The use of the "``*``" character only works at the beginning of
75 a host name and it must be isolated from the remainder of the
76 host name. You cannot use the wildcard character in any other
77 location of the name or combined with the front part of the
78 name.
79
80 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
81 is not.
82
83 - Mirrors not in the host list are skipped and logged in debug.
84
85 - Attempts to access networks not in the host list cause a failure.
86
Patrick Williams213cb262021-08-07 19:21:33 -050087 Using :term:`BB_ALLOWED_NETWORKS` in conjunction with
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088 :term:`PREMIRRORS` is very useful. Adding the
Patrick Williams213cb262021-08-07 19:21:33 -050089 host you want to use to :term:`PREMIRRORS` results in the source code
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090 being fetched from an allowed location and avoids raising an error
91 when a host that is not allowed is in a
92 :term:`SRC_URI` statement. This is because the
Patrick Williams213cb262021-08-07 19:21:33 -050093 fetcher does not attempt to use the host listed in :term:`SRC_URI` after
94 a successful fetch from the :term:`PREMIRRORS` occurs.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050095
Patrick Williams0ca19cc2021-08-16 14:03:13 -050096 :term:`BB_CHECK_SSL_CERTS`
97 Specifies if SSL certificates should be checked when fetching. The default
98 value is ``1`` and certificates are not checked if the value is set to ``0``.
99
Andrew Geisslerf0343792020-11-18 10:42:21 -0600100 :term:`BB_CONSOLELOG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500101 Specifies the path to a log file into which BitBake's user interface
102 writes output during the build.
103
Andrew Geisslerf0343792020-11-18 10:42:21 -0600104 :term:`BB_CURRENTTASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500105 Contains the name of the currently running task. The name does not
106 include the ``do_`` prefix.
107
Andrew Geisslerf0343792020-11-18 10:42:21 -0600108 :term:`BB_DANGLINGAPPENDS_WARNONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500109 Defines how BitBake handles situations where an append file
110 (``.bbappend``) has no corresponding recipe file (``.bb``). This
111 condition often occurs when layers get out of sync (e.g. ``oe-core``
112 bumps a recipe version and the old recipe no longer exists and the
113 other layer has not been updated to the new version of the recipe
114 yet).
115
116 The default fatal behavior is safest because it is the sane reaction
117 given something is out of sync. It is important to realize when your
118 changes are no longer being applied.
119
Andrew Geisslerf0343792020-11-18 10:42:21 -0600120 :term:`BB_DEFAULT_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121 The default task to use when none is specified (e.g. with the ``-c``
122 command line option). The task name specified should not include the
123 ``do_`` prefix.
124
Andrew Geissler9b4d8b02021-02-19 12:26:16 -0600125 :term:`BB_DEFAULT_UMASK`
126 The default umask to apply to tasks if specified and no task specific
127 umask flag is set.
128
Andrew Geisslerf0343792020-11-18 10:42:21 -0600129 :term:`BB_DISKMON_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500130 Monitors disk space and available inodes during the build and allows
131 you to control the build based on these parameters.
132
133 Disk space monitoring is disabled by default. When setting this
Andrew Geisslerc926e172021-05-07 16:11:35 -0500134 variable, use the following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500135
136 BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]"
137
138 where:
139
140 <action> is:
141 ABORT: Immediately abort the build when
142 a threshold is broken.
143 STOPTASKS: Stop the build after the currently
144 executing tasks have finished when
145 a threshold is broken.
146 WARN: Issue a warning but continue the
147 build when a threshold is broken.
148 Subsequent warnings are issued as
149 defined by the
150 BB_DISKMON_WARNINTERVAL variable,
151 which must be defined.
152
153 <dir> is:
154 Any directory you choose. You can specify one or
155 more directories to monitor by separating the
156 groupings with a space. If two directories are
157 on the same device, only the first directory
158 is monitored.
159
160 <threshold> is:
161 Either the minimum available disk space,
162 the minimum number of free inodes, or
163 both. You must specify at least one. To
164 omit one or the other, simply omit the value.
165 Specify the threshold using G, M, K for Gbytes,
166 Mbytes, and Kbytes, respectively. If you do
167 not specify G, M, or K, Kbytes is assumed by
168 default. Do not use GB, MB, or KB.
169
Andrew Geisslerc926e172021-05-07 16:11:35 -0500170 Here are some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500171
172 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
173 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
174 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
175
176 The first example works only if you also set the
177 :term:`BB_DISKMON_WARNINTERVAL`
178 variable. This example causes the build system to immediately abort
179 when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or
180 the available free inodes drops below 100 Kbytes. Because two
181 directories are provided with the variable, the build system also
182 issues a warning when the disk space in the ``${SSTATE_DIR}``
183 directory drops below 1 Gbyte or the number of free inodes drops
184 below 100 Kbytes. Subsequent warnings are issued during intervals as
Patrick Williams213cb262021-08-07 19:21:33 -0500185 defined by the :term:`BB_DISKMON_WARNINTERVAL` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500186
187 The second example stops the build after all currently executing
188 tasks complete when the minimum disk space in the ``${TMPDIR}``
189 directory drops below 1 Gbyte. No disk monitoring occurs for the free
190 inodes in this case.
191
192 The final example immediately aborts the build when the number of
193 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
194 disk space monitoring for the directory itself occurs in this case.
195
Andrew Geisslerf0343792020-11-18 10:42:21 -0600196 :term:`BB_DISKMON_WARNINTERVAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197 Defines the disk space and free inode warning intervals.
198
Patrick Williams213cb262021-08-07 19:21:33 -0500199 If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500200 must also use the :term:`BB_DISKMON_DIRS`
201 variable and define its action as "WARN". During the build,
202 subsequent warnings are issued each time disk space or number of free
203 inodes further reduces by the respective interval.
204
Patrick Williams213cb262021-08-07 19:21:33 -0500205 If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
206 do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500207 monitoring interval defaults to the following:
208 BB_DISKMON_WARNINTERVAL = "50M,5K"
209
210 When specifying the variable in your configuration file, use the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500211 following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500212
213 BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>"
214
215 where:
216
217 <disk_space_interval> is:
218 An interval of memory expressed in either
219 G, M, or K for Gbytes, Mbytes, or Kbytes,
220 respectively. You cannot use GB, MB, or KB.
221
222 <disk_inode_interval> is:
223 An interval of free inodes expressed in either
224 G, M, or K for Gbytes, Mbytes, or Kbytes,
225 respectively. You cannot use GB, MB, or KB.
226
Andrew Geisslerc926e172021-05-07 16:11:35 -0500227 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500228
229 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
230 BB_DISKMON_WARNINTERVAL = "50M,5K"
231
232 These variables cause BitBake to
233 issue subsequent warnings each time the available disk space further
234 reduces by 50 Mbytes or the number of free inodes further reduces by
235 5 Kbytes in the ``${SSTATE_DIR}`` directory. Subsequent warnings
236 based on the interval occur each time a respective interval is
237 reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes).
238
Patrick Williams213cb262021-08-07 19:21:33 -0500239 :term:`BB_ENV_EXTRAWHITE`
240 Specifies an additional set of variables to allow through (whitelist)
241 from the external environment into BitBake's datastore. This list of
242 variables are on top of the internal list set in
243 :term:`BB_ENV_WHITELIST`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500244
245 .. note::
246
247 You must set this variable in the external environment in order
248 for it to work.
249
Patrick Williams213cb262021-08-07 19:21:33 -0500250 :term:`BB_ENV_WHITELIST`
251 Specifies the internal whitelist of variables to allow through from
252 the external environment into BitBake's datastore. If the value of
253 this variable is not specified (which is the default), the following
254 list is used: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`,
255 :term:`BB_ENV_WHITELIST`, and :term:`BB_ENV_EXTRAWHITE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500256
257 .. note::
258
259 You must set this variable in the external environment in order
260 for it to work.
261
Andrew Geisslerf0343792020-11-18 10:42:21 -0600262 :term:`BB_FETCH_PREMIRRORONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500263 When set to "1", causes BitBake's fetcher module to only search
264 :term:`PREMIRRORS` for files. BitBake will not
265 search the main :term:`SRC_URI` or
266 :term:`MIRRORS`.
267
Andrew Geisslerf0343792020-11-18 10:42:21 -0600268 :term:`BB_FILENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500269 Contains the filename of the recipe that owns the currently running
270 task. For example, if the ``do_fetch`` task that resides in the
Patrick Williams213cb262021-08-07 19:21:33 -0500271 ``my-recipe.bb`` is executing, the :term:`BB_FILENAME` variable contains
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500272 "/foo/path/my-recipe.bb".
273
Andrew Geisslerf0343792020-11-18 10:42:21 -0600274 :term:`BB_GENERATE_MIRROR_TARBALLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500275 Causes tarballs of the Git repositories, including the Git metadata,
276 to be placed in the :term:`DL_DIR` directory. Anyone
277 wishing to create a source mirror would want to enable this variable.
278
279 For performance reasons, creating and placing tarballs of the Git
280 repositories is not the default action by BitBake. ::
281
282 BB_GENERATE_MIRROR_TARBALLS = "1"
283
Andrew Geisslereff27472021-10-29 15:35:00 -0500284 :term:`BB_GENERATE_SHALLOW_TARBALLS`
285 Setting this variable to "1" when :term:`BB_GIT_SHALLOW` is also set to
286 "1" causes bitbake to generate shallow mirror tarballs when fetching git
287 repositories. The number of commits included in the shallow mirror
288 tarballs is controlled by :term:`BB_GIT_SHALLOW_DEPTH`.
289
290 If both :term:`BB_GIT_SHALLOW` and :term:`BB_GENERATE_MIRROR_TARBALLS` are
291 enabled, bitbake will generate shallow mirror tarballs by default for git
292 repositories. This separate variable exists so that shallow tarball
293 generation can be enabled without needing to also enable normal mirror
294 generation if it is not desired.
295
296 For example usage, see :term:`BB_GIT_SHALLOW`.
297
298 :term:`BB_GIT_SHALLOW`
299 Setting this variable to "1" enables the support for fetching, using and
300 generating mirror tarballs of `shallow git repositories <https://riptutorial.com/git/example/4584/shallow-clone>`_.
301 The external `git-make-shallow <https://git.openembedded.org/bitbake/tree/bin/git-make-shallow>`_
302 script is used for shallow mirror tarball creation.
303
304 When :term:`BB_GIT_SHALLOW` is enabled, bitbake will attempt to fetch a shallow
305 mirror tarball. If the shallow mirror tarball cannot be fetched, it will
306 try to fetch the full mirror tarball and use that.
307
308 When a mirror tarball is not available, a full git clone will be performed
309 regardless of whether this variable is set or not. Support for shallow
310 clones is not currently implemented as git does not directly support
311 shallow cloning a particular git commit hash (it only supports cloning
312 from a tag or branch reference).
313
314 See also :term:`BB_GIT_SHALLOW_DEPTH` and
315 :term:`BB_GENERATE_SHALLOW_TARBALLS`.
316
317 Example usage::
318
319 BB_GIT_SHALLOW ?= "1"
320
321 # Keep only the top commit
322 BB_GIT_SHALLOW_DEPTH ?= "1"
323
324 # This defaults to enabled if both BB_GIT_SHALLOW and
325 # BB_GENERATE_MIRROR_TARBALLS are enabled
326 BB_GENERATE_SHALLOW_TARBALLS ?= "1"
327
328 :term:`BB_GIT_SHALLOW_DEPTH`
329 When used with :term:`BB_GENERATE_SHALLOW_TARBALLS`, this variable sets
330 the number of commits to include in generated shallow mirror tarballs.
331 With a depth of 1, only the commit referenced in :term:`SRCREV` is
332 included in the shallow mirror tarball. Increasing the depth includes
333 additional parent commits, working back through the commit history.
334
335 If this variable is unset, bitbake will default to a depth of 1 when
336 generating shallow mirror tarballs.
337
338 For example usage, see :term:`BB_GIT_SHALLOW`.
339
Andrew Geisslerf0343792020-11-18 10:42:21 -0600340 :term:`BB_HASHBASE_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500341 Lists variables that are excluded from checksum and dependency data.
342 Variables that are excluded can therefore change without affecting
343 the checksum mechanism. A common example would be the variable for
344 the path of the build. BitBake's output should not (and usually does
345 not) depend on the directory in which it was built.
346
Andrew Geisslerf0343792020-11-18 10:42:21 -0600347 :term:`BB_HASHCHECK_FUNCTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500348 Specifies the name of the function to call during the "setscene" part
349 of the task's execution in order to validate the list of task hashes.
350 The function returns the list of setscene tasks that should be
351 executed.
352
353 At this point in the execution of the code, the objective is to
354 quickly verify if a given setscene function is likely to work or not.
355 It's easier to check the list of setscene functions in one pass than
356 to call many individual tasks. The returned list need not be
357 completely accurate. A given setscene task can still later fail.
358 However, the more accurate the data returned, the more efficient the
359 build will be.
360
Patrick Williams213cb262021-08-07 19:21:33 -0500361 :term:`BB_HASHCONFIG_WHITELIST`
362 Lists variables that are excluded from base configuration checksum,
363 which is used to determine if the cache can be reused.
364
365 One of the ways BitBake determines whether to re-parse the main
366 metadata is through checksums of the variables in the datastore of
367 the base configuration data. There are variables that you typically
368 want to exclude when checking whether or not to re-parse and thus
369 rebuild the cache. As an example, you would usually exclude ``TIME``
370 and ``DATE`` because these variables are always changing. If you did
371 not exclude them, BitBake would never reuse the cache.
372
Andrew Geissler09036742021-06-25 14:25:14 -0500373 :term:`BB_HASHSERVE`
374 Specifies the Hash Equivalence server to use.
375
376 If set to ``auto``, BitBake automatically starts its own server
Andrew Geissler595f6302022-01-24 19:11:47 +0000377 over a UNIX domain socket. An option is to connect this server
378 to an upstream one, by setting :term:`BB_HASHSERVE_UPSTREAM`.
Andrew Geissler09036742021-06-25 14:25:14 -0500379
Andrew Geissler595f6302022-01-24 19:11:47 +0000380 If set to ``unix://path``, BitBake will connect to an existing
381 hash server available over a UNIX domain socket.
382
383 If set to ``host:port``, BitBake will connect to a remote server on the
Andrew Geissler09036742021-06-25 14:25:14 -0500384 specified host. This allows multiple clients to share the same
385 hash equivalence data.
386
Andrew Geissler595f6302022-01-24 19:11:47 +0000387 The remote server can be started manually through
388 the ``bin/bitbake-hashserv`` script provided by BitBake,
389 which supports UNIX domain sockets too. This script also allows
390 to start the server in read-only mode, to avoid accepting
391 equivalences that correspond to Share State caches that are
392 only available on specific clients.
393
394 :term:`BB_HASHSERVE_UPSTREAM`
395 Specifies an upstream Hash Equivalence server.
396
397 This optional setting is only useful when a local Hash Equivalence
398 server is started (setting :term:`BB_HASHSERVE` to ``auto``),
399 and you wish the local server to query an upstream server for
400 Hash Equivalence data.
401
402 Example usage::
403
404 BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687"
405
Andrew Geisslerf0343792020-11-18 10:42:21 -0600406 :term:`BB_INVALIDCONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500407 Used in combination with the ``ConfigParsed`` event to trigger
408 re-parsing the base metadata (i.e. all the recipes). The
409 ``ConfigParsed`` event can set the variable to trigger the re-parse.
410 You must be careful to avoid recursive loops with this functionality.
411
Andrew Geisslerf0343792020-11-18 10:42:21 -0600412 :term:`BB_LOGCONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500413 Specifies the name of a config file that contains the user logging
414 configuration. See
415 :ref:`bitbake-user-manual/bitbake-user-manual-execution:logging`
416 for additional information
417
Andrew Geisslerf0343792020-11-18 10:42:21 -0600418 :term:`BB_LOGFMT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500419 Specifies the name of the log files saved into
Patrick Williams213cb262021-08-07 19:21:33 -0500420 ``${``\ :term:`T`\ ``}``. By default, the :term:`BB_LOGFMT`
Andrew Geissler5199d832021-09-24 16:47:35 -0500421 variable is undefined and the log filenames get created using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500422 following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500423
424 log.{task}.{pid}
425
426 If you want to force log files to take a specific name, you can set this
427 variable in a configuration file.
428
Andrew Geisslerf0343792020-11-18 10:42:21 -0600429 :term:`BB_NICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500430 Allows BitBake to run at a specific priority (i.e. nice level).
431 System permissions usually mean that BitBake can reduce its priority
432 but not raise it again. See :term:`BB_TASK_NICE_LEVEL` for
433 additional information.
434
Andrew Geisslerf0343792020-11-18 10:42:21 -0600435 :term:`BB_NO_NETWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500436 Disables network access in the BitBake fetcher modules. With this
437 access disabled, any command that attempts to access the network
438 becomes an error.
439
440 Disabling network access is useful for testing source mirrors,
441 running builds when not connected to the Internet, and when operating
442 in certain kinds of firewall environments.
443
Patrick Williams213cb262021-08-07 19:21:33 -0500444 :term:`BB_NUMBER_PARSE_THREADS`
445 Sets the number of threads BitBake uses when parsing. By default, the
446 number of threads is equal to the number of cores on the system.
447
Andrew Geisslerf0343792020-11-18 10:42:21 -0600448 :term:`BB_NUMBER_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500449 The maximum number of tasks BitBake should run in parallel at any one
450 time. If your host development system supports multiple cores, a good
451 rule of thumb is to set this variable to twice the number of cores.
452
Andrew Geisslerf0343792020-11-18 10:42:21 -0600453 :term:`BB_ORIGENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500454 Contains a copy of the original external environment in which BitBake
455 was run. The copy is taken before any whitelisted variable values are
456 filtered into BitBake's datastore.
457
458 .. note::
459
460 The contents of this variable is a datastore object that can be
461 queried using the normal datastore operations.
462
Andrew Geisslerf0343792020-11-18 10:42:21 -0600463 :term:`BB_PRESERVE_ENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500464 Disables whitelisting and instead allows all variables through from
465 the external environment into BitBake's datastore.
466
467 .. note::
468
469 You must set this variable in the external environment in order
470 for it to work.
471
Andrew Geisslerf0343792020-11-18 10:42:21 -0600472 :term:`BB_RUNFMT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473 Specifies the name of the executable script files (i.e. run files)
474 saved into ``${``\ :term:`T`\ ``}``. By default, the
Andrew Geissler5199d832021-09-24 16:47:35 -0500475 :term:`BB_RUNFMT` variable is undefined and the run filenames get
Andrew Geisslerc926e172021-05-07 16:11:35 -0500476 created using the following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500477
478 run.{task}.{pid}
479
480 If you want to force run files to take a specific name, you can set this
481 variable in a configuration file.
482
Andrew Geisslerf0343792020-11-18 10:42:21 -0600483 :term:`BB_RUNTASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500484 Contains the name of the currently executing task. The value includes
485 the "do\_" prefix. For example, if the currently executing task is
486 ``do_config``, the value is "do_config".
487
Andrew Geisslerf0343792020-11-18 10:42:21 -0600488 :term:`BB_SCHEDULER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500489 Selects the name of the scheduler to use for the scheduling of
490 BitBake tasks. Three options exist:
491
492 - *basic* - The basic framework from which everything derives. Using
493 this option causes tasks to be ordered numerically as they are
494 parsed.
495
496 - *speed* - Executes tasks first that have more tasks depending on
497 them. The "speed" option is the default.
498
499 - *completion* - Causes the scheduler to try to complete a given
500 recipe once its build has started.
501
Andrew Geisslerf0343792020-11-18 10:42:21 -0600502 :term:`BB_SCHEDULERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503 Defines custom schedulers to import. Custom schedulers need to be
504 derived from the ``RunQueueScheduler`` class.
505
506 For information how to select a scheduler, see the
507 :term:`BB_SCHEDULER` variable.
508
Andrew Geisslerf0343792020-11-18 10:42:21 -0600509 :term:`BB_SETSCENE_DEPVALID`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500510 Specifies a function BitBake calls that determines whether BitBake
511 requires a setscene dependency to be met.
512
513 When running a setscene task, BitBake needs to know which
514 dependencies of that setscene task also need to be run. Whether
515 dependencies also need to be run is highly dependent on the metadata.
516 The function specified by this variable returns a "True" or "False"
517 depending on whether the dependency needs to be met.
518
Andrew Geisslerf0343792020-11-18 10:42:21 -0600519 :term:`BB_SIGNATURE_EXCLUDE_FLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500520 Lists variable flags (varflags) that can be safely excluded from
521 checksum and dependency data for keys in the datastore. When
522 generating checksum or dependency data for keys in the datastore, the
523 flags set against that key are normally included in the checksum.
524
525 For more information on varflags, see the
526 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`"
527 section.
528
Andrew Geisslerf0343792020-11-18 10:42:21 -0600529 :term:`BB_SIGNATURE_HANDLER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500530 Defines the name of the signature handler BitBake uses. The signature
531 handler defines the way stamp files are created and handled, if and
532 how the signature is incorporated into the stamps, and how the
533 signature itself is generated.
534
535 A new signature handler can be added by injecting a class derived
536 from the ``SignatureGenerator`` class into the global namespace.
537
Andrew Geisslerf0343792020-11-18 10:42:21 -0600538 :term:`BB_SRCREV_POLICY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500539 Defines the behavior of the fetcher when it interacts with source
540 control systems and dynamic source revisions. The
Patrick Williams213cb262021-08-07 19:21:33 -0500541 :term:`BB_SRCREV_POLICY` variable is useful when working without a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500542 network.
543
544 The variable can be set using one of two policies:
545
546 - *cache* - Retains the value the system obtained previously rather
547 than querying the source control system each time.
548
549 - *clear* - Queries the source controls system every time. With this
550 policy, there is no cache. The "clear" policy is the default.
551
Andrew Geisslerf0343792020-11-18 10:42:21 -0600552 :term:`BB_STRICT_CHECKSUM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500553 Sets a more strict checksum mechanism for non-local URLs. Setting
554 this variable to a value causes BitBake to report an error if it
555 encounters a non-local URL that does not have at least one checksum
556 specified.
557
Andrew Geisslerf0343792020-11-18 10:42:21 -0600558 :term:`BB_TASK_IONICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559 Allows adjustment of a task's Input/Output priority. During
560 Autobuilder testing, random failures can occur for tasks due to I/O
561 starvation. These failures occur during various QEMU runtime
Patrick Williams213cb262021-08-07 19:21:33 -0500562 timeouts. You can use the :term:`BB_TASK_IONICE_LEVEL` variable to adjust
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500563 the I/O priority of these tasks.
564
565 .. note::
566
567 This variable works similarly to the :term:`BB_TASK_NICE_LEVEL`
568 variable except with a task's I/O priorities.
569
Andrew Geisslerc926e172021-05-07 16:11:35 -0500570 Set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500571
572 BB_TASK_IONICE_LEVEL = "class.prio"
573
574 For *class*, the default value is "2", which is a best effort. You can use
575 "1" for realtime and "3" for idle. If you want to use realtime, you
576 must have superuser privileges.
577
578 For *prio*, you can use any value from "0", which is the highest
579 priority, to "7", which is the lowest. The default value is "4". You
580 do not need any special privileges to use this range of priority
581 values.
582
583 .. note::
584
585 In order for your I/O priority settings to take effect, you need the
586 Completely Fair Queuing (CFQ) Scheduler selected for the backing block
587 device. To select the scheduler, use the following command form where
Andrew Geisslerc926e172021-05-07 16:11:35 -0500588 device is the device (e.g. sda, sdb, and so forth)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500589
Andrew Geisslerf0343792020-11-18 10:42:21 -0600590 $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500591
Andrew Geisslerf0343792020-11-18 10:42:21 -0600592 :term:`BB_TASK_NICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500593 Allows specific tasks to change their priority (i.e. nice level).
594
595 You can use this variable in combination with task overrides to raise
596 or lower priorities of specific tasks. For example, on the `Yocto
Andrew Geisslereff27472021-10-29 15:35:00 -0500597 Project <https://www.yoctoproject.org>`__ autobuilder, QEMU emulation
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500598 in images is given a higher priority as compared to build tasks to
599 ensure that images do not suffer timeouts on loaded systems.
600
Andrew Geisslerf0343792020-11-18 10:42:21 -0600601 :term:`BB_TASKHASH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500602 Within an executing task, this variable holds the hash of the task as
603 returned by the currently enabled signature generator.
604
Andrew Geisslerf0343792020-11-18 10:42:21 -0600605 :term:`BB_VERBOSE_LOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500606 Controls how verbose BitBake is during builds. If set, shell scripts
607 echo commands and shell script output appears on standard out
608 (stdout).
609
Andrew Geisslerf0343792020-11-18 10:42:21 -0600610 :term:`BB_WORKERCONTEXT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500611 Specifies if the current context is executing a task. BitBake sets
612 this variable to "1" when a task is being executed. The value is not
613 set when the task is in server context during parsing or event
614 handling.
615
Andrew Geisslerf0343792020-11-18 10:42:21 -0600616 :term:`BBCLASSEXTEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500617 Allows you to extend a recipe so that it builds variants of the
618 software. Some examples of these variants for recipes from the
619 OpenEmbedded-Core metadata are "natives" such as ``quilt-native``,
620 which is a copy of Quilt built to run on the build system; "crosses"
621 such as ``gcc-cross``, which is a compiler built to run on the build
622 machine but produces binaries that run on the target ``MACHINE``;
623 "nativesdk", which targets the SDK machine instead of ``MACHINE``;
624 and "mulitlibs" in the form "``multilib:``\ multilib_name".
625
626 To build a different variant of the recipe with a minimal amount of
627 code, it usually is as simple as adding the variable to your recipe.
628 Here are two examples. The "native" variants are from the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500629 OpenEmbedded-Core metadata::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500630
631 BBCLASSEXTEND =+ "native nativesdk"
632 BBCLASSEXTEND =+ "multilib:multilib_name"
633
634 .. note::
635
Patrick Williams213cb262021-08-07 19:21:33 -0500636 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500637 variants by rewriting variable values and applying overrides such
638 as ``_class-native``. For example, to generate a native version of
639 a recipe, a :term:`DEPENDS` on "foo" is
Patrick Williams213cb262021-08-07 19:21:33 -0500640 rewritten to a :term:`DEPENDS` on "foo-native".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500641
Patrick Williams213cb262021-08-07 19:21:33 -0500642 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500643 Parsing once adds some limitations. For example, it is not
644 possible to include a different file depending on the variant,
645 since ``include`` statements are processed when the recipe is
646 parsed.
647
Andrew Geisslerf0343792020-11-18 10:42:21 -0600648 :term:`BBDEBUG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500649 Sets the BitBake debug output level to a specific value as
650 incremented by the ``-D`` command line option.
651
652 .. note::
653
654 You must set this variable in the external environment in order
655 for it to work.
656
Andrew Geisslerf0343792020-11-18 10:42:21 -0600657 :term:`BBFILE_COLLECTIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500658 Lists the names of configured layers. These names are used to find
659 the other ``BBFILE_*`` variables. Typically, each layer appends its
660 name to this variable in its ``conf/layer.conf`` file.
661
Andrew Geisslerf0343792020-11-18 10:42:21 -0600662 :term:`BBFILE_PATTERN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500663 Variable that expands to match files from
664 :term:`BBFILES` in a particular layer. This
665 variable is used in the ``conf/layer.conf`` file and must be suffixed
666 with the name of the specific layer (e.g.
667 ``BBFILE_PATTERN_emenlow``).
668
Andrew Geisslerf0343792020-11-18 10:42:21 -0600669 :term:`BBFILE_PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500670 Assigns the priority for recipe files in each layer.
671
672 This variable is useful in situations where the same recipe appears
673 in more than one layer. Setting this variable allows you to
674 prioritize a layer against other layers that contain the same recipe
675 - effectively letting you control the precedence for the multiple
676 layers. The precedence established through this variable stands
677 regardless of a recipe's version (:term:`PV` variable).
Patrick Williams213cb262021-08-07 19:21:33 -0500678 For example, a layer that has a recipe with a higher :term:`PV` value but
679 for which the :term:`BBFILE_PRIORITY` is set to have a lower precedence
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500680 still has a lower precedence.
681
Patrick Williams213cb262021-08-07 19:21:33 -0500682 A larger value for the :term:`BBFILE_PRIORITY` variable results in a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500683 higher precedence. For example, the value 6 has a higher precedence
Patrick Williams213cb262021-08-07 19:21:33 -0500684 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
685 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500686 for more information. The default priority, if unspecified for a
687 layer with no dependencies, is the lowest defined priority + 1 (or 1
688 if no priorities are defined).
689
690 .. tip::
691
692 You can use the command bitbake-layers show-layers to list all
693 configured layers along with their priorities.
694
Andrew Geisslerf0343792020-11-18 10:42:21 -0600695 :term:`BBFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500696 A space-separated list of recipe files BitBake uses to build
697 software.
698
699 When specifying recipe files, you can pattern match using Python's
700 `glob <https://docs.python.org/3/library/glob.html>`_ syntax.
701 For details on the syntax, see the documentation by following the
702 previous link.
703
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500704 :term:`BBFILES_DYNAMIC`
705 Activates content depending on presence of identified layers. You
706 identify the layers by the collections that the layers define.
707
Patrick Williams213cb262021-08-07 19:21:33 -0500708 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files whose
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500709 corresponding ``.bb`` file is in a layer that attempts to modify other
710 layers through ``.bbappend`` but does not want to introduce a hard
711 dependency on those other layers.
712
713 Additionally you can prefix the rule with "!" to add ``.bbappend`` and
714 ``.bb`` files in case a layer is not present. Use this avoid hard
715 dependency on those other layers.
716
Patrick Williams213cb262021-08-07 19:21:33 -0500717 Use the following form for :term:`BBFILES_DYNAMIC`::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500718
719 collection_name:filename_pattern
720
721 The following example identifies two collection names and two filename
Andrew Geisslerc926e172021-05-07 16:11:35 -0500722 patterns::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500723
724 BBFILES_DYNAMIC += "\
725 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
726 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
727 "
728
729 When the collection name is prefixed with "!" it will add the file pattern in case
Andrew Geisslerc926e172021-05-07 16:11:35 -0500730 the layer is absent::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500731
732 BBFILES_DYNAMIC += "\
733 !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \
734 "
735
736 This next example shows an error message that occurs because invalid
Andrew Geisslerc926e172021-05-07 16:11:35 -0500737 entries are found, which cause parsing to abort::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500738
739 ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not:
740 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
741 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
742
Andrew Geisslerf0343792020-11-18 10:42:21 -0600743 :term:`BBINCLUDED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500744 Contains a space-separated list of all of all files that BitBake's
745 parser included during parsing of the current file.
746
Andrew Geisslerf0343792020-11-18 10:42:21 -0600747 :term:`BBINCLUDELOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500748 If set to a value, enables printing the task log when reporting a
749 failed task.
750
Andrew Geisslerf0343792020-11-18 10:42:21 -0600751 :term:`BBINCLUDELOGS_LINES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500752 If :term:`BBINCLUDELOGS` is set, specifies
753 the maximum number of lines from the task log file to print when
Patrick Williams213cb262021-08-07 19:21:33 -0500754 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500755 the entire log is printed.
756
Andrew Geisslerf0343792020-11-18 10:42:21 -0600757 :term:`BBLAYERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500758 Lists the layers to enable during the build. This variable is defined
759 in the ``bblayers.conf`` configuration file in the build directory.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500760 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500761
762 BBLAYERS = " \
763 /home/scottrif/poky/meta \
764 /home/scottrif/poky/meta-yocto \
765 /home/scottrif/poky/meta-yocto-bsp \
766 /home/scottrif/poky/meta-mykernel \
767 "
768
769 This example enables four layers, one of which is a custom, user-defined
770 layer named ``meta-mykernel``.
771
Andrew Geisslerf0343792020-11-18 10:42:21 -0600772 :term:`BBLAYERS_FETCH_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500773 Sets the base location where layers are stored. This setting is used
774 in conjunction with ``bitbake-layers layerindex-fetch`` and tells
775 ``bitbake-layers`` where to place the fetched layers.
776
Andrew Geisslerf0343792020-11-18 10:42:21 -0600777 :term:`BBMASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500778 Prevents BitBake from processing recipes and recipe append files.
779
Patrick Williams213cb262021-08-07 19:21:33 -0500780 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500781 ``.bbappend`` files. BitBake ignores any recipe or recipe append
782 files that match any of the expressions. It is as if BitBake does not
783 see them at all. Consequently, matching files are not parsed or
784 otherwise used by BitBake.
785
786 The values you provide are passed to Python's regular expression
787 compiler. Consequently, the syntax follows Python's Regular
788 Expression (re) syntax. The expressions are compared against the full
789 paths to the files. For complete syntax information, see Python's
790 documentation at http://docs.python.org/3/library/re.html.
791
792 The following example uses a complete regular expression to tell
793 BitBake to ignore all recipe and recipe append files in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500794 ``meta-ti/recipes-misc/`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500795
796 BBMASK = "meta-ti/recipes-misc/"
797
798 If you want to mask out multiple directories or recipes, you can
799 specify multiple regular expression fragments. This next example
Andrew Geisslerc926e172021-05-07 16:11:35 -0500800 masks out multiple directories and individual recipes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500801
802 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
803 BBMASK += "/meta-oe/recipes-support/"
804 BBMASK += "/meta-foo/.*/openldap"
805 BBMASK += "opencv.*\.bbappend"
806 BBMASK += "lzma"
807
808 .. note::
809
810 When specifying a directory name, use the trailing slash character
811 to ensure you match just that directory name.
812
Andrew Geisslerf0343792020-11-18 10:42:21 -0600813 :term:`BBMULTICONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500814 Enables BitBake to perform multiple configuration builds and lists
815 each separate configuration (multiconfig). You can use this variable
816 to cause BitBake to build multiple targets where each target has a
Patrick Williams213cb262021-08-07 19:21:33 -0500817 separate configuration. Define :term:`BBMULTICONFIG` in your
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500818 ``conf/local.conf`` configuration file.
819
820 As an example, the following line specifies three multiconfigs, each
Andrew Geisslerc926e172021-05-07 16:11:35 -0500821 having a separate configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500822
823 BBMULTIFONFIG = "configA configB configC"
824
825 Each configuration file you use must reside in the
826 build directory within a directory named ``conf/multiconfig`` (e.g.
827 build_directory\ ``/conf/multiconfig/configA.conf``).
828
Patrick Williams213cb262021-08-07 19:21:33 -0500829 For information on how to use :term:`BBMULTICONFIG` in an environment
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500830 that supports building targets with multiple configurations, see the
831 ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`"
832 section.
833
Andrew Geisslerf0343792020-11-18 10:42:21 -0600834 :term:`BBPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500835 Used by BitBake to locate class (``.bbclass``) and configuration
836 (``.conf``) files. This variable is analogous to the ``PATH``
837 variable.
838
839 If you run BitBake from a directory outside of the build directory,
Patrick Williams213cb262021-08-07 19:21:33 -0500840 you must be sure to set :term:`BBPATH` to point to the build directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500841 Set the variable as you would any environment variable and then run
Andrew Geisslerc926e172021-05-07 16:11:35 -0500842 BitBake::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500843
844 $ BBPATH="build_directory"
845 $ export BBPATH
846 $ bitbake target
847
Andrew Geisslerf0343792020-11-18 10:42:21 -0600848 :term:`BBSERVER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500849 Points to the server that runs memory-resident BitBake. The variable
850 is only used when you employ memory-resident BitBake.
851
Andrew Geisslerf0343792020-11-18 10:42:21 -0600852 :term:`BBTARGETS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500853 Allows you to use a configuration file to add to the list of
854 command-line target recipes you want to build.
855
Andrew Geisslerf0343792020-11-18 10:42:21 -0600856 :term:`BITBAKE_UI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500857 Used to specify the UI module to use when running BitBake. Using this
858 variable is equivalent to using the ``-u`` command-line option.
859
860 .. note::
861
862 You must set this variable in the external environment in order
863 for it to work.
864
Andrew Geisslerf0343792020-11-18 10:42:21 -0600865 :term:`BUILDNAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500866 A name assigned to the build. The name defaults to a datetime stamp
867 of when the build was started but can be defined by the metadata.
868
Andrew Geisslerf0343792020-11-18 10:42:21 -0600869 :term:`BZRDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500870 The directory in which files checked out of a Bazaar system are
871 stored.
872
Andrew Geisslerf0343792020-11-18 10:42:21 -0600873 :term:`CACHE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500874 Specifies the directory BitBake uses to store a cache of the metadata
875 so it does not need to be parsed every time BitBake is started.
876
Andrew Geisslerf0343792020-11-18 10:42:21 -0600877 :term:`CVSDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500878 The directory in which files checked out under the CVS system are
879 stored.
880
Andrew Geisslerf0343792020-11-18 10:42:21 -0600881 :term:`DEFAULT_PREFERENCE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500882 Specifies a weak bias for recipe selection priority.
883
884 The most common usage of this is variable is to set it to "-1" within
885 a recipe for a development version of a piece of software. Using the
886 variable in this way causes the stable version of the recipe to build
Patrick Williams213cb262021-08-07 19:21:33 -0500887 by default in the absence of :term:`PREFERRED_VERSION` being used to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500888 build the development version.
889
890 .. note::
891
892 The bias provided by DEFAULT_PREFERENCE is weak and is overridden by
893 :term:`BBFILE_PRIORITY` if that variable is different between two
894 layers that contain different versions of the same recipe.
895
Andrew Geisslerf0343792020-11-18 10:42:21 -0600896 :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500897 Lists a recipe's build-time dependencies (i.e. other recipe files).
898
899 Consider this simple example for two recipes named "a" and "b" that
Patrick Williams213cb262021-08-07 19:21:33 -0500900 produce similarly named packages. In this example, the :term:`DEPENDS`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500901 statement appears in the "a" recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500902
903 DEPENDS = "b"
904
905 Here, the dependency is such that the ``do_configure`` task for recipe "a"
906 depends on the ``do_populate_sysroot`` task of recipe "b". This means
907 anything that recipe "b" puts into sysroot is available when recipe "a" is
908 configuring itself.
909
910 For information on runtime dependencies, see the :term:`RDEPENDS`
911 variable.
912
Andrew Geisslerf0343792020-11-18 10:42:21 -0600913 :term:`DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500914 A long description for the recipe.
915
Andrew Geisslerf0343792020-11-18 10:42:21 -0600916 :term:`DL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500917 The central download directory used by the build process to store
Patrick Williams213cb262021-08-07 19:21:33 -0500918 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500919 everything except Git repositories. If you want tarballs of Git
920 repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable.
921
Andrew Geisslerf0343792020-11-18 10:42:21 -0600922 :term:`EXCLUDE_FROM_WORLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500923 Directs BitBake to exclude a recipe from world builds (i.e.
924 ``bitbake world``). During world builds, BitBake locates, parses and
925 builds all recipes found in every layer exposed in the
926 ``bblayers.conf`` configuration file.
927
928 To exclude a recipe from a world build using this variable, set the
929 variable to "1" in the recipe.
930
931 .. note::
932
Patrick Williams213cb262021-08-07 19:21:33 -0500933 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a world
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500934 build in order to satisfy dependencies of other recipes. Adding a
Patrick Williams213cb262021-08-07 19:21:33 -0500935 recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500936 explicitly added to the list of build targets in a world build.
937
Andrew Geisslerf0343792020-11-18 10:42:21 -0600938 :term:`FAKEROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500939 Contains the command to use when running a shell script in a fakeroot
Patrick Williams213cb262021-08-07 19:21:33 -0500940 environment. The :term:`FAKEROOT` variable is obsolete and has been
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500941 replaced by the other ``FAKEROOT*`` variables. See these entries in
942 the glossary for more information.
943
Andrew Geisslerf0343792020-11-18 10:42:21 -0600944 :term:`FAKEROOTBASEENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500945 Lists environment variables to set when executing the command defined
946 by :term:`FAKEROOTCMD` that starts the
947 bitbake-worker process in the fakeroot environment.
948
Andrew Geisslerf0343792020-11-18 10:42:21 -0600949 :term:`FAKEROOTCMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500950 Contains the command that starts the bitbake-worker process in the
951 fakeroot environment.
952
Andrew Geisslerf0343792020-11-18 10:42:21 -0600953 :term:`FAKEROOTDIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500954 Lists directories to create before running a task in the fakeroot
955 environment.
956
Andrew Geisslerf0343792020-11-18 10:42:21 -0600957 :term:`FAKEROOTENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500958 Lists environment variables to set when running a task in the
959 fakeroot environment. For additional information on environment
960 variables and the fakeroot environment, see the
961 :term:`FAKEROOTBASEENV` variable.
962
Andrew Geisslerf0343792020-11-18 10:42:21 -0600963 :term:`FAKEROOTNOENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500964 Lists environment variables to set when running a task that is not in
965 the fakeroot environment. For additional information on environment
966 variables and the fakeroot environment, see the
967 :term:`FAKEROOTENV` variable.
968
Andrew Geisslerf0343792020-11-18 10:42:21 -0600969 :term:`FETCHCMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500970 Defines the command the BitBake fetcher module executes when running
971 fetch operations. You need to use an override suffix when you use the
972 variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``).
973
Andrew Geisslerf0343792020-11-18 10:42:21 -0600974 :term:`FILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500975 Points at the current file. BitBake sets this variable during the
976 parsing process to identify the file being parsed. BitBake also sets
977 this variable when a recipe is being executed to identify the recipe
978 file.
979
Andrew Geisslerf0343792020-11-18 10:42:21 -0600980 :term:`FILESPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500981 Specifies directories BitBake uses when searching for patches and
982 files. The "local" fetcher module uses these directories when
983 handling ``file://`` URLs. The variable behaves like a shell ``PATH``
984 environment variable. The value is a colon-separated list of
985 directories that are searched left-to-right in order.
986
Andrew Geisslerf0343792020-11-18 10:42:21 -0600987 :term:`GITDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500988 The directory in which a local copy of a Git repository is stored
989 when it is cloned.
990
Andrew Geisslerf0343792020-11-18 10:42:21 -0600991 :term:`HGDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500992 The directory in which files checked out of a Mercurial system are
993 stored.
994
Andrew Geisslerf0343792020-11-18 10:42:21 -0600995 :term:`HOMEPAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500996 Website where more information about the software the recipe is
997 building can be found.
998
Andrew Geisslerf0343792020-11-18 10:42:21 -0600999 :term:`INHERIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001000 Causes the named class or classes to be inherited globally. Anonymous
1001 functions in the class or classes are not executed for the base
1002 configuration and in each individual recipe. The OpenEmbedded build
Patrick Williams213cb262021-08-07 19:21:33 -05001003 system ignores changes to :term:`INHERIT` in individual recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001004
Patrick Williams213cb262021-08-07 19:21:33 -05001005 For more information on :term:`INHERIT`, see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001006 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
1007 section.
1008
Andrew Geisslerf0343792020-11-18 10:42:21 -06001009 :term:`LAYERDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001010 Lists the layers, separated by spaces, upon which this recipe
1011 depends. Optionally, you can specify a specific layer version for a
1012 dependency by adding it to the end of the layer name with a colon,
1013 (e.g. "anotherlayer:3" to be compared against
1014 :term:`LAYERVERSION`\ ``_anotherlayer`` in
1015 this case). BitBake produces an error if any dependency is missing or
1016 the version numbers do not match exactly (if specified).
1017
1018 You use this variable in the ``conf/layer.conf`` file. You must also
1019 use the specific layer name as a suffix to the variable (e.g.
1020 ``LAYERDEPENDS_mylayer``).
1021
Andrew Geisslerf0343792020-11-18 10:42:21 -06001022 :term:`LAYERDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001023 When used inside the ``layer.conf`` configuration file, this variable
1024 provides the path of the current layer. This variable is not
1025 available outside of ``layer.conf`` and references are expanded
1026 immediately when parsing of the file completes.
1027
Andrew Geisslerf0343792020-11-18 10:42:21 -06001028 :term:`LAYERDIR_RE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001029 When used inside the ``layer.conf`` configuration file, this variable
1030 provides the path of the current layer, escaped for use in a regular
1031 expression (:term:`BBFILE_PATTERN`). This
1032 variable is not available outside of ``layer.conf`` and references
1033 are expanded immediately when parsing of the file completes.
1034
Andrew Geisslerf0343792020-11-18 10:42:21 -06001035 :term:`LAYERVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001036 Optionally specifies the version of a layer as a single number. You
1037 can use this variable within
1038 :term:`LAYERDEPENDS` for another layer in
1039 order to depend on a specific version of the layer.
1040
1041 You use this variable in the ``conf/layer.conf`` file. You must also
1042 use the specific layer name as a suffix to the variable (e.g.
1043 ``LAYERDEPENDS_mylayer``).
1044
Andrew Geisslerf0343792020-11-18 10:42:21 -06001045 :term:`LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001046 The list of source licenses for the recipe.
1047
Andrew Geisslerf0343792020-11-18 10:42:21 -06001048 :term:`MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001049 Specifies additional paths from which BitBake gets source code. When
1050 the build system searches for source code, it first tries the local
1051 download directory. If that location fails, the build system tries
1052 locations defined by :term:`PREMIRRORS`, the
Patrick Williams213cb262021-08-07 19:21:33 -05001053 upstream source, and then locations specified by :term:`MIRRORS` in that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001054 order.
1055
Andrew Geisslerf0343792020-11-18 10:42:21 -06001056 :term:`MULTI_PROVIDER_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001057 Allows you to suppress BitBake warnings caused when building two
1058 separate recipes that provide the same output.
1059
1060 BitBake normally issues a warning when building two different recipes
1061 where each provides the same output. This scenario is usually
1062 something the user does not want. However, cases do exist where it
1063 makes sense, particularly in the ``virtual/*`` namespace. You can use
1064 this variable to suppress BitBake's warnings.
1065
1066 To use the variable, list provider names (e.g. recipe names,
1067 ``virtual/kernel``, and so forth).
1068
Andrew Geisslerf0343792020-11-18 10:42:21 -06001069 :term:`OVERRIDES`
Patrick Williams213cb262021-08-07 19:21:33 -05001070 BitBake uses :term:`OVERRIDES` to control what variables are overridden
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001071 after BitBake parses recipes and configuration files.
1072
1073 Following is a simple example that uses an overrides list based on
1074 machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
Patrick Williams213cb262021-08-07 19:21:33 -05001075 find information on how to use :term:`OVERRIDES` in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001076 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax
1077 (overrides)`" section.
1078
Andrew Geisslerf0343792020-11-18 10:42:21 -06001079 :term:`P4DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001080 The directory in which a local copy of a Perforce depot is stored
1081 when it is fetched.
1082
Andrew Geisslerf0343792020-11-18 10:42:21 -06001083 :term:`PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001084 The list of packages the recipe creates.
1085
Andrew Geisslerf0343792020-11-18 10:42:21 -06001086 :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001087 A promise that your recipe satisfies runtime dependencies for
1088 optional modules that are found in other recipes.
Patrick Williams213cb262021-08-07 19:21:33 -05001089 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001090 only states that they should be satisfied. For example, if a hard,
1091 runtime dependency (:term:`RDEPENDS`) of another
1092 package is satisfied during the build through the
Patrick Williams213cb262021-08-07 19:21:33 -05001093 :term:`PACKAGES_DYNAMIC` variable, but a package with the module name is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001094 never actually produced, then the other package will be broken.
1095
Andrew Geisslerf0343792020-11-18 10:42:21 -06001096 :term:`PE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001097 The epoch of the recipe. By default, this variable is unset. The
1098 variable is used to make upgrades possible when the versioning scheme
1099 changes in some backwards incompatible way.
1100
Andrew Geisslerf0343792020-11-18 10:42:21 -06001101 :term:`PERSISTENT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001102 Specifies the directory BitBake uses to store data that should be
1103 preserved between builds. In particular, the data stored is the data
1104 that uses BitBake's persistent data API and the data used by the PR
1105 Server and PR Service.
1106
Andrew Geisslerf0343792020-11-18 10:42:21 -06001107 :term:`PF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001108 Specifies the recipe or package name and includes all version and
1109 revision numbers (i.e. ``eglibc-2.13-r20+svnr15508/`` and
1110 ``bash-4.2-r1/``).
1111
Andrew Geisslerf0343792020-11-18 10:42:21 -06001112 :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001113 The recipe name.
1114
Andrew Geisslerf0343792020-11-18 10:42:21 -06001115 :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001116 The revision of the recipe.
1117
Andrew Geisslerf0343792020-11-18 10:42:21 -06001118 :term:`PREFERRED_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001119 Determines which recipe should be given preference when multiple
1120 recipes provide the same item. You should always suffix the variable
1121 with the name of the provided item, and you should set it to the
1122 :term:`PN` of the recipe to which you want to give
Andrew Geisslerc926e172021-05-07 16:11:35 -05001123 precedence. Some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001124
1125 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1126 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1127 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1128
Andrew Geisslerf0343792020-11-18 10:42:21 -06001129 :term:`PREFERRED_PROVIDERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001130 Determines which recipe should be given preference for cases where
1131 multiple recipes provide the same item. Functionally,
Patrick Williams213cb262021-08-07 19:21:33 -05001132 :term:`PREFERRED_PROVIDERS` is identical to
1133 :term:`PREFERRED_PROVIDER`. However, the :term:`PREFERRED_PROVIDERS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001134 lets you define preferences for multiple situations using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001135 form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001136
1137 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1138
Andrew Geisslerc926e172021-05-07 16:11:35 -05001139 This form is a convenient replacement for the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001140
1141 PREFERRED_PROVIDER_xxx = "yyy"
1142 PREFERRED_PROVIDER_aaa = "bbb"
1143
Andrew Geisslerf0343792020-11-18 10:42:21 -06001144 :term:`PREFERRED_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001145 If there are multiple versions of a recipe available, this variable
1146 determines which version should be given preference. You must always
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001147 suffix the variable with the :term:`PN` you want to
1148 select, and you should set :term:`PV` accordingly for
1149 precedence.
1150
Patrick Williams213cb262021-08-07 19:21:33 -05001151 The :term:`PREFERRED_VERSION` variable supports limited wildcard use
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001152 through the "``%``" character. You can use the character to match any
1153 number of characters, which can be useful when specifying versions
1154 that contain long revision numbers that potentially change. Here are
Andrew Geisslerc926e172021-05-07 16:11:35 -05001155 two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001156
1157 PREFERRED_VERSION_python = "2.7.3"
1158 PREFERRED_VERSION_linux-yocto = "4.12%"
1159
1160 .. important::
1161
1162 The use of the " % " character is limited in that it only works at the
1163 end of the string. You cannot use the wildcard character in any other
1164 location of the string.
1165
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001166 If a recipe with the specified version is not available, a warning
1167 message will be shown. See :term:`REQUIRED_VERSION` if you want this
1168 to be an error instead.
1169
Andrew Geisslerf0343792020-11-18 10:42:21 -06001170 :term:`PREMIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001171 Specifies additional paths from which BitBake gets source code. When
1172 the build system searches for source code, it first tries the local
1173 download directory. If that location fails, the build system tries
Patrick Williams213cb262021-08-07 19:21:33 -05001174 locations defined by :term:`PREMIRRORS`, the upstream source, and then
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001175 locations specified by :term:`MIRRORS` in that order.
1176
1177 Typically, you would add a specific server for the build system to
1178 attempt before any others by adding something like the following to
Andrew Geisslerc926e172021-05-07 16:11:35 -05001179 your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001180
Patrick Williams213cb262021-08-07 19:21:33 -05001181 PREMIRRORS:prepend = "\
Andrew Geisslereff27472021-10-29 15:35:00 -05001182 git://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
1183 ftp://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
1184 http://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
1185 https://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001186
1187 These changes cause the build system to intercept Git, FTP, HTTP, and
1188 HTTPS requests and direct them to the ``http://`` sources mirror. You can
1189 use ``file://`` URLs to point to local directories or network shares as
1190 well.
1191
Andrew Geisslerf0343792020-11-18 10:42:21 -06001192 :term:`PROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001193 A list of aliases by which a particular recipe can be known. By
Patrick Williams213cb262021-08-07 19:21:33 -05001194 default, a recipe's own :term:`PN` is implicitly already in its
1195 :term:`PROVIDES` list. If a recipe uses :term:`PROVIDES`, the additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001196 aliases are synonyms for the recipe and can be useful satisfying
1197 dependencies of other recipes during the build as specified by
Patrick Williams213cb262021-08-07 19:21:33 -05001198 :term:`DEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001199
Patrick Williams213cb262021-08-07 19:21:33 -05001200 Consider the following example :term:`PROVIDES` statement from a recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05001201 file ``libav_0.8.11.bb``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001202
1203 PROVIDES += "libpostproc"
1204
Patrick Williams213cb262021-08-07 19:21:33 -05001205 The :term:`PROVIDES` statement results in the "libav" recipe also being known
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001206 as "libpostproc".
1207
1208 In addition to providing recipes under alternate names, the
Patrick Williams213cb262021-08-07 19:21:33 -05001209 :term:`PROVIDES` mechanism is also used to implement virtual targets. A
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001210 virtual target is a name that corresponds to some particular
1211 functionality (e.g. a Linux kernel). Recipes that provide the
Patrick Williams213cb262021-08-07 19:21:33 -05001212 functionality in question list the virtual target in :term:`PROVIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001213 Recipes that depend on the functionality in question can include the
1214 virtual target in :term:`DEPENDS` to leave the
1215 choice of provider open.
1216
1217 Conventionally, virtual targets have names on the form
1218 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
1219 of the name and has no syntactical significance.
1220
Andrew Geisslerf0343792020-11-18 10:42:21 -06001221 :term:`PRSERV_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001222 The network based :term:`PR` service host and port.
1223
Patrick Williams213cb262021-08-07 19:21:33 -05001224 Following is an example of how the :term:`PRSERV_HOST` variable is set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001225
1226 PRSERV_HOST = "localhost:0"
1227
1228 You must set the variable if you want to automatically start a local PR
Patrick Williams213cb262021-08-07 19:21:33 -05001229 service. You can set :term:`PRSERV_HOST` to other values to use a remote PR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001230 service.
1231
Andrew Geisslerf0343792020-11-18 10:42:21 -06001232 :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001233 The version of the recipe.
1234
Andrew Geisslerf0343792020-11-18 10:42:21 -06001235 :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001236 Lists a package's runtime dependencies (i.e. other packages) that
1237 must be installed in order for the built package to run correctly. If
1238 a package in this list cannot be found during the build, you will get
1239 a build error.
1240
Patrick Williams213cb262021-08-07 19:21:33 -05001241 Because the :term:`RDEPENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001242 you should always use the variable in a form with an attached package
1243 name. For example, suppose you are building a development package
1244 that depends on the ``perl`` package. In this case, you would use the
Patrick Williams213cb262021-08-07 19:21:33 -05001245 following :term:`RDEPENDS` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001246
Patrick Williams213cb262021-08-07 19:21:33 -05001247 RDEPENDS:${PN}-dev += "perl"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001248
1249 In the example, the development package depends on the ``perl`` package.
Patrick Williams213cb262021-08-07 19:21:33 -05001250 Thus, the :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001251 of the variable.
1252
1253 BitBake supports specifying versioned dependencies. Although the
1254 syntax varies depending on the packaging format, BitBake hides these
1255 differences from you. Here is the general syntax to specify versions
Patrick Williams213cb262021-08-07 19:21:33 -05001256 with the :term:`RDEPENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001257
Patrick Williams213cb262021-08-07 19:21:33 -05001258 RDEPENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001259
Andrew Geisslerc926e172021-05-07 16:11:35 -05001260 For ``operator``, you can specify the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001261
1262 =
1263 <
1264 >
1265 <=
1266 >=
1267
1268 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05001269 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001270
Patrick Williams213cb262021-08-07 19:21:33 -05001271 RDEPENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001272
1273 For information on build-time dependencies, see the :term:`DEPENDS`
1274 variable.
1275
Andrew Geisslerf0343792020-11-18 10:42:21 -06001276 :term:`REPODIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001277 The directory in which a local copy of a ``google-repo`` directory is
1278 stored when it is synced.
1279
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001280 :term:`REQUIRED_VERSION`
1281 If there are multiple versions of a recipe available, this variable
Patrick Williams213cb262021-08-07 19:21:33 -05001282 determines which version should be given preference. :term:`REQUIRED_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001283 works in exactly the same manner as :term:`PREFERRED_VERSION`, except
1284 that if the specified version is not available then an error message
1285 is shown and the build fails immediately.
1286
Patrick Williams213cb262021-08-07 19:21:33 -05001287 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set for
1288 the same recipe, the :term:`REQUIRED_VERSION` value applies.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001289
Andrew Geisslerf0343792020-11-18 10:42:21 -06001290 :term:`RPROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001291 A list of package name aliases that a package also provides. These
1292 aliases are useful for satisfying runtime dependencies of other
1293 packages both during the build and on the target (as specified by
Patrick Williams213cb262021-08-07 19:21:33 -05001294 :term:`RDEPENDS`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001295
1296 As with all package-controlling variables, you must always use the
1297 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05001298 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001299
Patrick Williams213cb262021-08-07 19:21:33 -05001300 RPROVIDES:${PN} = "widget-abi-2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001301
Andrew Geisslerf0343792020-11-18 10:42:21 -06001302 :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001303 A list of packages that extends the usability of a package being
1304 built. The package being built does not depend on this list of
1305 packages in order to successfully build, but needs them for the
1306 extended usability. To specify runtime dependencies for packages, see
Patrick Williams213cb262021-08-07 19:21:33 -05001307 the :term:`RDEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001308
1309 BitBake supports specifying versioned recommends. Although the syntax
1310 varies depending on the packaging format, BitBake hides these
1311 differences from you. Here is the general syntax to specify versions
Patrick Williams213cb262021-08-07 19:21:33 -05001312 with the :term:`RRECOMMENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001313
Patrick Williams213cb262021-08-07 19:21:33 -05001314 RRECOMMENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001315
Andrew Geisslerc926e172021-05-07 16:11:35 -05001316 For ``operator``, you can specify the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001317
1318 =
1319 <
1320 >
1321 <=
1322 >=
1323
1324 For example, the following sets up a recommend on version
Andrew Geisslerc926e172021-05-07 16:11:35 -05001325 1.2 or greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001326
Patrick Williams213cb262021-08-07 19:21:33 -05001327 RRECOMMENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001328
Andrew Geisslerf0343792020-11-18 10:42:21 -06001329 :term:`SECTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001330 The section in which packages should be categorized.
1331
Andrew Geisslerf0343792020-11-18 10:42:21 -06001332 :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001333 The list of source files - local or remote. This variable tells
1334 BitBake which bits to pull for the build and how to pull them. For
1335 example, if the recipe or append file needs to fetch a single tarball
Andrew Geissler595f6302022-01-24 19:11:47 +00001336 from the Internet, the recipe or append file uses a :term:`SRC_URI`
1337 entry that specifies that tarball. On the other hand, if the recipe or
1338 append file needs to fetch a tarball, apply two patches, and include
1339 a custom file, the recipe or append file needs an :term:`SRC_URI`
1340 variable that specifies all those sources.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001341
Andrew Geissler595f6302022-01-24 19:11:47 +00001342 The following list explains the available URI protocols. URI
1343 protocols are highly dependent on particular BitBake Fetcher
1344 submodules. Depending on the fetcher BitBake uses, various URL
1345 parameters are employed. For specifics on the supported Fetchers, see
1346 the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`
1347 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001348
Andrew Geissler595f6302022-01-24 19:11:47 +00001349 - ``az://`` : Fetches files from an Azure Storage account using HTTPS.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001350
1351 - ``bzr://`` : Fetches files from a Bazaar revision control
1352 repository.
1353
Andrew Geissler595f6302022-01-24 19:11:47 +00001354 - ``ccrc://`` - Fetches files from a ClearCase repository.
1355
1356 - ``cvs://`` : Fetches files from a CVS revision control
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001357 repository.
1358
Andrew Geissler595f6302022-01-24 19:11:47 +00001359 - ``file://`` - Fetches files, which are usually files shipped
1360 with the Metadata, from the local machine.
1361 The path is relative to the :term:`FILESPATH`
1362 variable. Thus, the build system searches, in order, from the
1363 following directories, which are assumed to be a subdirectories of
1364 the directory in which the recipe file (``.bb``) or append file
1365 (``.bbappend``) resides:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001366
Andrew Geissler595f6302022-01-24 19:11:47 +00001367 - ``${BPN}`` - The base recipe name without any special suffix
1368 or version numbers.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001369
Andrew Geissler595f6302022-01-24 19:11:47 +00001370 - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and
1371 version but without any special package name suffix.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001372
Andrew Geissler595f6302022-01-24 19:11:47 +00001373 - *files -* Files within a directory, which is named ``files``
1374 and is also alongside the recipe or append file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001375
1376 - ``ftp://`` : Fetches files from the Internet using FTP.
1377
Andrew Geissler595f6302022-01-24 19:11:47 +00001378 - ``git://`` : Fetches files from a Git revision control
1379 repository.
1380
1381 - ``gitsm://`` : Fetches submodules from a Git revision control
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001382 repository.
1383
1384 - ``hg://`` : Fetches files from a Mercurial (``hg``) revision
1385 control repository.
1386
Andrew Geissler595f6302022-01-24 19:11:47 +00001387 - ``http://`` : Fetches files from the Internet using HTTP.
1388
1389 - ``https://`` : Fetches files from the Internet using HTTPS.
1390
1391 - ``npm://`` - Fetches JavaScript modules from a registry.
1392
1393 - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service)
1394 revision control repository.
1395
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001396 - ``p4://`` : Fetches files from a Perforce (``p4``) revision
1397 control repository.
1398
Andrew Geissler595f6302022-01-24 19:11:47 +00001399 - ``repo://`` : Fetches files from a repo (Git) repository.
1400
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001401 - ``ssh://`` : Fetches files from a secure shell.
1402
1403 - ``svn://`` : Fetches files from a Subversion (``svn``) revision
1404 control repository.
1405
1406 Here are some additional options worth mentioning:
1407
Andrew Geissler595f6302022-01-24 19:11:47 +00001408 - ``downloadfilename`` : Specifies the filename used when storing
1409 the downloaded file.
1410
1411 - ``name`` - Specifies a name to be used for association with
1412 :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one
1413 file or git repository specified in :term:`SRC_URI`. For example::
1414
1415 SRC_URI = "git://example.com/foo.git;name=first \
1416 git://example.com/bar.git;name=second \
1417 http://example.com/file.tar.gz;name=third"
1418
1419 SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"
1420 SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f"
1421 SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001422
1423 - ``subdir`` : Places the file (or extracts its contents) into the
1424 specified subdirectory. This option is useful for unusual tarballs
1425 or other archives that do not have their files already in a
1426 subdirectory within the archive.
1427
Andrew Geissler595f6302022-01-24 19:11:47 +00001428 - ``subpath`` - Limits the checkout to a specific subpath of the
1429 tree when using the Git fetcher is used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001430
Andrew Geissler595f6302022-01-24 19:11:47 +00001431 - ``unpack`` : Controls whether or not to unpack the file if it is
1432 an archive. The default action is to unpack the file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001433
Andrew Geisslerf0343792020-11-18 10:42:21 -06001434 :term:`SRCDATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001435 The date of the source code used to build the package. This variable
1436 applies only if the source was fetched from a Source Code Manager
1437 (SCM).
1438
Andrew Geisslerf0343792020-11-18 10:42:21 -06001439 :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001440 The revision of the source code used to build the package. This
1441 variable applies only when using Subversion, Git, Mercurial and
1442 Bazaar. If you want to build a fixed revision and you want to avoid
1443 performing a query on the remote repository every time BitBake parses
Patrick Williams213cb262021-08-07 19:21:33 -05001444 your recipe, you should specify a :term:`SRCREV` that is a full revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001445 identifier and not just a tag.
1446
Andrew Geisslerf0343792020-11-18 10:42:21 -06001447 :term:`SRCREV_FORMAT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001448 Helps construct valid :term:`SRCREV` values when
1449 multiple source controlled URLs are used in
1450 :term:`SRC_URI`.
1451
1452 The system needs help constructing these values under these
Patrick Williams213cb262021-08-07 19:21:33 -05001453 circumstances. Each component in the :term:`SRC_URI` is assigned a name
1454 and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001455 an example with URLs named "machine" and "meta". In this case,
Patrick Williams213cb262021-08-07 19:21:33 -05001456 :term:`SRCREV_FORMAT` could look like "machine_meta" and those names
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001457 would have the SCM versions substituted into each position. Only one
1458 ``AUTOINC`` placeholder is added and if needed. And, this placeholder
1459 is placed at the start of the returned string.
1460
Andrew Geisslerf0343792020-11-18 10:42:21 -06001461 :term:`STAMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001462 Specifies the base path used to create recipe stamp files. The path
1463 to an actual stamp file is constructed by evaluating this string and
1464 then appending additional information.
1465
Andrew Geisslerf0343792020-11-18 10:42:21 -06001466 :term:`STAMPCLEAN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001467 Specifies the base path used to create recipe stamp files. Unlike the
Patrick Williams213cb262021-08-07 19:21:33 -05001468 :term:`STAMP` variable, :term:`STAMPCLEAN` can contain
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001469 wildcards to match the range of files a clean operation should
1470 remove. BitBake uses a clean operation to remove any other stamps it
1471 should be removing when creating a new stamp.
1472
Andrew Geisslerf0343792020-11-18 10:42:21 -06001473 :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001474 A short summary for the recipe, which is 72 characters or less.
1475
Andrew Geisslerf0343792020-11-18 10:42:21 -06001476 :term:`SVNDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001477 The directory in which files checked out of a Subversion system are
1478 stored.
1479
Andrew Geisslerf0343792020-11-18 10:42:21 -06001480 :term:`T`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001481 Points to a directory were BitBake places temporary files, which
1482 consist mostly of task logs and scripts, when building a particular
1483 recipe.
1484
Andrew Geisslerf0343792020-11-18 10:42:21 -06001485 :term:`TOPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001486 Points to the build directory. BitBake automatically sets this
1487 variable.