blob: 2392ec42563f887452503b8708ba4e862135ef6e [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 Geisslerf0343792020-11-18 10:42:21 -0600284 :term:`BB_HASHBASE_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285 Lists variables that are excluded from checksum and dependency data.
286 Variables that are excluded can therefore change without affecting
287 the checksum mechanism. A common example would be the variable for
288 the path of the build. BitBake's output should not (and usually does
289 not) depend on the directory in which it was built.
290
Andrew Geisslerf0343792020-11-18 10:42:21 -0600291 :term:`BB_HASHCHECK_FUNCTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500292 Specifies the name of the function to call during the "setscene" part
293 of the task's execution in order to validate the list of task hashes.
294 The function returns the list of setscene tasks that should be
295 executed.
296
297 At this point in the execution of the code, the objective is to
298 quickly verify if a given setscene function is likely to work or not.
299 It's easier to check the list of setscene functions in one pass than
300 to call many individual tasks. The returned list need not be
301 completely accurate. A given setscene task can still later fail.
302 However, the more accurate the data returned, the more efficient the
303 build will be.
304
Patrick Williams213cb262021-08-07 19:21:33 -0500305 :term:`BB_HASHCONFIG_WHITELIST`
306 Lists variables that are excluded from base configuration checksum,
307 which is used to determine if the cache can be reused.
308
309 One of the ways BitBake determines whether to re-parse the main
310 metadata is through checksums of the variables in the datastore of
311 the base configuration data. There are variables that you typically
312 want to exclude when checking whether or not to re-parse and thus
313 rebuild the cache. As an example, you would usually exclude ``TIME``
314 and ``DATE`` because these variables are always changing. If you did
315 not exclude them, BitBake would never reuse the cache.
316
Andrew Geissler09036742021-06-25 14:25:14 -0500317 :term:`BB_HASHSERVE`
318 Specifies the Hash Equivalence server to use.
319
320 If set to ``auto``, BitBake automatically starts its own server
321 over a UNIX domain socket.
322
323 If set to ``host:port``, BitBake will use a remote server on the
324 specified host. This allows multiple clients to share the same
325 hash equivalence data.
326
Andrew Geisslerf0343792020-11-18 10:42:21 -0600327 :term:`BB_INVALIDCONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500328 Used in combination with the ``ConfigParsed`` event to trigger
329 re-parsing the base metadata (i.e. all the recipes). The
330 ``ConfigParsed`` event can set the variable to trigger the re-parse.
331 You must be careful to avoid recursive loops with this functionality.
332
Andrew Geisslerf0343792020-11-18 10:42:21 -0600333 :term:`BB_LOGCONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500334 Specifies the name of a config file that contains the user logging
335 configuration. See
336 :ref:`bitbake-user-manual/bitbake-user-manual-execution:logging`
337 for additional information
338
Andrew Geisslerf0343792020-11-18 10:42:21 -0600339 :term:`BB_LOGFMT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500340 Specifies the name of the log files saved into
Patrick Williams213cb262021-08-07 19:21:33 -0500341 ``${``\ :term:`T`\ ``}``. By default, the :term:`BB_LOGFMT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500342 variable is undefined and the log file names get created using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500343 following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500344
345 log.{task}.{pid}
346
347 If you want to force log files to take a specific name, you can set this
348 variable in a configuration file.
349
Andrew Geisslerf0343792020-11-18 10:42:21 -0600350 :term:`BB_NICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500351 Allows BitBake to run at a specific priority (i.e. nice level).
352 System permissions usually mean that BitBake can reduce its priority
353 but not raise it again. See :term:`BB_TASK_NICE_LEVEL` for
354 additional information.
355
Andrew Geisslerf0343792020-11-18 10:42:21 -0600356 :term:`BB_NO_NETWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500357 Disables network access in the BitBake fetcher modules. With this
358 access disabled, any command that attempts to access the network
359 becomes an error.
360
361 Disabling network access is useful for testing source mirrors,
362 running builds when not connected to the Internet, and when operating
363 in certain kinds of firewall environments.
364
Patrick Williams213cb262021-08-07 19:21:33 -0500365 :term:`BB_NUMBER_PARSE_THREADS`
366 Sets the number of threads BitBake uses when parsing. By default, the
367 number of threads is equal to the number of cores on the system.
368
Andrew Geisslerf0343792020-11-18 10:42:21 -0600369 :term:`BB_NUMBER_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500370 The maximum number of tasks BitBake should run in parallel at any one
371 time. If your host development system supports multiple cores, a good
372 rule of thumb is to set this variable to twice the number of cores.
373
Andrew Geisslerf0343792020-11-18 10:42:21 -0600374 :term:`BB_ORIGENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500375 Contains a copy of the original external environment in which BitBake
376 was run. The copy is taken before any whitelisted variable values are
377 filtered into BitBake's datastore.
378
379 .. note::
380
381 The contents of this variable is a datastore object that can be
382 queried using the normal datastore operations.
383
Andrew Geisslerf0343792020-11-18 10:42:21 -0600384 :term:`BB_PRESERVE_ENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385 Disables whitelisting and instead allows all variables through from
386 the external environment into BitBake's datastore.
387
388 .. note::
389
390 You must set this variable in the external environment in order
391 for it to work.
392
Andrew Geisslerf0343792020-11-18 10:42:21 -0600393 :term:`BB_RUNFMT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500394 Specifies the name of the executable script files (i.e. run files)
395 saved into ``${``\ :term:`T`\ ``}``. By default, the
Patrick Williams213cb262021-08-07 19:21:33 -0500396 :term:`BB_RUNFMT` variable is undefined and the run file names get
Andrew Geisslerc926e172021-05-07 16:11:35 -0500397 created using the following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500398
399 run.{task}.{pid}
400
401 If you want to force run files to take a specific name, you can set this
402 variable in a configuration file.
403
Andrew Geisslerf0343792020-11-18 10:42:21 -0600404 :term:`BB_RUNTASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500405 Contains the name of the currently executing task. The value includes
406 the "do\_" prefix. For example, if the currently executing task is
407 ``do_config``, the value is "do_config".
408
Andrew Geisslerf0343792020-11-18 10:42:21 -0600409 :term:`BB_SCHEDULER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500410 Selects the name of the scheduler to use for the scheduling of
411 BitBake tasks. Three options exist:
412
413 - *basic* - The basic framework from which everything derives. Using
414 this option causes tasks to be ordered numerically as they are
415 parsed.
416
417 - *speed* - Executes tasks first that have more tasks depending on
418 them. The "speed" option is the default.
419
420 - *completion* - Causes the scheduler to try to complete a given
421 recipe once its build has started.
422
Andrew Geisslerf0343792020-11-18 10:42:21 -0600423 :term:`BB_SCHEDULERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500424 Defines custom schedulers to import. Custom schedulers need to be
425 derived from the ``RunQueueScheduler`` class.
426
427 For information how to select a scheduler, see the
428 :term:`BB_SCHEDULER` variable.
429
Andrew Geisslerf0343792020-11-18 10:42:21 -0600430 :term:`BB_SETSCENE_DEPVALID`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500431 Specifies a function BitBake calls that determines whether BitBake
432 requires a setscene dependency to be met.
433
434 When running a setscene task, BitBake needs to know which
435 dependencies of that setscene task also need to be run. Whether
436 dependencies also need to be run is highly dependent on the metadata.
437 The function specified by this variable returns a "True" or "False"
438 depending on whether the dependency needs to be met.
439
Andrew Geisslerf0343792020-11-18 10:42:21 -0600440 :term:`BB_SIGNATURE_EXCLUDE_FLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500441 Lists variable flags (varflags) that can be safely excluded from
442 checksum and dependency data for keys in the datastore. When
443 generating checksum or dependency data for keys in the datastore, the
444 flags set against that key are normally included in the checksum.
445
446 For more information on varflags, see the
447 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`"
448 section.
449
Andrew Geisslerf0343792020-11-18 10:42:21 -0600450 :term:`BB_SIGNATURE_HANDLER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500451 Defines the name of the signature handler BitBake uses. The signature
452 handler defines the way stamp files are created and handled, if and
453 how the signature is incorporated into the stamps, and how the
454 signature itself is generated.
455
456 A new signature handler can be added by injecting a class derived
457 from the ``SignatureGenerator`` class into the global namespace.
458
Andrew Geisslerf0343792020-11-18 10:42:21 -0600459 :term:`BB_SRCREV_POLICY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500460 Defines the behavior of the fetcher when it interacts with source
461 control systems and dynamic source revisions. The
Patrick Williams213cb262021-08-07 19:21:33 -0500462 :term:`BB_SRCREV_POLICY` variable is useful when working without a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500463 network.
464
465 The variable can be set using one of two policies:
466
467 - *cache* - Retains the value the system obtained previously rather
468 than querying the source control system each time.
469
470 - *clear* - Queries the source controls system every time. With this
471 policy, there is no cache. The "clear" policy is the default.
472
Andrew Geisslerf0343792020-11-18 10:42:21 -0600473 :term:`BB_STAMP_POLICY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500474 Defines the mode used for how timestamps of stamp files are compared.
475 You can set the variable to one of the following modes:
476
477 - *perfile* - Timestamp comparisons are only made between timestamps
478 of a specific recipe. This is the default mode.
479
480 - *full* - Timestamp comparisons are made for all dependencies.
481
482 - *whitelist* - Identical to "full" mode except timestamp
483 comparisons are made for recipes listed in the
484 :term:`BB_STAMP_WHITELIST` variable.
485
486 .. note::
487
488 Stamp policies are largely obsolete with the introduction of
489 setscene tasks.
490
Andrew Geisslerf0343792020-11-18 10:42:21 -0600491 :term:`BB_STAMP_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500492 Lists files whose stamp file timestamps are compared when the stamp
493 policy mode is set to "whitelist". For information on stamp policies,
494 see the :term:`BB_STAMP_POLICY` variable.
495
Andrew Geisslerf0343792020-11-18 10:42:21 -0600496 :term:`BB_STRICT_CHECKSUM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500497 Sets a more strict checksum mechanism for non-local URLs. Setting
498 this variable to a value causes BitBake to report an error if it
499 encounters a non-local URL that does not have at least one checksum
500 specified.
501
Andrew Geisslerf0343792020-11-18 10:42:21 -0600502 :term:`BB_TASK_IONICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503 Allows adjustment of a task's Input/Output priority. During
504 Autobuilder testing, random failures can occur for tasks due to I/O
505 starvation. These failures occur during various QEMU runtime
Patrick Williams213cb262021-08-07 19:21:33 -0500506 timeouts. You can use the :term:`BB_TASK_IONICE_LEVEL` variable to adjust
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500507 the I/O priority of these tasks.
508
509 .. note::
510
511 This variable works similarly to the :term:`BB_TASK_NICE_LEVEL`
512 variable except with a task's I/O priorities.
513
Andrew Geisslerc926e172021-05-07 16:11:35 -0500514 Set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500515
516 BB_TASK_IONICE_LEVEL = "class.prio"
517
518 For *class*, the default value is "2", which is a best effort. You can use
519 "1" for realtime and "3" for idle. If you want to use realtime, you
520 must have superuser privileges.
521
522 For *prio*, you can use any value from "0", which is the highest
523 priority, to "7", which is the lowest. The default value is "4". You
524 do not need any special privileges to use this range of priority
525 values.
526
527 .. note::
528
529 In order for your I/O priority settings to take effect, you need the
530 Completely Fair Queuing (CFQ) Scheduler selected for the backing block
531 device. To select the scheduler, use the following command form where
Andrew Geisslerc926e172021-05-07 16:11:35 -0500532 device is the device (e.g. sda, sdb, and so forth)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500533
Andrew Geisslerf0343792020-11-18 10:42:21 -0600534 $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500535
Andrew Geisslerf0343792020-11-18 10:42:21 -0600536 :term:`BB_TASK_NICE_LEVEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500537 Allows specific tasks to change their priority (i.e. nice level).
538
539 You can use this variable in combination with task overrides to raise
540 or lower priorities of specific tasks. For example, on the `Yocto
541 Project <http://www.yoctoproject.org>`__ autobuilder, QEMU emulation
542 in images is given a higher priority as compared to build tasks to
543 ensure that images do not suffer timeouts on loaded systems.
544
Andrew Geisslerf0343792020-11-18 10:42:21 -0600545 :term:`BB_TASKHASH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500546 Within an executing task, this variable holds the hash of the task as
547 returned by the currently enabled signature generator.
548
Andrew Geisslerf0343792020-11-18 10:42:21 -0600549 :term:`BB_VERBOSE_LOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500550 Controls how verbose BitBake is during builds. If set, shell scripts
551 echo commands and shell script output appears on standard out
552 (stdout).
553
Andrew Geisslerf0343792020-11-18 10:42:21 -0600554 :term:`BB_WORKERCONTEXT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500555 Specifies if the current context is executing a task. BitBake sets
556 this variable to "1" when a task is being executed. The value is not
557 set when the task is in server context during parsing or event
558 handling.
559
Andrew Geisslerf0343792020-11-18 10:42:21 -0600560 :term:`BBCLASSEXTEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500561 Allows you to extend a recipe so that it builds variants of the
562 software. Some examples of these variants for recipes from the
563 OpenEmbedded-Core metadata are "natives" such as ``quilt-native``,
564 which is a copy of Quilt built to run on the build system; "crosses"
565 such as ``gcc-cross``, which is a compiler built to run on the build
566 machine but produces binaries that run on the target ``MACHINE``;
567 "nativesdk", which targets the SDK machine instead of ``MACHINE``;
568 and "mulitlibs" in the form "``multilib:``\ multilib_name".
569
570 To build a different variant of the recipe with a minimal amount of
571 code, it usually is as simple as adding the variable to your recipe.
572 Here are two examples. The "native" variants are from the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500573 OpenEmbedded-Core metadata::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500574
575 BBCLASSEXTEND =+ "native nativesdk"
576 BBCLASSEXTEND =+ "multilib:multilib_name"
577
578 .. note::
579
Patrick Williams213cb262021-08-07 19:21:33 -0500580 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500581 variants by rewriting variable values and applying overrides such
582 as ``_class-native``. For example, to generate a native version of
583 a recipe, a :term:`DEPENDS` on "foo" is
Patrick Williams213cb262021-08-07 19:21:33 -0500584 rewritten to a :term:`DEPENDS` on "foo-native".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500585
Patrick Williams213cb262021-08-07 19:21:33 -0500586 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500587 Parsing once adds some limitations. For example, it is not
588 possible to include a different file depending on the variant,
589 since ``include`` statements are processed when the recipe is
590 parsed.
591
Andrew Geisslerf0343792020-11-18 10:42:21 -0600592 :term:`BBDEBUG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500593 Sets the BitBake debug output level to a specific value as
594 incremented by the ``-D`` command line option.
595
596 .. note::
597
598 You must set this variable in the external environment in order
599 for it to work.
600
Andrew Geisslerf0343792020-11-18 10:42:21 -0600601 :term:`BBFILE_COLLECTIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500602 Lists the names of configured layers. These names are used to find
603 the other ``BBFILE_*`` variables. Typically, each layer appends its
604 name to this variable in its ``conf/layer.conf`` file.
605
Andrew Geisslerf0343792020-11-18 10:42:21 -0600606 :term:`BBFILE_PATTERN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500607 Variable that expands to match files from
608 :term:`BBFILES` in a particular layer. This
609 variable is used in the ``conf/layer.conf`` file and must be suffixed
610 with the name of the specific layer (e.g.
611 ``BBFILE_PATTERN_emenlow``).
612
Andrew Geisslerf0343792020-11-18 10:42:21 -0600613 :term:`BBFILE_PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500614 Assigns the priority for recipe files in each layer.
615
616 This variable is useful in situations where the same recipe appears
617 in more than one layer. Setting this variable allows you to
618 prioritize a layer against other layers that contain the same recipe
619 - effectively letting you control the precedence for the multiple
620 layers. The precedence established through this variable stands
621 regardless of a recipe's version (:term:`PV` variable).
Patrick Williams213cb262021-08-07 19:21:33 -0500622 For example, a layer that has a recipe with a higher :term:`PV` value but
623 for which the :term:`BBFILE_PRIORITY` is set to have a lower precedence
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500624 still has a lower precedence.
625
Patrick Williams213cb262021-08-07 19:21:33 -0500626 A larger value for the :term:`BBFILE_PRIORITY` variable results in a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500627 higher precedence. For example, the value 6 has a higher precedence
Patrick Williams213cb262021-08-07 19:21:33 -0500628 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
629 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500630 for more information. The default priority, if unspecified for a
631 layer with no dependencies, is the lowest defined priority + 1 (or 1
632 if no priorities are defined).
633
634 .. tip::
635
636 You can use the command bitbake-layers show-layers to list all
637 configured layers along with their priorities.
638
Andrew Geisslerf0343792020-11-18 10:42:21 -0600639 :term:`BBFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500640 A space-separated list of recipe files BitBake uses to build
641 software.
642
643 When specifying recipe files, you can pattern match using Python's
644 `glob <https://docs.python.org/3/library/glob.html>`_ syntax.
645 For details on the syntax, see the documentation by following the
646 previous link.
647
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500648 :term:`BBFILES_DYNAMIC`
649 Activates content depending on presence of identified layers. You
650 identify the layers by the collections that the layers define.
651
Patrick Williams213cb262021-08-07 19:21:33 -0500652 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files whose
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500653 corresponding ``.bb`` file is in a layer that attempts to modify other
654 layers through ``.bbappend`` but does not want to introduce a hard
655 dependency on those other layers.
656
657 Additionally you can prefix the rule with "!" to add ``.bbappend`` and
658 ``.bb`` files in case a layer is not present. Use this avoid hard
659 dependency on those other layers.
660
Patrick Williams213cb262021-08-07 19:21:33 -0500661 Use the following form for :term:`BBFILES_DYNAMIC`::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500662
663 collection_name:filename_pattern
664
665 The following example identifies two collection names and two filename
Andrew Geisslerc926e172021-05-07 16:11:35 -0500666 patterns::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500667
668 BBFILES_DYNAMIC += "\
669 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
670 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
671 "
672
673 When the collection name is prefixed with "!" it will add the file pattern in case
Andrew Geisslerc926e172021-05-07 16:11:35 -0500674 the layer is absent::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500675
676 BBFILES_DYNAMIC += "\
677 !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \
678 "
679
680 This next example shows an error message that occurs because invalid
Andrew Geisslerc926e172021-05-07 16:11:35 -0500681 entries are found, which cause parsing to abort::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500682
683 ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not:
684 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
685 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
686
Andrew Geisslerf0343792020-11-18 10:42:21 -0600687 :term:`BBINCLUDED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500688 Contains a space-separated list of all of all files that BitBake's
689 parser included during parsing of the current file.
690
Andrew Geisslerf0343792020-11-18 10:42:21 -0600691 :term:`BBINCLUDELOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500692 If set to a value, enables printing the task log when reporting a
693 failed task.
694
Andrew Geisslerf0343792020-11-18 10:42:21 -0600695 :term:`BBINCLUDELOGS_LINES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500696 If :term:`BBINCLUDELOGS` is set, specifies
697 the maximum number of lines from the task log file to print when
Patrick Williams213cb262021-08-07 19:21:33 -0500698 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500699 the entire log is printed.
700
Andrew Geisslerf0343792020-11-18 10:42:21 -0600701 :term:`BBLAYERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500702 Lists the layers to enable during the build. This variable is defined
703 in the ``bblayers.conf`` configuration file in the build directory.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500704 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500705
706 BBLAYERS = " \
707 /home/scottrif/poky/meta \
708 /home/scottrif/poky/meta-yocto \
709 /home/scottrif/poky/meta-yocto-bsp \
710 /home/scottrif/poky/meta-mykernel \
711 "
712
713 This example enables four layers, one of which is a custom, user-defined
714 layer named ``meta-mykernel``.
715
Andrew Geisslerf0343792020-11-18 10:42:21 -0600716 :term:`BBLAYERS_FETCH_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500717 Sets the base location where layers are stored. This setting is used
718 in conjunction with ``bitbake-layers layerindex-fetch`` and tells
719 ``bitbake-layers`` where to place the fetched layers.
720
Andrew Geisslerf0343792020-11-18 10:42:21 -0600721 :term:`BBMASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500722 Prevents BitBake from processing recipes and recipe append files.
723
Patrick Williams213cb262021-08-07 19:21:33 -0500724 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500725 ``.bbappend`` files. BitBake ignores any recipe or recipe append
726 files that match any of the expressions. It is as if BitBake does not
727 see them at all. Consequently, matching files are not parsed or
728 otherwise used by BitBake.
729
730 The values you provide are passed to Python's regular expression
731 compiler. Consequently, the syntax follows Python's Regular
732 Expression (re) syntax. The expressions are compared against the full
733 paths to the files. For complete syntax information, see Python's
734 documentation at http://docs.python.org/3/library/re.html.
735
736 The following example uses a complete regular expression to tell
737 BitBake to ignore all recipe and recipe append files in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500738 ``meta-ti/recipes-misc/`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500739
740 BBMASK = "meta-ti/recipes-misc/"
741
742 If you want to mask out multiple directories or recipes, you can
743 specify multiple regular expression fragments. This next example
Andrew Geisslerc926e172021-05-07 16:11:35 -0500744 masks out multiple directories and individual recipes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500745
746 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
747 BBMASK += "/meta-oe/recipes-support/"
748 BBMASK += "/meta-foo/.*/openldap"
749 BBMASK += "opencv.*\.bbappend"
750 BBMASK += "lzma"
751
752 .. note::
753
754 When specifying a directory name, use the trailing slash character
755 to ensure you match just that directory name.
756
Andrew Geisslerf0343792020-11-18 10:42:21 -0600757 :term:`BBMULTICONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500758 Enables BitBake to perform multiple configuration builds and lists
759 each separate configuration (multiconfig). You can use this variable
760 to cause BitBake to build multiple targets where each target has a
Patrick Williams213cb262021-08-07 19:21:33 -0500761 separate configuration. Define :term:`BBMULTICONFIG` in your
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500762 ``conf/local.conf`` configuration file.
763
764 As an example, the following line specifies three multiconfigs, each
Andrew Geisslerc926e172021-05-07 16:11:35 -0500765 having a separate configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500766
767 BBMULTIFONFIG = "configA configB configC"
768
769 Each configuration file you use must reside in the
770 build directory within a directory named ``conf/multiconfig`` (e.g.
771 build_directory\ ``/conf/multiconfig/configA.conf``).
772
Patrick Williams213cb262021-08-07 19:21:33 -0500773 For information on how to use :term:`BBMULTICONFIG` in an environment
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500774 that supports building targets with multiple configurations, see the
775 ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`"
776 section.
777
Andrew Geisslerf0343792020-11-18 10:42:21 -0600778 :term:`BBPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500779 Used by BitBake to locate class (``.bbclass``) and configuration
780 (``.conf``) files. This variable is analogous to the ``PATH``
781 variable.
782
783 If you run BitBake from a directory outside of the build directory,
Patrick Williams213cb262021-08-07 19:21:33 -0500784 you must be sure to set :term:`BBPATH` to point to the build directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500785 Set the variable as you would any environment variable and then run
Andrew Geisslerc926e172021-05-07 16:11:35 -0500786 BitBake::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500787
788 $ BBPATH="build_directory"
789 $ export BBPATH
790 $ bitbake target
791
Andrew Geisslerf0343792020-11-18 10:42:21 -0600792 :term:`BBSERVER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500793 Points to the server that runs memory-resident BitBake. The variable
794 is only used when you employ memory-resident BitBake.
795
Andrew Geisslerf0343792020-11-18 10:42:21 -0600796 :term:`BBTARGETS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500797 Allows you to use a configuration file to add to the list of
798 command-line target recipes you want to build.
799
Andrew Geisslerf0343792020-11-18 10:42:21 -0600800 :term:`BITBAKE_UI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500801 Used to specify the UI module to use when running BitBake. Using this
802 variable is equivalent to using the ``-u`` command-line option.
803
804 .. note::
805
806 You must set this variable in the external environment in order
807 for it to work.
808
Andrew Geisslerf0343792020-11-18 10:42:21 -0600809 :term:`BUILDNAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500810 A name assigned to the build. The name defaults to a datetime stamp
811 of when the build was started but can be defined by the metadata.
812
Andrew Geisslerf0343792020-11-18 10:42:21 -0600813 :term:`BZRDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500814 The directory in which files checked out of a Bazaar system are
815 stored.
816
Andrew Geisslerf0343792020-11-18 10:42:21 -0600817 :term:`CACHE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500818 Specifies the directory BitBake uses to store a cache of the metadata
819 so it does not need to be parsed every time BitBake is started.
820
Andrew Geisslerf0343792020-11-18 10:42:21 -0600821 :term:`CVSDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500822 The directory in which files checked out under the CVS system are
823 stored.
824
Andrew Geisslerf0343792020-11-18 10:42:21 -0600825 :term:`DEFAULT_PREFERENCE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500826 Specifies a weak bias for recipe selection priority.
827
828 The most common usage of this is variable is to set it to "-1" within
829 a recipe for a development version of a piece of software. Using the
830 variable in this way causes the stable version of the recipe to build
Patrick Williams213cb262021-08-07 19:21:33 -0500831 by default in the absence of :term:`PREFERRED_VERSION` being used to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500832 build the development version.
833
834 .. note::
835
836 The bias provided by DEFAULT_PREFERENCE is weak and is overridden by
837 :term:`BBFILE_PRIORITY` if that variable is different between two
838 layers that contain different versions of the same recipe.
839
Andrew Geisslerf0343792020-11-18 10:42:21 -0600840 :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500841 Lists a recipe's build-time dependencies (i.e. other recipe files).
842
843 Consider this simple example for two recipes named "a" and "b" that
Patrick Williams213cb262021-08-07 19:21:33 -0500844 produce similarly named packages. In this example, the :term:`DEPENDS`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500845 statement appears in the "a" recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500846
847 DEPENDS = "b"
848
849 Here, the dependency is such that the ``do_configure`` task for recipe "a"
850 depends on the ``do_populate_sysroot`` task of recipe "b". This means
851 anything that recipe "b" puts into sysroot is available when recipe "a" is
852 configuring itself.
853
854 For information on runtime dependencies, see the :term:`RDEPENDS`
855 variable.
856
Andrew Geisslerf0343792020-11-18 10:42:21 -0600857 :term:`DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500858 A long description for the recipe.
859
Andrew Geisslerf0343792020-11-18 10:42:21 -0600860 :term:`DL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500861 The central download directory used by the build process to store
Patrick Williams213cb262021-08-07 19:21:33 -0500862 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500863 everything except Git repositories. If you want tarballs of Git
864 repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable.
865
Andrew Geisslerf0343792020-11-18 10:42:21 -0600866 :term:`EXCLUDE_FROM_WORLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500867 Directs BitBake to exclude a recipe from world builds (i.e.
868 ``bitbake world``). During world builds, BitBake locates, parses and
869 builds all recipes found in every layer exposed in the
870 ``bblayers.conf`` configuration file.
871
872 To exclude a recipe from a world build using this variable, set the
873 variable to "1" in the recipe.
874
875 .. note::
876
Patrick Williams213cb262021-08-07 19:21:33 -0500877 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a world
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500878 build in order to satisfy dependencies of other recipes. Adding a
Patrick Williams213cb262021-08-07 19:21:33 -0500879 recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500880 explicitly added to the list of build targets in a world build.
881
Andrew Geisslerf0343792020-11-18 10:42:21 -0600882 :term:`FAKEROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500883 Contains the command to use when running a shell script in a fakeroot
Patrick Williams213cb262021-08-07 19:21:33 -0500884 environment. The :term:`FAKEROOT` variable is obsolete and has been
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500885 replaced by the other ``FAKEROOT*`` variables. See these entries in
886 the glossary for more information.
887
Andrew Geisslerf0343792020-11-18 10:42:21 -0600888 :term:`FAKEROOTBASEENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500889 Lists environment variables to set when executing the command defined
890 by :term:`FAKEROOTCMD` that starts the
891 bitbake-worker process in the fakeroot environment.
892
Andrew Geisslerf0343792020-11-18 10:42:21 -0600893 :term:`FAKEROOTCMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500894 Contains the command that starts the bitbake-worker process in the
895 fakeroot environment.
896
Andrew Geisslerf0343792020-11-18 10:42:21 -0600897 :term:`FAKEROOTDIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500898 Lists directories to create before running a task in the fakeroot
899 environment.
900
Andrew Geisslerf0343792020-11-18 10:42:21 -0600901 :term:`FAKEROOTENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500902 Lists environment variables to set when running a task in the
903 fakeroot environment. For additional information on environment
904 variables and the fakeroot environment, see the
905 :term:`FAKEROOTBASEENV` variable.
906
Andrew Geisslerf0343792020-11-18 10:42:21 -0600907 :term:`FAKEROOTNOENV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500908 Lists environment variables to set when running a task that is not in
909 the fakeroot environment. For additional information on environment
910 variables and the fakeroot environment, see the
911 :term:`FAKEROOTENV` variable.
912
Andrew Geisslerf0343792020-11-18 10:42:21 -0600913 :term:`FETCHCMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500914 Defines the command the BitBake fetcher module executes when running
915 fetch operations. You need to use an override suffix when you use the
916 variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``).
917
Andrew Geisslerf0343792020-11-18 10:42:21 -0600918 :term:`FILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500919 Points at the current file. BitBake sets this variable during the
920 parsing process to identify the file being parsed. BitBake also sets
921 this variable when a recipe is being executed to identify the recipe
922 file.
923
Andrew Geisslerf0343792020-11-18 10:42:21 -0600924 :term:`FILESPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500925 Specifies directories BitBake uses when searching for patches and
926 files. The "local" fetcher module uses these directories when
927 handling ``file://`` URLs. The variable behaves like a shell ``PATH``
928 environment variable. The value is a colon-separated list of
929 directories that are searched left-to-right in order.
930
Andrew Geisslerf0343792020-11-18 10:42:21 -0600931 :term:`GITDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500932 The directory in which a local copy of a Git repository is stored
933 when it is cloned.
934
Andrew Geisslerf0343792020-11-18 10:42:21 -0600935 :term:`HGDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500936 The directory in which files checked out of a Mercurial system are
937 stored.
938
Andrew Geisslerf0343792020-11-18 10:42:21 -0600939 :term:`HOMEPAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500940 Website where more information about the software the recipe is
941 building can be found.
942
Andrew Geisslerf0343792020-11-18 10:42:21 -0600943 :term:`INHERIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500944 Causes the named class or classes to be inherited globally. Anonymous
945 functions in the class or classes are not executed for the base
946 configuration and in each individual recipe. The OpenEmbedded build
Patrick Williams213cb262021-08-07 19:21:33 -0500947 system ignores changes to :term:`INHERIT` in individual recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500948
Patrick Williams213cb262021-08-07 19:21:33 -0500949 For more information on :term:`INHERIT`, see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500950 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
951 section.
952
Andrew Geisslerf0343792020-11-18 10:42:21 -0600953 :term:`LAYERDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500954 Lists the layers, separated by spaces, upon which this recipe
955 depends. Optionally, you can specify a specific layer version for a
956 dependency by adding it to the end of the layer name with a colon,
957 (e.g. "anotherlayer:3" to be compared against
958 :term:`LAYERVERSION`\ ``_anotherlayer`` in
959 this case). BitBake produces an error if any dependency is missing or
960 the version numbers do not match exactly (if specified).
961
962 You use this variable in the ``conf/layer.conf`` file. You must also
963 use the specific layer name as a suffix to the variable (e.g.
964 ``LAYERDEPENDS_mylayer``).
965
Andrew Geisslerf0343792020-11-18 10:42:21 -0600966 :term:`LAYERDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500967 When used inside the ``layer.conf`` configuration file, this variable
968 provides the path of the current layer. This variable is not
969 available outside of ``layer.conf`` and references are expanded
970 immediately when parsing of the file completes.
971
Andrew Geisslerf0343792020-11-18 10:42:21 -0600972 :term:`LAYERDIR_RE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500973 When used inside the ``layer.conf`` configuration file, this variable
974 provides the path of the current layer, escaped for use in a regular
975 expression (:term:`BBFILE_PATTERN`). This
976 variable is not available outside of ``layer.conf`` and references
977 are expanded immediately when parsing of the file completes.
978
Andrew Geisslerf0343792020-11-18 10:42:21 -0600979 :term:`LAYERVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500980 Optionally specifies the version of a layer as a single number. You
981 can use this variable within
982 :term:`LAYERDEPENDS` for another layer in
983 order to depend on a specific version of the layer.
984
985 You use this variable in the ``conf/layer.conf`` file. You must also
986 use the specific layer name as a suffix to the variable (e.g.
987 ``LAYERDEPENDS_mylayer``).
988
Andrew Geisslerf0343792020-11-18 10:42:21 -0600989 :term:`LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500990 The list of source licenses for the recipe.
991
Andrew Geisslerf0343792020-11-18 10:42:21 -0600992 :term:`MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500993 Specifies additional paths from which BitBake gets source code. When
994 the build system searches for source code, it first tries the local
995 download directory. If that location fails, the build system tries
996 locations defined by :term:`PREMIRRORS`, the
Patrick Williams213cb262021-08-07 19:21:33 -0500997 upstream source, and then locations specified by :term:`MIRRORS` in that
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500998 order.
999
Andrew Geisslerf0343792020-11-18 10:42:21 -06001000 :term:`MULTI_PROVIDER_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001001 Allows you to suppress BitBake warnings caused when building two
1002 separate recipes that provide the same output.
1003
1004 BitBake normally issues a warning when building two different recipes
1005 where each provides the same output. This scenario is usually
1006 something the user does not want. However, cases do exist where it
1007 makes sense, particularly in the ``virtual/*`` namespace. You can use
1008 this variable to suppress BitBake's warnings.
1009
1010 To use the variable, list provider names (e.g. recipe names,
1011 ``virtual/kernel``, and so forth).
1012
Andrew Geisslerf0343792020-11-18 10:42:21 -06001013 :term:`OVERRIDES`
Patrick Williams213cb262021-08-07 19:21:33 -05001014 BitBake uses :term:`OVERRIDES` to control what variables are overridden
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001015 after BitBake parses recipes and configuration files.
1016
1017 Following is a simple example that uses an overrides list based on
1018 machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
Patrick Williams213cb262021-08-07 19:21:33 -05001019 find information on how to use :term:`OVERRIDES` in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001020 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax
1021 (overrides)`" section.
1022
Andrew Geisslerf0343792020-11-18 10:42:21 -06001023 :term:`P4DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001024 The directory in which a local copy of a Perforce depot is stored
1025 when it is fetched.
1026
Andrew Geisslerf0343792020-11-18 10:42:21 -06001027 :term:`PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001028 The list of packages the recipe creates.
1029
Andrew Geisslerf0343792020-11-18 10:42:21 -06001030 :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001031 A promise that your recipe satisfies runtime dependencies for
1032 optional modules that are found in other recipes.
Patrick Williams213cb262021-08-07 19:21:33 -05001033 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001034 only states that they should be satisfied. For example, if a hard,
1035 runtime dependency (:term:`RDEPENDS`) of another
1036 package is satisfied during the build through the
Patrick Williams213cb262021-08-07 19:21:33 -05001037 :term:`PACKAGES_DYNAMIC` variable, but a package with the module name is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001038 never actually produced, then the other package will be broken.
1039
Andrew Geisslerf0343792020-11-18 10:42:21 -06001040 :term:`PE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001041 The epoch of the recipe. By default, this variable is unset. The
1042 variable is used to make upgrades possible when the versioning scheme
1043 changes in some backwards incompatible way.
1044
Andrew Geisslerf0343792020-11-18 10:42:21 -06001045 :term:`PERSISTENT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001046 Specifies the directory BitBake uses to store data that should be
1047 preserved between builds. In particular, the data stored is the data
1048 that uses BitBake's persistent data API and the data used by the PR
1049 Server and PR Service.
1050
Andrew Geisslerf0343792020-11-18 10:42:21 -06001051 :term:`PF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001052 Specifies the recipe or package name and includes all version and
1053 revision numbers (i.e. ``eglibc-2.13-r20+svnr15508/`` and
1054 ``bash-4.2-r1/``).
1055
Andrew Geisslerf0343792020-11-18 10:42:21 -06001056 :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001057 The recipe name.
1058
Andrew Geisslerf0343792020-11-18 10:42:21 -06001059 :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001060 The revision of the recipe.
1061
Andrew Geisslerf0343792020-11-18 10:42:21 -06001062 :term:`PREFERRED_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001063 Determines which recipe should be given preference when multiple
1064 recipes provide the same item. You should always suffix the variable
1065 with the name of the provided item, and you should set it to the
1066 :term:`PN` of the recipe to which you want to give
Andrew Geisslerc926e172021-05-07 16:11:35 -05001067 precedence. Some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001068
1069 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1070 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1071 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1072
Andrew Geisslerf0343792020-11-18 10:42:21 -06001073 :term:`PREFERRED_PROVIDERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001074 Determines which recipe should be given preference for cases where
1075 multiple recipes provide the same item. Functionally,
Patrick Williams213cb262021-08-07 19:21:33 -05001076 :term:`PREFERRED_PROVIDERS` is identical to
1077 :term:`PREFERRED_PROVIDER`. However, the :term:`PREFERRED_PROVIDERS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001078 lets you define preferences for multiple situations using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001079 form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001080
1081 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1082
Andrew Geisslerc926e172021-05-07 16:11:35 -05001083 This form is a convenient replacement for the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001084
1085 PREFERRED_PROVIDER_xxx = "yyy"
1086 PREFERRED_PROVIDER_aaa = "bbb"
1087
Andrew Geisslerf0343792020-11-18 10:42:21 -06001088 :term:`PREFERRED_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001089 If there are multiple versions of a recipe available, this variable
1090 determines which version should be given preference. You must always
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001091 suffix the variable with the :term:`PN` you want to
1092 select, and you should set :term:`PV` accordingly for
1093 precedence.
1094
Patrick Williams213cb262021-08-07 19:21:33 -05001095 The :term:`PREFERRED_VERSION` variable supports limited wildcard use
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001096 through the "``%``" character. You can use the character to match any
1097 number of characters, which can be useful when specifying versions
1098 that contain long revision numbers that potentially change. Here are
Andrew Geisslerc926e172021-05-07 16:11:35 -05001099 two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001100
1101 PREFERRED_VERSION_python = "2.7.3"
1102 PREFERRED_VERSION_linux-yocto = "4.12%"
1103
1104 .. important::
1105
1106 The use of the " % " character is limited in that it only works at the
1107 end of the string. You cannot use the wildcard character in any other
1108 location of the string.
1109
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001110 If a recipe with the specified version is not available, a warning
1111 message will be shown. See :term:`REQUIRED_VERSION` if you want this
1112 to be an error instead.
1113
Andrew Geisslerf0343792020-11-18 10:42:21 -06001114 :term:`PREMIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001115 Specifies additional paths from which BitBake gets source code. When
1116 the build system searches for source code, it first tries the local
1117 download directory. If that location fails, the build system tries
Patrick Williams213cb262021-08-07 19:21:33 -05001118 locations defined by :term:`PREMIRRORS`, the upstream source, and then
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001119 locations specified by :term:`MIRRORS` in that order.
1120
1121 Typically, you would add a specific server for the build system to
1122 attempt before any others by adding something like the following to
Andrew Geisslerc926e172021-05-07 16:11:35 -05001123 your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001124
Patrick Williams213cb262021-08-07 19:21:33 -05001125 PREMIRRORS:prepend = "\
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001126 git://.*/.* http://www.yoctoproject.org/sources/ \n \
1127 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
1128 http://.*/.* http://www.yoctoproject.org/sources/ \n \
1129 https://.*/.* http://www.yoctoproject.org/sources/ \n"
1130
1131 These changes cause the build system to intercept Git, FTP, HTTP, and
1132 HTTPS requests and direct them to the ``http://`` sources mirror. You can
1133 use ``file://`` URLs to point to local directories or network shares as
1134 well.
1135
Andrew Geisslerf0343792020-11-18 10:42:21 -06001136 :term:`PROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001137 A list of aliases by which a particular recipe can be known. By
Patrick Williams213cb262021-08-07 19:21:33 -05001138 default, a recipe's own :term:`PN` is implicitly already in its
1139 :term:`PROVIDES` list. If a recipe uses :term:`PROVIDES`, the additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001140 aliases are synonyms for the recipe and can be useful satisfying
1141 dependencies of other recipes during the build as specified by
Patrick Williams213cb262021-08-07 19:21:33 -05001142 :term:`DEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001143
Patrick Williams213cb262021-08-07 19:21:33 -05001144 Consider the following example :term:`PROVIDES` statement from a recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05001145 file ``libav_0.8.11.bb``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001146
1147 PROVIDES += "libpostproc"
1148
Patrick Williams213cb262021-08-07 19:21:33 -05001149 The :term:`PROVIDES` statement results in the "libav" recipe also being known
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001150 as "libpostproc".
1151
1152 In addition to providing recipes under alternate names, the
Patrick Williams213cb262021-08-07 19:21:33 -05001153 :term:`PROVIDES` mechanism is also used to implement virtual targets. A
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001154 virtual target is a name that corresponds to some particular
1155 functionality (e.g. a Linux kernel). Recipes that provide the
Patrick Williams213cb262021-08-07 19:21:33 -05001156 functionality in question list the virtual target in :term:`PROVIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001157 Recipes that depend on the functionality in question can include the
1158 virtual target in :term:`DEPENDS` to leave the
1159 choice of provider open.
1160
1161 Conventionally, virtual targets have names on the form
1162 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
1163 of the name and has no syntactical significance.
1164
Andrew Geisslerf0343792020-11-18 10:42:21 -06001165 :term:`PRSERV_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001166 The network based :term:`PR` service host and port.
1167
Patrick Williams213cb262021-08-07 19:21:33 -05001168 Following is an example of how the :term:`PRSERV_HOST` variable is set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001169
1170 PRSERV_HOST = "localhost:0"
1171
1172 You must set the variable if you want to automatically start a local PR
Patrick Williams213cb262021-08-07 19:21:33 -05001173 service. You can set :term:`PRSERV_HOST` to other values to use a remote PR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001174 service.
1175
Andrew Geisslerf0343792020-11-18 10:42:21 -06001176 :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001177 The version of the recipe.
1178
Andrew Geisslerf0343792020-11-18 10:42:21 -06001179 :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001180 Lists a package's runtime dependencies (i.e. other packages) that
1181 must be installed in order for the built package to run correctly. If
1182 a package in this list cannot be found during the build, you will get
1183 a build error.
1184
Patrick Williams213cb262021-08-07 19:21:33 -05001185 Because the :term:`RDEPENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001186 you should always use the variable in a form with an attached package
1187 name. For example, suppose you are building a development package
1188 that depends on the ``perl`` package. In this case, you would use the
Patrick Williams213cb262021-08-07 19:21:33 -05001189 following :term:`RDEPENDS` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001190
Patrick Williams213cb262021-08-07 19:21:33 -05001191 RDEPENDS:${PN}-dev += "perl"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001192
1193 In the example, the development package depends on the ``perl`` package.
Patrick Williams213cb262021-08-07 19:21:33 -05001194 Thus, the :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001195 of the variable.
1196
1197 BitBake supports specifying versioned dependencies. Although the
1198 syntax varies depending on the packaging format, BitBake hides these
1199 differences from you. Here is the general syntax to specify versions
Patrick Williams213cb262021-08-07 19:21:33 -05001200 with the :term:`RDEPENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001201
Patrick Williams213cb262021-08-07 19:21:33 -05001202 RDEPENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001203
Andrew Geisslerc926e172021-05-07 16:11:35 -05001204 For ``operator``, you can specify the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001205
1206 =
1207 <
1208 >
1209 <=
1210 >=
1211
1212 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05001213 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001214
Patrick Williams213cb262021-08-07 19:21:33 -05001215 RDEPENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001216
1217 For information on build-time dependencies, see the :term:`DEPENDS`
1218 variable.
1219
Andrew Geisslerf0343792020-11-18 10:42:21 -06001220 :term:`REPODIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001221 The directory in which a local copy of a ``google-repo`` directory is
1222 stored when it is synced.
1223
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001224 :term:`REQUIRED_VERSION`
1225 If there are multiple versions of a recipe available, this variable
Patrick Williams213cb262021-08-07 19:21:33 -05001226 determines which version should be given preference. :term:`REQUIRED_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001227 works in exactly the same manner as :term:`PREFERRED_VERSION`, except
1228 that if the specified version is not available then an error message
1229 is shown and the build fails immediately.
1230
Patrick Williams213cb262021-08-07 19:21:33 -05001231 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set for
1232 the same recipe, the :term:`REQUIRED_VERSION` value applies.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001233
Andrew Geisslerf0343792020-11-18 10:42:21 -06001234 :term:`RPROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001235 A list of package name aliases that a package also provides. These
1236 aliases are useful for satisfying runtime dependencies of other
1237 packages both during the build and on the target (as specified by
Patrick Williams213cb262021-08-07 19:21:33 -05001238 :term:`RDEPENDS`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001239
1240 As with all package-controlling variables, you must always use the
1241 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05001242 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001243
Patrick Williams213cb262021-08-07 19:21:33 -05001244 RPROVIDES:${PN} = "widget-abi-2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001245
Andrew Geisslerf0343792020-11-18 10:42:21 -06001246 :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001247 A list of packages that extends the usability of a package being
1248 built. The package being built does not depend on this list of
1249 packages in order to successfully build, but needs them for the
1250 extended usability. To specify runtime dependencies for packages, see
Patrick Williams213cb262021-08-07 19:21:33 -05001251 the :term:`RDEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001252
1253 BitBake supports specifying versioned recommends. Although the syntax
1254 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:`RRECOMMENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001257
Patrick Williams213cb262021-08-07 19:21:33 -05001258 RRECOMMENDS:${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 recommend on version
Andrew Geisslerc926e172021-05-07 16:11:35 -05001269 1.2 or greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001270
Patrick Williams213cb262021-08-07 19:21:33 -05001271 RRECOMMENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001272
Andrew Geisslerf0343792020-11-18 10:42:21 -06001273 :term:`SECTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001274 The section in which packages should be categorized.
1275
Andrew Geisslerf0343792020-11-18 10:42:21 -06001276 :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001277 The list of source files - local or remote. This variable tells
1278 BitBake which bits to pull for the build and how to pull them. For
1279 example, if the recipe or append file needs to fetch a single tarball
Patrick Williams213cb262021-08-07 19:21:33 -05001280 from the Internet, the recipe or append file uses a :term:`SRC_URI` entry
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001281 that specifies that tarball. On the other hand, if the recipe or
1282 append file needs to fetch a tarball and include a custom file, the
Patrick Williams213cb262021-08-07 19:21:33 -05001283 recipe or append file needs an :term:`SRC_URI` variable that specifies
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001284 all those sources.
1285
1286 The following list explains the available URI protocols:
1287
1288 - ``file://`` : Fetches files, which are usually files shipped
1289 with the metadata, from the local machine. The path is relative to
1290 the :term:`FILESPATH` variable.
1291
1292 - ``bzr://`` : Fetches files from a Bazaar revision control
1293 repository.
1294
1295 - ``git://`` : Fetches files from a Git revision control
1296 repository.
1297
1298 - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service)
1299 revision control repository.
1300
1301 - ``repo://`` : Fetches files from a repo (Git) repository.
1302
1303 - ``http://`` : Fetches files from the Internet using HTTP.
1304
1305 - ``https://`` : Fetches files from the Internet using HTTPS.
1306
1307 - ``ftp://`` : Fetches files from the Internet using FTP.
1308
1309 - ``cvs://`` : Fetches files from a CVS revision control
1310 repository.
1311
1312 - ``hg://`` : Fetches files from a Mercurial (``hg``) revision
1313 control repository.
1314
1315 - ``p4://`` : Fetches files from a Perforce (``p4``) revision
1316 control repository.
1317
1318 - ``ssh://`` : Fetches files from a secure shell.
1319
1320 - ``svn://`` : Fetches files from a Subversion (``svn``) revision
1321 control repository.
1322
Andrew Geissler95ac1b82021-03-31 14:34:31 -05001323 - ``az://`` : Fetches files from an Azure Storage account using HTTPS.
1324
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001325 Here are some additional options worth mentioning:
1326
1327 - ``unpack`` : Controls whether or not to unpack the file if it is
1328 an archive. The default action is to unpack the file.
1329
1330 - ``subdir`` : Places the file (or extracts its contents) into the
1331 specified subdirectory. This option is useful for unusual tarballs
1332 or other archives that do not have their files already in a
1333 subdirectory within the archive.
1334
1335 - ``name`` : Specifies a name to be used for association with
Patrick Williams213cb262021-08-07 19:21:33 -05001336 :term:`SRC_URI` checksums when you have more than one file specified
1337 in :term:`SRC_URI`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001338
1339 - ``downloadfilename`` : Specifies the filename used when storing
1340 the downloaded file.
1341
Andrew Geisslerf0343792020-11-18 10:42:21 -06001342 :term:`SRCDATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001343 The date of the source code used to build the package. This variable
1344 applies only if the source was fetched from a Source Code Manager
1345 (SCM).
1346
Andrew Geisslerf0343792020-11-18 10:42:21 -06001347 :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001348 The revision of the source code used to build the package. This
1349 variable applies only when using Subversion, Git, Mercurial and
1350 Bazaar. If you want to build a fixed revision and you want to avoid
1351 performing a query on the remote repository every time BitBake parses
Patrick Williams213cb262021-08-07 19:21:33 -05001352 your recipe, you should specify a :term:`SRCREV` that is a full revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001353 identifier and not just a tag.
1354
Andrew Geisslerf0343792020-11-18 10:42:21 -06001355 :term:`SRCREV_FORMAT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001356 Helps construct valid :term:`SRCREV` values when
1357 multiple source controlled URLs are used in
1358 :term:`SRC_URI`.
1359
1360 The system needs help constructing these values under these
Patrick Williams213cb262021-08-07 19:21:33 -05001361 circumstances. Each component in the :term:`SRC_URI` is assigned a name
1362 and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001363 an example with URLs named "machine" and "meta". In this case,
Patrick Williams213cb262021-08-07 19:21:33 -05001364 :term:`SRCREV_FORMAT` could look like "machine_meta" and those names
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001365 would have the SCM versions substituted into each position. Only one
1366 ``AUTOINC`` placeholder is added and if needed. And, this placeholder
1367 is placed at the start of the returned string.
1368
Andrew Geisslerf0343792020-11-18 10:42:21 -06001369 :term:`STAMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001370 Specifies the base path used to create recipe stamp files. The path
1371 to an actual stamp file is constructed by evaluating this string and
1372 then appending additional information.
1373
Andrew Geisslerf0343792020-11-18 10:42:21 -06001374 :term:`STAMPCLEAN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001375 Specifies the base path used to create recipe stamp files. Unlike the
Patrick Williams213cb262021-08-07 19:21:33 -05001376 :term:`STAMP` variable, :term:`STAMPCLEAN` can contain
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001377 wildcards to match the range of files a clean operation should
1378 remove. BitBake uses a clean operation to remove any other stamps it
1379 should be removing when creating a new stamp.
1380
Andrew Geisslerf0343792020-11-18 10:42:21 -06001381 :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001382 A short summary for the recipe, which is 72 characters or less.
1383
Andrew Geisslerf0343792020-11-18 10:42:21 -06001384 :term:`SVNDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001385 The directory in which files checked out of a Subversion system are
1386 stored.
1387
Andrew Geisslerf0343792020-11-18 10:42:21 -06001388 :term:`T`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001389 Points to a directory were BitBake places temporary files, which
1390 consist mostly of task logs and scripts, when building a particular
1391 recipe.
1392
Andrew Geisslerf0343792020-11-18 10:42:21 -06001393 :term:`TOPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001394 Points to the build directory. BitBake automatically sets this
1395 variable.