blob: fb1b353c82d5466442fe8141d180458303d79bf9 [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001.. SPDX-License-Identifier: CC-BY-2.5
4Variables Glossary
9This chapter lists common variables used by BitBake and gives an
10overview of their function and contents.
12.. note::
14 Following are some points regarding the variables listed in this
15 glossary:
17 - The variables listed in this glossary are specific to BitBake.
18 Consequently, the descriptions are limited to that context.
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.
26 - Finally, there are variables mentioned in this glossary that do
27 not appear in the BitBake glossary. These other variables are
28 variables used in systems that use BitBake.
30.. glossary::
Andrew Geissler4873add2020-11-02 18:44:49 -060032 ASSUME_PROVIDED
Andrew Geisslerc9f78652020-09-18 14:11:35 -050033 Lists recipe names (:term:`PN` values) BitBake does not
34 attempt to build. Instead, BitBake assumes these recipes have already
35 been built.
37 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native
38 tools that should not be built. An example is ``git-native``, which
39 when specified allows for the Git binary from the host to be used
40 rather than building ``git-native``.
Andrew Geissler4873add2020-11-02 18:44:49 -060042 B
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043 The directory in which BitBake executes functions during a recipe's
44 build process.
Andrew Geissler4873add2020-11-02 18:44:49 -060046 BB_ALLOWED_NETWORKS
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047 Specifies a space-delimited list of hosts that the fetcher is allowed
48 to use to obtain the required source code. Following are
49 considerations surrounding this variable:
51 - This host list is only used if
52 :term:`BB_NO_NETWORK` is either not set or
53 set to "0".
55 - Limited support for the "``*``" wildcard character for matching
56 against the beginning of host names exists. For example, the
57 following setting matches ````, ````, and
58 ````. ::
62 .. important::
64 The use of the "``*``" character only works at the beginning of
65 a host name and it must be isolated from the remainder of the
66 host name. You cannot use the wildcard character in any other
67 location of the name or combined with the front part of the
68 name.
70 For example, ``*`` is supported, while ``*``
71 is not.
73 - Mirrors not in the host list are skipped and logged in debug.
75 - Attempts to access networks not in the host list cause a failure.
77 Using ``BB_ALLOWED_NETWORKS`` in conjunction with
78 :term:`PREMIRRORS` is very useful. Adding the
79 host you want to use to ``PREMIRRORS`` results in the source code
80 being fetched from an allowed location and avoids raising an error
81 when a host that is not allowed is in a
82 :term:`SRC_URI` statement. This is because the
83 fetcher does not attempt to use the host listed in ``SRC_URI`` after
84 a successful fetch from the ``PREMIRRORS`` occurs.
Andrew Geissler4873add2020-11-02 18:44:49 -060086 BB_CONSOLELOG
Andrew Geisslerc9f78652020-09-18 14:11:35 -050087 Specifies the path to a log file into which BitBake's user interface
88 writes output during the build.
Andrew Geissler4873add2020-11-02 18:44:49 -060090 BB_CURRENTTASK
Andrew Geisslerc9f78652020-09-18 14:11:35 -050091 Contains the name of the currently running task. The name does not
92 include the ``do_`` prefix.
Andrew Geissler4873add2020-11-02 18:44:49 -060094 BB_DANGLINGAPPENDS_WARNONLY
Andrew Geisslerc9f78652020-09-18 14:11:35 -050095 Defines how BitBake handles situations where an append file
96 (``.bbappend``) has no corresponding recipe file (``.bb``). This
97 condition often occurs when layers get out of sync (e.g. ``oe-core``
98 bumps a recipe version and the old recipe no longer exists and the
99 other layer has not been updated to the new version of the recipe
100 yet).
102 The default fatal behavior is safest because it is the sane reaction
103 given something is out of sync. It is important to realize when your
104 changes are no longer being applied.
Andrew Geissler4873add2020-11-02 18:44:49 -0600106 BB_DEFAULT_TASK
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500107 The default task to use when none is specified (e.g. with the ``-c``
108 command line option). The task name specified should not include the
109 ``do_`` prefix.
Andrew Geissler4873add2020-11-02 18:44:49 -0600111 BB_DISKMON_DIRS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112 Monitors disk space and available inodes during the build and allows
113 you to control the build based on these parameters.
115 Disk space monitoring is disabled by default. When setting this
116 variable, use the following form: ::
118 BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]"
120 where:
122 <action> is:
123 ABORT: Immediately abort the build when
124 a threshold is broken.
125 STOPTASKS: Stop the build after the currently
126 executing tasks have finished when
127 a threshold is broken.
128 WARN: Issue a warning but continue the
129 build when a threshold is broken.
130 Subsequent warnings are issued as
131 defined by the
133 which must be defined.
135 <dir> is:
136 Any directory you choose. You can specify one or
137 more directories to monitor by separating the
138 groupings with a space. If two directories are
139 on the same device, only the first directory
140 is monitored.
142 <threshold> is:
143 Either the minimum available disk space,
144 the minimum number of free inodes, or
145 both. You must specify at least one. To
146 omit one or the other, simply omit the value.
147 Specify the threshold using G, M, K for Gbytes,
148 Mbytes, and Kbytes, respectively. If you do
149 not specify G, M, or K, Kbytes is assumed by
150 default. Do not use GB, MB, or KB.
152 Here are some examples: ::
158 The first example works only if you also set the
160 variable. This example causes the build system to immediately abort
161 when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or
162 the available free inodes drops below 100 Kbytes. Because two
163 directories are provided with the variable, the build system also
164 issues a warning when the disk space in the ``${SSTATE_DIR}``
165 directory drops below 1 Gbyte or the number of free inodes drops
166 below 100 Kbytes. Subsequent warnings are issued during intervals as
167 defined by the ``BB_DISKMON_WARNINTERVAL`` variable.
169 The second example stops the build after all currently executing
170 tasks complete when the minimum disk space in the ``${TMPDIR}``
171 directory drops below 1 Gbyte. No disk monitoring occurs for the free
172 inodes in this case.
174 The final example immediately aborts the build when the number of
175 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
176 disk space monitoring for the directory itself occurs in this case.
Andrew Geissler4873add2020-11-02 18:44:49 -0600178 BB_DISKMON_WARNINTERVAL
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179 Defines the disk space and free inode warning intervals.
181 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you
182 must also use the :term:`BB_DISKMON_DIRS`
183 variable and define its action as "WARN". During the build,
184 subsequent warnings are issued each time disk space or number of free
185 inodes further reduces by the respective interval.
187 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you
188 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk
189 monitoring interval defaults to the following:
192 When specifying the variable in your configuration file, use the
193 following form: ::
195 BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>"
197 where:
199 <disk_space_interval> is:
200 An interval of memory expressed in either
201 G, M, or K for Gbytes, Mbytes, or Kbytes,
202 respectively. You cannot use GB, MB, or KB.
204 <disk_inode_interval> is:
205 An interval of free inodes expressed in either
206 G, M, or K for Gbytes, Mbytes, or Kbytes,
207 respectively. You cannot use GB, MB, or KB.
209 Here is an example: ::
214 These variables cause BitBake to
215 issue subsequent warnings each time the available disk space further
216 reduces by 50 Mbytes or the number of free inodes further reduces by
217 5 Kbytes in the ``${SSTATE_DIR}`` directory. Subsequent warnings
218 based on the interval occur each time a respective interval is
219 reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes).
Andrew Geissler4873add2020-11-02 18:44:49 -0600221 BB_ENV_WHITELIST
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500222 Specifies the internal whitelist of variables to allow through from
223 the external environment into BitBake's datastore. If the value of
224 this variable is not specified (which is the default), the following
225 list is used: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`,
226 :term:`BB_ENV_WHITELIST`, and :term:`BB_ENV_EXTRAWHITE`.
228 .. note::
230 You must set this variable in the external environment in order
231 for it to work.
Andrew Geissler4873add2020-11-02 18:44:49 -0600233 BB_ENV_EXTRAWHITE
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234 Specifies an additional set of variables to allow through (whitelist)
235 from the external environment into BitBake's datastore. This list of
236 variables are on top of the internal list set in
237 :term:`BB_ENV_WHITELIST`.
239 .. note::
241 You must set this variable in the external environment in order
242 for it to work.
Andrew Geissler4873add2020-11-02 18:44:49 -0600244 BB_FETCH_PREMIRRORONLY
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500245 When set to "1", causes BitBake's fetcher module to only search
246 :term:`PREMIRRORS` for files. BitBake will not
247 search the main :term:`SRC_URI` or
248 :term:`MIRRORS`.
Andrew Geissler4873add2020-11-02 18:44:49 -0600250 BB_FILENAME
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500251 Contains the filename of the recipe that owns the currently running
252 task. For example, if the ``do_fetch`` task that resides in the
253 ```` is executing, the ``BB_FILENAME`` variable contains
254 "/foo/path/".
Andrew Geissler4873add2020-11-02 18:44:49 -0600256 BBFILES_DYNAMIC
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500257 Activates content depending on presence of identified layers. You
258 identify the layers by the collections that the layers define.
260 Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose
261 corresponding ``.bb`` file is in a layer that attempts to modify other
262 layers through ``.bbappend`` but does not want to introduce a hard
263 dependency on those other layers.
265 Additionally you can prefix the rule with "!" to add ``.bbappend`` and
266 ``.bb`` files in case a layer is not present. Use this avoid hard
267 dependency on those other layers.
269 Use the following form for ``BBFILES_DYNAMIC``: ::
271 collection_name:filename_pattern
273 The following example identifies two collection names and two filename
274 patterns: ::
277 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
278 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
279 "
281 When the collection name is prefixed with "!" it will add the file pattern in case
282 the layer is absent: ::
285 !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \
286 "
288 This next example shows an error message that occurs because invalid
289 entries are found, which cause parsing to abort: ::
291 ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not:
292 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
293 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
Andrew Geissler4873add2020-11-02 18:44:49 -0600295 BB_GENERATE_MIRROR_TARBALLS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296 Causes tarballs of the Git repositories, including the Git metadata,
297 to be placed in the :term:`DL_DIR` directory. Anyone
298 wishing to create a source mirror would want to enable this variable.
300 For performance reasons, creating and placing tarballs of the Git
301 repositories is not the default action by BitBake. ::
Andrew Geissler4873add2020-11-02 18:44:49 -0600305 BB_HASHCONFIG_WHITELIST
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500306 Lists variables that are excluded from base configuration checksum,
307 which is used to determine if the cache can be reused.
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.
Andrew Geissler4873add2020-11-02 18:44:49 -0600317 BB_HASHBASE_WHITELIST
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500318 Lists variables that are excluded from checksum and dependency data.
319 Variables that are excluded can therefore change without affecting
320 the checksum mechanism. A common example would be the variable for
321 the path of the build. BitBake's output should not (and usually does
322 not) depend on the directory in which it was built.
Andrew Geissler4873add2020-11-02 18:44:49 -0600324 BB_HASHCHECK_FUNCTION
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325 Specifies the name of the function to call during the "setscene" part
326 of the task's execution in order to validate the list of task hashes.
327 The function returns the list of setscene tasks that should be
328 executed.
330 At this point in the execution of the code, the objective is to
331 quickly verify if a given setscene function is likely to work or not.
332 It's easier to check the list of setscene functions in one pass than
333 to call many individual tasks. The returned list need not be
334 completely accurate. A given setscene task can still later fail.
335 However, the more accurate the data returned, the more efficient the
336 build will be.
Andrew Geissler4873add2020-11-02 18:44:49 -0600338 BB_INVALIDCONF
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500339 Used in combination with the ``ConfigParsed`` event to trigger
340 re-parsing the base metadata (i.e. all the recipes). The
341 ``ConfigParsed`` event can set the variable to trigger the re-parse.
342 You must be careful to avoid recursive loops with this functionality.
Andrew Geissler4873add2020-11-02 18:44:49 -0600344 BB_LOGCONFIG
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500345 Specifies the name of a config file that contains the user logging
346 configuration. See
347 :ref:`bitbake-user-manual/bitbake-user-manual-execution:logging`
348 for additional information
Andrew Geissler4873add2020-11-02 18:44:49 -0600350 BB_LOGFMT
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500351 Specifies the name of the log files saved into
352 ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT``
353 variable is undefined and the log file names get created using the
354 following form: ::
356 log.{task}.{pid}
358 If you want to force log files to take a specific name, you can set this
359 variable in a configuration file.
Andrew Geissler4873add2020-11-02 18:44:49 -0600361 BB_NICE_LEVEL
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500362 Allows BitBake to run at a specific priority (i.e. nice level).
363 System permissions usually mean that BitBake can reduce its priority
364 but not raise it again. See :term:`BB_TASK_NICE_LEVEL` for
365 additional information.
Andrew Geissler4873add2020-11-02 18:44:49 -0600367 BB_NO_NETWORK
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500368 Disables network access in the BitBake fetcher modules. With this
369 access disabled, any command that attempts to access the network
370 becomes an error.
372 Disabling network access is useful for testing source mirrors,
373 running builds when not connected to the Internet, and when operating
374 in certain kinds of firewall environments.
Andrew Geissler4873add2020-11-02 18:44:49 -0600376 BB_NUMBER_THREADS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377 The maximum number of tasks BitBake should run in parallel at any one
378 time. If your host development system supports multiple cores, a good
379 rule of thumb is to set this variable to twice the number of cores.
Andrew Geissler4873add2020-11-02 18:44:49 -0600381 BB_NUMBER_PARSE_THREADS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500382 Sets the number of threads BitBake uses when parsing. By default, the
383 number of threads is equal to the number of cores on the system.
Andrew Geissler4873add2020-11-02 18:44:49 -0600385 BB_ORIGENV
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500386 Contains a copy of the original external environment in which BitBake
387 was run. The copy is taken before any whitelisted variable values are
388 filtered into BitBake's datastore.
390 .. note::
392 The contents of this variable is a datastore object that can be
393 queried using the normal datastore operations.
Andrew Geissler4873add2020-11-02 18:44:49 -0600395 BB_PRESERVE_ENV
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500396 Disables whitelisting and instead allows all variables through from
397 the external environment into BitBake's datastore.
399 .. note::
401 You must set this variable in the external environment in order
402 for it to work.
Andrew Geissler4873add2020-11-02 18:44:49 -0600404 BB_RUNFMT
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500405 Specifies the name of the executable script files (i.e. run files)
406 saved into ``${``\ :term:`T`\ ``}``. By default, the
407 ``BB_RUNFMT`` variable is undefined and the run file names get
408 created using the following form: ::
410 run.{task}.{pid}
412 If you want to force run files to take a specific name, you can set this
413 variable in a configuration file.
Andrew Geissler4873add2020-11-02 18:44:49 -0600415 BB_RUNTASK
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500416 Contains the name of the currently executing task. The value includes
417 the "do\_" prefix. For example, if the currently executing task is
418 ``do_config``, the value is "do_config".
Andrew Geissler4873add2020-11-02 18:44:49 -0600420 BB_SCHEDULER
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500421 Selects the name of the scheduler to use for the scheduling of
422 BitBake tasks. Three options exist:
424 - *basic* - The basic framework from which everything derives. Using
425 this option causes tasks to be ordered numerically as they are
426 parsed.
428 - *speed* - Executes tasks first that have more tasks depending on
429 them. The "speed" option is the default.
431 - *completion* - Causes the scheduler to try to complete a given
432 recipe once its build has started.
Andrew Geissler4873add2020-11-02 18:44:49 -0600434 BB_SCHEDULERS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500435 Defines custom schedulers to import. Custom schedulers need to be
436 derived from the ``RunQueueScheduler`` class.
438 For information how to select a scheduler, see the
439 :term:`BB_SCHEDULER` variable.
Andrew Geissler4873add2020-11-02 18:44:49 -0600441 BB_SETSCENE_DEPVALID
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500442 Specifies a function BitBake calls that determines whether BitBake
443 requires a setscene dependency to be met.
445 When running a setscene task, BitBake needs to know which
446 dependencies of that setscene task also need to be run. Whether
447 dependencies also need to be run is highly dependent on the metadata.
448 The function specified by this variable returns a "True" or "False"
449 depending on whether the dependency needs to be met.
Andrew Geissler4873add2020-11-02 18:44:49 -0600451 BB_SETSCENE_VERIFY_FUNCTION2
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500452 Specifies a function to call that verifies the list of planned task
453 execution before the main task execution happens. The function is
454 called once BitBake has a list of setscene tasks that have run and
455 either succeeded or failed.
457 The function allows for a task list check to see if they make sense.
458 Even if BitBake was planning to skip a task, the returned value of
459 the function can force BitBake to run the task, which is necessary
460 under certain metadata defined circumstances.
Andrew Geissler4873add2020-11-02 18:44:49 -0600462 BB_SIGNATURE_EXCLUDE_FLAGS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500463 Lists variable flags (varflags) that can be safely excluded from
464 checksum and dependency data for keys in the datastore. When
465 generating checksum or dependency data for keys in the datastore, the
466 flags set against that key are normally included in the checksum.
468 For more information on varflags, see the
469 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`"
470 section.
Andrew Geissler4873add2020-11-02 18:44:49 -0600472 BB_SIGNATURE_HANDLER
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473 Defines the name of the signature handler BitBake uses. The signature
474 handler defines the way stamp files are created and handled, if and
475 how the signature is incorporated into the stamps, and how the
476 signature itself is generated.
478 A new signature handler can be added by injecting a class derived
479 from the ``SignatureGenerator`` class into the global namespace.
Andrew Geissler4873add2020-11-02 18:44:49 -0600481 BB_SRCREV_POLICY
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500482 Defines the behavior of the fetcher when it interacts with source
483 control systems and dynamic source revisions. The
484 ``BB_SRCREV_POLICY`` variable is useful when working without a
485 network.
487 The variable can be set using one of two policies:
489 - *cache* - Retains the value the system obtained previously rather
490 than querying the source control system each time.
492 - *clear* - Queries the source controls system every time. With this
493 policy, there is no cache. The "clear" policy is the default.
Andrew Geissler4873add2020-11-02 18:44:49 -0600495 BB_STAMP_POLICY
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500496 Defines the mode used for how timestamps of stamp files are compared.
497 You can set the variable to one of the following modes:
499 - *perfile* - Timestamp comparisons are only made between timestamps
500 of a specific recipe. This is the default mode.
502 - *full* - Timestamp comparisons are made for all dependencies.
504 - *whitelist* - Identical to "full" mode except timestamp
505 comparisons are made for recipes listed in the
506 :term:`BB_STAMP_WHITELIST` variable.
508 .. note::
510 Stamp policies are largely obsolete with the introduction of
511 setscene tasks.
Andrew Geissler4873add2020-11-02 18:44:49 -0600513 BB_STAMP_WHITELIST
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500514 Lists files whose stamp file timestamps are compared when the stamp
515 policy mode is set to "whitelist". For information on stamp policies,
516 see the :term:`BB_STAMP_POLICY` variable.
Andrew Geissler4873add2020-11-02 18:44:49 -0600518 BB_STRICT_CHECKSUM
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500519 Sets a more strict checksum mechanism for non-local URLs. Setting
520 this variable to a value causes BitBake to report an error if it
521 encounters a non-local URL that does not have at least one checksum
522 specified.
Andrew Geissler4873add2020-11-02 18:44:49 -0600524 BB_TASK_IONICE_LEVEL
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500525 Allows adjustment of a task's Input/Output priority. During
526 Autobuilder testing, random failures can occur for tasks due to I/O
527 starvation. These failures occur during various QEMU runtime
528 timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust
529 the I/O priority of these tasks.
531 .. note::
533 This variable works similarly to the :term:`BB_TASK_NICE_LEVEL`
534 variable except with a task's I/O priorities.
536 Set the variable as follows: ::
538 BB_TASK_IONICE_LEVEL = "class.prio"
540 For *class*, the default value is "2", which is a best effort. You can use
541 "1" for realtime and "3" for idle. If you want to use realtime, you
542 must have superuser privileges.
544 For *prio*, you can use any value from "0", which is the highest
545 priority, to "7", which is the lowest. The default value is "4". You
546 do not need any special privileges to use this range of priority
547 values.
549 .. note::
551 In order for your I/O priority settings to take effect, you need the
552 Completely Fair Queuing (CFQ) Scheduler selected for the backing block
553 device. To select the scheduler, use the following command form where
554 device is the device (e.g. sda, sdb, and so forth): ::
Andrew Geissler4873add2020-11-02 18:44:49 -0600556 $ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500557
Andrew Geissler4873add2020-11-02 18:44:49 -0600558 BB_TASK_NICE_LEVEL
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559 Allows specific tasks to change their priority (i.e. nice level).
561 You can use this variable in combination with task overrides to raise
562 or lower priorities of specific tasks. For example, on the `Yocto
563 Project <>`__ autobuilder, QEMU emulation
564 in images is given a higher priority as compared to build tasks to
565 ensure that images do not suffer timeouts on loaded systems.
Andrew Geissler4873add2020-11-02 18:44:49 -0600567 BB_TASKHASH
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568 Within an executing task, this variable holds the hash of the task as
569 returned by the currently enabled signature generator.
Andrew Geissler4873add2020-11-02 18:44:49 -0600571 BB_VERBOSE_LOGS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500572 Controls how verbose BitBake is during builds. If set, shell scripts
573 echo commands and shell script output appears on standard out
574 (stdout).
Andrew Geissler4873add2020-11-02 18:44:49 -0600576 BB_WORKERCONTEXT
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500577 Specifies if the current context is executing a task. BitBake sets
578 this variable to "1" when a task is being executed. The value is not
579 set when the task is in server context during parsing or event
580 handling.
Andrew Geissler4873add2020-11-02 18:44:49 -0600582 BBCLASSEXTEND
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500583 Allows you to extend a recipe so that it builds variants of the
584 software. Some examples of these variants for recipes from the
585 OpenEmbedded-Core metadata are "natives" such as ``quilt-native``,
586 which is a copy of Quilt built to run on the build system; "crosses"
587 such as ``gcc-cross``, which is a compiler built to run on the build
588 machine but produces binaries that run on the target ``MACHINE``;
589 "nativesdk", which targets the SDK machine instead of ``MACHINE``;
590 and "mulitlibs" in the form "``multilib:``\ multilib_name".
592 To build a different variant of the recipe with a minimal amount of
593 code, it usually is as simple as adding the variable to your recipe.
594 Here are two examples. The "native" variants are from the
595 OpenEmbedded-Core metadata: ::
597 BBCLASSEXTEND =+ "native nativesdk"
598 BBCLASSEXTEND =+ "multilib:multilib_name"
600 .. note::
602 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe
603 variants by rewriting variable values and applying overrides such
604 as ``_class-native``. For example, to generate a native version of
605 a recipe, a :term:`DEPENDS` on "foo" is
606 rewritten to a ``DEPENDS`` on "foo-native".
608 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once.
609 Parsing once adds some limitations. For example, it is not
610 possible to include a different file depending on the variant,
611 since ``include`` statements are processed when the recipe is
612 parsed.
Andrew Geissler4873add2020-11-02 18:44:49 -0600614 BBDEBUG
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500615 Sets the BitBake debug output level to a specific value as
616 incremented by the ``-D`` command line option.
618 .. note::
620 You must set this variable in the external environment in order
621 for it to work.
Andrew Geissler4873add2020-11-02 18:44:49 -0600623 BBFILE_COLLECTIONS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500624 Lists the names of configured layers. These names are used to find
625 the other ``BBFILE_*`` variables. Typically, each layer appends its
626 name to this variable in its ``conf/layer.conf`` file.
Andrew Geissler4873add2020-11-02 18:44:49 -0600628 BBFILE_PATTERN
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500629 Variable that expands to match files from
630 :term:`BBFILES` in a particular layer. This
631 variable is used in the ``conf/layer.conf`` file and must be suffixed
632 with the name of the specific layer (e.g.
633 ``BBFILE_PATTERN_emenlow``).
Andrew Geissler4873add2020-11-02 18:44:49 -0600635 BBFILE_PRIORITY
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500636 Assigns the priority for recipe files in each layer.
638 This variable is useful in situations where the same recipe appears
639 in more than one layer. Setting this variable allows you to
640 prioritize a layer against other layers that contain the same recipe
641 - effectively letting you control the precedence for the multiple
642 layers. The precedence established through this variable stands
643 regardless of a recipe's version (:term:`PV` variable).
644 For example, a layer that has a recipe with a higher ``PV`` value but
645 for which the ``BBFILE_PRIORITY`` is set to have a lower precedence
646 still has a lower precedence.
648 A larger value for the ``BBFILE_PRIORITY`` variable results in a
649 higher precedence. For example, the value 6 has a higher precedence
650 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable
651 is set based on layer dependencies (see the ``LAYERDEPENDS`` variable
652 for more information. The default priority, if unspecified for a
653 layer with no dependencies, is the lowest defined priority + 1 (or 1
654 if no priorities are defined).
656 .. tip::
658 You can use the command bitbake-layers show-layers to list all
659 configured layers along with their priorities.
Andrew Geissler4873add2020-11-02 18:44:49 -0600661 BBFILES
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500662 A space-separated list of recipe files BitBake uses to build
663 software.
665 When specifying recipe files, you can pattern match using Python's
666 `glob <>`_ syntax.
667 For details on the syntax, see the documentation by following the
668 previous link.
Andrew Geissler4873add2020-11-02 18:44:49 -0600670 BBINCLUDED
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500671 Contains a space-separated list of all of all files that BitBake's
672 parser included during parsing of the current file.
Andrew Geissler4873add2020-11-02 18:44:49 -0600674 BBINCLUDELOGS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500675 If set to a value, enables printing the task log when reporting a
676 failed task.
Andrew Geissler4873add2020-11-02 18:44:49 -0600678 BBINCLUDELOGS_LINES
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500679 If :term:`BBINCLUDELOGS` is set, specifies
680 the maximum number of lines from the task log file to print when
681 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``,
682 the entire log is printed.
Andrew Geissler4873add2020-11-02 18:44:49 -0600684 BBLAYERS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500685 Lists the layers to enable during the build. This variable is defined
686 in the ``bblayers.conf`` configuration file in the build directory.
687 Here is an example: ::
689 BBLAYERS = " \
690 /home/scottrif/poky/meta \
691 /home/scottrif/poky/meta-yocto \
692 /home/scottrif/poky/meta-yocto-bsp \
693 /home/scottrif/poky/meta-mykernel \
694 "
696 This example enables four layers, one of which is a custom, user-defined
697 layer named ``meta-mykernel``.
Andrew Geissler4873add2020-11-02 18:44:49 -0600699 BBLAYERS_FETCH_DIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500700 Sets the base location where layers are stored. This setting is used
701 in conjunction with ``bitbake-layers layerindex-fetch`` and tells
702 ``bitbake-layers`` where to place the fetched layers.
Andrew Geissler4873add2020-11-02 18:44:49 -0600704 BBMASK
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500705 Prevents BitBake from processing recipes and recipe append files.
707 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and
708 ``.bbappend`` files. BitBake ignores any recipe or recipe append
709 files that match any of the expressions. It is as if BitBake does not
710 see them at all. Consequently, matching files are not parsed or
711 otherwise used by BitBake.
713 The values you provide are passed to Python's regular expression
714 compiler. Consequently, the syntax follows Python's Regular
715 Expression (re) syntax. The expressions are compared against the full
716 paths to the files. For complete syntax information, see Python's
717 documentation at
719 The following example uses a complete regular expression to tell
720 BitBake to ignore all recipe and recipe append files in the
721 ``meta-ti/recipes-misc/`` directory: ::
723 BBMASK = "meta-ti/recipes-misc/"
725 If you want to mask out multiple directories or recipes, you can
726 specify multiple regular expression fragments. This next example
727 masks out multiple directories and individual recipes: ::
729 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
730 BBMASK += "/meta-oe/recipes-support/"
731 BBMASK += "/meta-foo/.*/openldap"
732 BBMASK += "opencv.*\.bbappend"
733 BBMASK += "lzma"
735 .. note::
737 When specifying a directory name, use the trailing slash character
738 to ensure you match just that directory name.
Andrew Geissler4873add2020-11-02 18:44:49 -0600740 BBMULTICONFIG
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500741 Enables BitBake to perform multiple configuration builds and lists
742 each separate configuration (multiconfig). You can use this variable
743 to cause BitBake to build multiple targets where each target has a
744 separate configuration. Define ``BBMULTICONFIG`` in your
745 ``conf/local.conf`` configuration file.
747 As an example, the following line specifies three multiconfigs, each
748 having a separate configuration file: ::
750 BBMULTIFONFIG = "configA configB configC"
752 Each configuration file you use must reside in the
753 build directory within a directory named ``conf/multiconfig`` (e.g.
754 build_directory\ ``/conf/multiconfig/configA.conf``).
756 For information on how to use ``BBMULTICONFIG`` in an environment
757 that supports building targets with multiple configurations, see the
758 ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`"
759 section.
Andrew Geissler4873add2020-11-02 18:44:49 -0600761 BBPATH
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500762 Used by BitBake to locate class (``.bbclass``) and configuration
763 (``.conf``) files. This variable is analogous to the ``PATH``
764 variable.
766 If you run BitBake from a directory outside of the build directory,
767 you must be sure to set ``BBPATH`` to point to the build directory.
768 Set the variable as you would any environment variable and then run
769 BitBake: ::
771 $ BBPATH="build_directory"
772 $ export BBPATH
773 $ bitbake target
Andrew Geissler4873add2020-11-02 18:44:49 -0600775 BBSERVER
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500776 Points to the server that runs memory-resident BitBake. The variable
777 is only used when you employ memory-resident BitBake.
Andrew Geissler4873add2020-11-02 18:44:49 -0600779 BBTARGETS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500780 Allows you to use a configuration file to add to the list of
781 command-line target recipes you want to build.
Andrew Geissler4873add2020-11-02 18:44:49 -0600783 BBVERSIONS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500784 Allows a single recipe to build multiple versions of a project from a
785 single recipe file. You also able to specify conditional metadata
786 using the :term:`OVERRIDES` mechanism for a
787 single version or for an optionally named range of versions.
789 For more information on ``BBVERSIONS``, see the
790 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variants - class extension mechanism`"
791 section.
Andrew Geissler4873add2020-11-02 18:44:49 -0600793 BITBAKE_UI
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500794 Used to specify the UI module to use when running BitBake. Using this
795 variable is equivalent to using the ``-u`` command-line option.
797 .. note::
799 You must set this variable in the external environment in order
800 for it to work.
Andrew Geissler4873add2020-11-02 18:44:49 -0600802 BUILDNAME
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500803 A name assigned to the build. The name defaults to a datetime stamp
804 of when the build was started but can be defined by the metadata.
Andrew Geissler4873add2020-11-02 18:44:49 -0600806 BZRDIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500807 The directory in which files checked out of a Bazaar system are
808 stored.
Andrew Geissler4873add2020-11-02 18:44:49 -0600810 CACHE
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500811 Specifies the directory BitBake uses to store a cache of the metadata
812 so it does not need to be parsed every time BitBake is started.
Andrew Geissler4873add2020-11-02 18:44:49 -0600814 CVSDIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500815 The directory in which files checked out under the CVS system are
816 stored.
Andrew Geissler4873add2020-11-02 18:44:49 -0600818 DEFAULT_PREFERENCE
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500819 Specifies a weak bias for recipe selection priority.
821 The most common usage of this is variable is to set it to "-1" within
822 a recipe for a development version of a piece of software. Using the
823 variable in this way causes the stable version of the recipe to build
824 by default in the absence of ``PREFERRED_VERSION`` being used to
825 build the development version.
827 .. note::
829 The bias provided by DEFAULT_PREFERENCE is weak and is overridden by
830 :term:`BBFILE_PRIORITY` if that variable is different between two
831 layers that contain different versions of the same recipe.
Andrew Geissler4873add2020-11-02 18:44:49 -0600833 DEPENDS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500834 Lists a recipe's build-time dependencies (i.e. other recipe files).
836 Consider this simple example for two recipes named "a" and "b" that
837 produce similarly named packages. In this example, the ``DEPENDS``
838 statement appears in the "a" recipe: ::
840 DEPENDS = "b"
842 Here, the dependency is such that the ``do_configure`` task for recipe "a"
843 depends on the ``do_populate_sysroot`` task of recipe "b". This means
844 anything that recipe "b" puts into sysroot is available when recipe "a" is
845 configuring itself.
847 For information on runtime dependencies, see the :term:`RDEPENDS`
848 variable.
Andrew Geissler4873add2020-11-02 18:44:49 -0600850 DESCRIPTION
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500851 A long description for the recipe.
Andrew Geissler4873add2020-11-02 18:44:49 -0600853 DL_DIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500854 The central download directory used by the build process to store
855 downloads. By default, ``DL_DIR`` gets files suitable for mirroring for
856 everything except Git repositories. If you want tarballs of Git
857 repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable.
Andrew Geissler4873add2020-11-02 18:44:49 -0600859 EXCLUDE_FROM_WORLD
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500860 Directs BitBake to exclude a recipe from world builds (i.e.
861 ``bitbake world``). During world builds, BitBake locates, parses and
862 builds all recipes found in every layer exposed in the
863 ``bblayers.conf`` configuration file.
865 To exclude a recipe from a world build using this variable, set the
866 variable to "1" in the recipe.
868 .. note::
870 Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a world
871 build in order to satisfy dependencies of other recipes. Adding a
872 recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not
873 explicitly added to the list of build targets in a world build.
Andrew Geissler4873add2020-11-02 18:44:49 -0600875 FAKEROOT
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500876 Contains the command to use when running a shell script in a fakeroot
877 environment. The ``FAKEROOT`` variable is obsolete and has been
878 replaced by the other ``FAKEROOT*`` variables. See these entries in
879 the glossary for more information.
Andrew Geissler4873add2020-11-02 18:44:49 -0600881 FAKEROOTBASEENV
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500882 Lists environment variables to set when executing the command defined
883 by :term:`FAKEROOTCMD` that starts the
884 bitbake-worker process in the fakeroot environment.
Andrew Geissler4873add2020-11-02 18:44:49 -0600886 FAKEROOTCMD
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500887 Contains the command that starts the bitbake-worker process in the
888 fakeroot environment.
Andrew Geissler4873add2020-11-02 18:44:49 -0600890 FAKEROOTDIRS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500891 Lists directories to create before running a task in the fakeroot
892 environment.
Andrew Geissler4873add2020-11-02 18:44:49 -0600894 FAKEROOTENV
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500895 Lists environment variables to set when running a task in the
896 fakeroot environment. For additional information on environment
897 variables and the fakeroot environment, see the
898 :term:`FAKEROOTBASEENV` variable.
Andrew Geissler4873add2020-11-02 18:44:49 -0600900 FAKEROOTNOENV
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500901 Lists environment variables to set when running a task that is not in
902 the fakeroot environment. For additional information on environment
903 variables and the fakeroot environment, see the
904 :term:`FAKEROOTENV` variable.
Andrew Geissler4873add2020-11-02 18:44:49 -0600906 FETCHCMD
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500907 Defines the command the BitBake fetcher module executes when running
908 fetch operations. You need to use an override suffix when you use the
909 variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``).
Andrew Geissler4873add2020-11-02 18:44:49 -0600911 FILE
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500912 Points at the current file. BitBake sets this variable during the
913 parsing process to identify the file being parsed. BitBake also sets
914 this variable when a recipe is being executed to identify the recipe
915 file.
Andrew Geissler4873add2020-11-02 18:44:49 -0600917 FILESPATH
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500918 Specifies directories BitBake uses when searching for patches and
919 files. The "local" fetcher module uses these directories when
920 handling ``file://`` URLs. The variable behaves like a shell ``PATH``
921 environment variable. The value is a colon-separated list of
922 directories that are searched left-to-right in order.
Andrew Geissler4873add2020-11-02 18:44:49 -0600924 GITDIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500925 The directory in which a local copy of a Git repository is stored
926 when it is cloned.
Andrew Geissler4873add2020-11-02 18:44:49 -0600928 HGDIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500929 The directory in which files checked out of a Mercurial system are
930 stored.
Andrew Geissler4873add2020-11-02 18:44:49 -0600932 HOMEPAGE
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500933 Website where more information about the software the recipe is
934 building can be found.
Andrew Geissler4873add2020-11-02 18:44:49 -0600936 INHERIT
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500937 Causes the named class or classes to be inherited globally. Anonymous
938 functions in the class or classes are not executed for the base
939 configuration and in each individual recipe. The OpenEmbedded build
940 system ignores changes to ``INHERIT`` in individual recipes.
942 For more information on ``INHERIT``, see the
943 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
944 section.
Andrew Geissler4873add2020-11-02 18:44:49 -0600946 LAYERDEPENDS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500947 Lists the layers, separated by spaces, upon which this recipe
948 depends. Optionally, you can specify a specific layer version for a
949 dependency by adding it to the end of the layer name with a colon,
950 (e.g. "anotherlayer:3" to be compared against
951 :term:`LAYERVERSION`\ ``_anotherlayer`` in
952 this case). BitBake produces an error if any dependency is missing or
953 the version numbers do not match exactly (if specified).
955 You use this variable in the ``conf/layer.conf`` file. You must also
956 use the specific layer name as a suffix to the variable (e.g.
957 ``LAYERDEPENDS_mylayer``).
Andrew Geissler4873add2020-11-02 18:44:49 -0600959 LAYERDIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500960 When used inside the ``layer.conf`` configuration file, this variable
961 provides the path of the current layer. This variable is not
962 available outside of ``layer.conf`` and references are expanded
963 immediately when parsing of the file completes.
Andrew Geissler4873add2020-11-02 18:44:49 -0600965 LAYERDIR_RE
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500966 When used inside the ``layer.conf`` configuration file, this variable
967 provides the path of the current layer, escaped for use in a regular
968 expression (:term:`BBFILE_PATTERN`). This
969 variable is not available outside of ``layer.conf`` and references
970 are expanded immediately when parsing of the file completes.
Andrew Geissler4873add2020-11-02 18:44:49 -0600972 LAYERVERSION
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500973 Optionally specifies the version of a layer as a single number. You
974 can use this variable within
975 :term:`LAYERDEPENDS` for another layer in
976 order to depend on a specific version of the layer.
978 You use this variable in the ``conf/layer.conf`` file. You must also
979 use the specific layer name as a suffix to the variable (e.g.
980 ``LAYERDEPENDS_mylayer``).
Andrew Geissler4873add2020-11-02 18:44:49 -0600982 LICENSE
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500983 The list of source licenses for the recipe.
Andrew Geissler4873add2020-11-02 18:44:49 -0600985 MIRRORS
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500986 Specifies additional paths from which BitBake gets source code. When
987 the build system searches for source code, it first tries the local
988 download directory. If that location fails, the build system tries
989 locations defined by :term:`PREMIRRORS`, the
990 upstream source, and then locations specified by ``MIRRORS`` in that
991 order.
Andrew Geissler4873add2020-11-02 18:44:49 -0600993 MULTI_PROVIDER_WHITELIST
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500994 Allows you to suppress BitBake warnings caused when building two
995 separate recipes that provide the same output.
997 BitBake normally issues a warning when building two different recipes
998 where each provides the same output. This scenario is usually
999 something the user does not want. However, cases do exist where it
1000 makes sense, particularly in the ``virtual/*`` namespace. You can use
1001 this variable to suppress BitBake's warnings.
1003 To use the variable, list provider names (e.g. recipe names,
1004 ``virtual/kernel``, and so forth).
Andrew Geissler4873add2020-11-02 18:44:49 -06001006 OVERRIDES
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001007 BitBake uses ``OVERRIDES`` to control what variables are overridden
1008 after BitBake parses recipes and configuration files.
1010 Following is a simple example that uses an overrides list based on
1011 machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
1012 find information on how to use ``OVERRIDES`` in the
1013 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax
1014 (overrides)`" section.
Andrew Geissler4873add2020-11-02 18:44:49 -06001016 P4DIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001017 The directory in which a local copy of a Perforce depot is stored
1018 when it is fetched.
Andrew Geissler4873add2020-11-02 18:44:49 -06001020 PACKAGES
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001021 The list of packages the recipe creates.
Andrew Geissler4873add2020-11-02 18:44:49 -06001023 PACKAGES_DYNAMIC
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001024 A promise that your recipe satisfies runtime dependencies for
1025 optional modules that are found in other recipes.
1026 ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it
1027 only states that they should be satisfied. For example, if a hard,
1028 runtime dependency (:term:`RDEPENDS`) of another
1029 package is satisfied during the build through the
1030 ``PACKAGES_DYNAMIC`` variable, but a package with the module name is
1031 never actually produced, then the other package will be broken.
Andrew Geissler4873add2020-11-02 18:44:49 -06001033 PE
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001034 The epoch of the recipe. By default, this variable is unset. The
1035 variable is used to make upgrades possible when the versioning scheme
1036 changes in some backwards incompatible way.
Andrew Geissler4873add2020-11-02 18:44:49 -06001038 PERSISTENT_DIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001039 Specifies the directory BitBake uses to store data that should be
1040 preserved between builds. In particular, the data stored is the data
1041 that uses BitBake's persistent data API and the data used by the PR
1042 Server and PR Service.
Andrew Geissler4873add2020-11-02 18:44:49 -06001044 PF
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001045 Specifies the recipe or package name and includes all version and
1046 revision numbers (i.e. ``eglibc-2.13-r20+svnr15508/`` and
1047 ``bash-4.2-r1/``).
Andrew Geissler4873add2020-11-02 18:44:49 -06001049 PN
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001050 The recipe name.
Andrew Geissler4873add2020-11-02 18:44:49 -06001052 PR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001053 The revision of the recipe.
Andrew Geissler4873add2020-11-02 18:44:49 -06001055 PREFERRED_PROVIDER
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001056 Determines which recipe should be given preference when multiple
1057 recipes provide the same item. You should always suffix the variable
1058 with the name of the provided item, and you should set it to the
1059 :term:`PN` of the recipe to which you want to give
1060 precedence. Some examples: ::
1062 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1063 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1064 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
Andrew Geissler4873add2020-11-02 18:44:49 -06001066 PREFERRED_PROVIDERS
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001067 Determines which recipe should be given preference for cases where
1068 multiple recipes provide the same item. Functionally,
1069 ``PREFERRED_PROVIDERS`` is identical to
1070 :term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable
1071 lets you define preferences for multiple situations using the following
1072 form: ::
1074 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1076 This form is a convenient replacement for the following: ::
1078 PREFERRED_PROVIDER_xxx = "yyy"
1079 PREFERRED_PROVIDER_aaa = "bbb"
Andrew Geissler4873add2020-11-02 18:44:49 -06001081 PREFERRED_VERSION
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001082 If there are multiple versions of recipes available, this variable
1083 determines which recipe should be given preference. You must always
1084 suffix the variable with the :term:`PN` you want to
1085 select, and you should set :term:`PV` accordingly for
1086 precedence.
1088 The ``PREFERRED_VERSION`` variable supports limited wildcard use
1089 through the "``%``" character. You can use the character to match any
1090 number of characters, which can be useful when specifying versions
1091 that contain long revision numbers that potentially change. Here are
1092 two examples: ::
1094 PREFERRED_VERSION_python = "2.7.3"
1095 PREFERRED_VERSION_linux-yocto = "4.12%"
1097 .. important::
1099 The use of the " % " character is limited in that it only works at the
1100 end of the string. You cannot use the wildcard character in any other
1101 location of the string.
Andrew Geissler4873add2020-11-02 18:44:49 -06001103 PREMIRRORS
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001104 Specifies additional paths from which BitBake gets source code. When
1105 the build system searches for source code, it first tries the local
1106 download directory. If that location fails, the build system tries
1107 locations defined by ``PREMIRRORS``, the upstream source, and then
1108 locations specified by :term:`MIRRORS` in that order.
1110 Typically, you would add a specific server for the build system to
1111 attempt before any others by adding something like the following to
1112 your configuration: ::
1114 PREMIRRORS_prepend = "\
1115 git://.*/.* \n \
1116 ftp://.*/.* \n \
1117 http://.*/.* \n \
1118 https://.*/.* \n"
1120 These changes cause the build system to intercept Git, FTP, HTTP, and
1121 HTTPS requests and direct them to the ``http://`` sources mirror. You can
1122 use ``file://`` URLs to point to local directories or network shares as
1123 well.
Andrew Geissler4873add2020-11-02 18:44:49 -06001125 PROVIDES
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001126 A list of aliases by which a particular recipe can be known. By
1127 default, a recipe's own ``PN`` is implicitly already in its
1128 ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional
1129 aliases are synonyms for the recipe and can be useful satisfying
1130 dependencies of other recipes during the build as specified by
1131 ``DEPENDS``.
1133 Consider the following example ``PROVIDES`` statement from a recipe
1134 file ````: ::
1136 PROVIDES += "libpostproc"
1138 The ``PROVIDES`` statement results in the "libav" recipe also being known
1139 as "libpostproc".
1141 In addition to providing recipes under alternate names, the
1142 ``PROVIDES`` mechanism is also used to implement virtual targets. A
1143 virtual target is a name that corresponds to some particular
1144 functionality (e.g. a Linux kernel). Recipes that provide the
1145 functionality in question list the virtual target in ``PROVIDES``.
1146 Recipes that depend on the functionality in question can include the
1147 virtual target in :term:`DEPENDS` to leave the
1148 choice of provider open.
1150 Conventionally, virtual targets have names on the form
1151 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
1152 of the name and has no syntactical significance.
Andrew Geissler4873add2020-11-02 18:44:49 -06001154 PRSERV_HOST
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001155 The network based :term:`PR` service host and port.
1157 Following is an example of how the ``PRSERV_HOST`` variable is set: ::
1159 PRSERV_HOST = "localhost:0"
1161 You must set the variable if you want to automatically start a local PR
1162 service. You can set ``PRSERV_HOST`` to other values to use a remote PR
1163 service.
Andrew Geissler4873add2020-11-02 18:44:49 -06001165 PV
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001166 The version of the recipe.
Andrew Geissler4873add2020-11-02 18:44:49 -06001168 RDEPENDS
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001169 Lists a package's runtime dependencies (i.e. other packages) that
1170 must be installed in order for the built package to run correctly. If
1171 a package in this list cannot be found during the build, you will get
1172 a build error.
1174 Because the ``RDEPENDS`` variable applies to packages being built,
1175 you should always use the variable in a form with an attached package
1176 name. For example, suppose you are building a development package
1177 that depends on the ``perl`` package. In this case, you would use the
1178 following ``RDEPENDS`` statement: ::
1180 RDEPENDS_${PN}-dev += "perl"
1182 In the example, the development package depends on the ``perl`` package.
1183 Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part
1184 of the variable.
1186 BitBake supports specifying versioned dependencies. Although the
1187 syntax varies depending on the packaging format, BitBake hides these
1188 differences from you. Here is the general syntax to specify versions
1189 with the ``RDEPENDS`` variable: ::
1191 RDEPENDS_${PN} = "package (operator version)"
1193 For ``operator``, you can specify the following: ::
1195 =
1196 <
1197 >
1198 <=
1199 >=
1201 For example, the following sets up a dependency on version 1.2 or
1202 greater of the package ``foo``: ::
1204 RDEPENDS_${PN} = "foo (>= 1.2)"
1206 For information on build-time dependencies, see the :term:`DEPENDS`
1207 variable.
Andrew Geissler4873add2020-11-02 18:44:49 -06001209 REPODIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001210 The directory in which a local copy of a ``google-repo`` directory is
1211 stored when it is synced.
Andrew Geissler4873add2020-11-02 18:44:49 -06001213 RPROVIDES
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001214 A list of package name aliases that a package also provides. These
1215 aliases are useful for satisfying runtime dependencies of other
1216 packages both during the build and on the target (as specified by
1217 ``RDEPENDS``).
1219 As with all package-controlling variables, you must always use the
1220 variable in conjunction with a package name override. Here is an
1221 example: ::
1223 RPROVIDES_${PN} = "widget-abi-2"
Andrew Geissler4873add2020-11-02 18:44:49 -06001225 RRECOMMENDS
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001226 A list of packages that extends the usability of a package being
1227 built. The package being built does not depend on this list of
1228 packages in order to successfully build, but needs them for the
1229 extended usability. To specify runtime dependencies for packages, see
1230 the ``RDEPENDS`` variable.
1232 BitBake supports specifying versioned recommends. Although the syntax
1233 varies depending on the packaging format, BitBake hides these
1234 differences from you. Here is the general syntax to specify versions
1235 with the ``RRECOMMENDS`` variable: ::
1237 RRECOMMENDS_${PN} = "package (operator version)"
1239 For ``operator``, you can specify the following: ::
1241 =
1242 <
1243 >
1244 <=
1245 >=
1247 For example, the following sets up a recommend on version
1248 1.2 or greater of the package ``foo``: ::
1250 RRECOMMENDS_${PN} = "foo (>= 1.2)"
Andrew Geissler4873add2020-11-02 18:44:49 -06001252 SECTION
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001253 The section in which packages should be categorized.
Andrew Geissler4873add2020-11-02 18:44:49 -06001255 SRC_URI
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001256 The list of source files - local or remote. This variable tells
1257 BitBake which bits to pull for the build and how to pull them. For
1258 example, if the recipe or append file needs to fetch a single tarball
1259 from the Internet, the recipe or append file uses a ``SRC_URI`` entry
1260 that specifies that tarball. On the other hand, if the recipe or
1261 append file needs to fetch a tarball and include a custom file, the
1262 recipe or append file needs an ``SRC_URI`` variable that specifies
1263 all those sources.
1265 The following list explains the available URI protocols:
1267 - ``file://`` : Fetches files, which are usually files shipped
1268 with the metadata, from the local machine. The path is relative to
1269 the :term:`FILESPATH` variable.
1271 - ``bzr://`` : Fetches files from a Bazaar revision control
1272 repository.
1274 - ``git://`` : Fetches files from a Git revision control
1275 repository.
1277 - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service)
1278 revision control repository.
1280 - ``repo://`` : Fetches files from a repo (Git) repository.
1282 - ``http://`` : Fetches files from the Internet using HTTP.
1284 - ``https://`` : Fetches files from the Internet using HTTPS.
1286 - ``ftp://`` : Fetches files from the Internet using FTP.
1288 - ``cvs://`` : Fetches files from a CVS revision control
1289 repository.
1291 - ``hg://`` : Fetches files from a Mercurial (``hg``) revision
1292 control repository.
1294 - ``p4://`` : Fetches files from a Perforce (``p4``) revision
1295 control repository.
1297 - ``ssh://`` : Fetches files from a secure shell.
1299 - ``svn://`` : Fetches files from a Subversion (``svn``) revision
1300 control repository.
1302 Here are some additional options worth mentioning:
1304 - ``unpack`` : Controls whether or not to unpack the file if it is
1305 an archive. The default action is to unpack the file.
1307 - ``subdir`` : Places the file (or extracts its contents) into the
1308 specified subdirectory. This option is useful for unusual tarballs
1309 or other archives that do not have their files already in a
1310 subdirectory within the archive.
1312 - ``name`` : Specifies a name to be used for association with
1313 ``SRC_URI`` checksums when you have more than one file specified
1314 in ``SRC_URI``.
1316 - ``downloadfilename`` : Specifies the filename used when storing
1317 the downloaded file.
Andrew Geissler4873add2020-11-02 18:44:49 -06001319 SRCDATE
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001320 The date of the source code used to build the package. This variable
1321 applies only if the source was fetched from a Source Code Manager
1322 (SCM).
Andrew Geissler4873add2020-11-02 18:44:49 -06001324 SRCREV
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001325 The revision of the source code used to build the package. This
1326 variable applies only when using Subversion, Git, Mercurial and
1327 Bazaar. If you want to build a fixed revision and you want to avoid
1328 performing a query on the remote repository every time BitBake parses
1329 your recipe, you should specify a ``SRCREV`` that is a full revision
1330 identifier and not just a tag.
Andrew Geissler4873add2020-11-02 18:44:49 -06001332 SRCREV_FORMAT
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001333 Helps construct valid :term:`SRCREV` values when
1334 multiple source controlled URLs are used in
1335 :term:`SRC_URI`.
1337 The system needs help constructing these values under these
1338 circumstances. Each component in the ``SRC_URI`` is assigned a name
1339 and these are referenced in the ``SRCREV_FORMAT`` variable. Consider
1340 an example with URLs named "machine" and "meta". In this case,
1341 ``SRCREV_FORMAT`` could look like "machine_meta" and those names
1342 would have the SCM versions substituted into each position. Only one
1343 ``AUTOINC`` placeholder is added and if needed. And, this placeholder
1344 is placed at the start of the returned string.
Andrew Geissler4873add2020-11-02 18:44:49 -06001346 STAMP
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001347 Specifies the base path used to create recipe stamp files. The path
1348 to an actual stamp file is constructed by evaluating this string and
1349 then appending additional information.
Andrew Geissler4873add2020-11-02 18:44:49 -06001351 STAMPCLEAN
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001352 Specifies the base path used to create recipe stamp files. Unlike the
1353 :term:`STAMP` variable, ``STAMPCLEAN`` can contain
1354 wildcards to match the range of files a clean operation should
1355 remove. BitBake uses a clean operation to remove any other stamps it
1356 should be removing when creating a new stamp.
Andrew Geissler4873add2020-11-02 18:44:49 -06001358 SUMMARY
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001359 A short summary for the recipe, which is 72 characters or less.
Andrew Geissler4873add2020-11-02 18:44:49 -06001361 SVNDIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001362 The directory in which files checked out of a Subversion system are
1363 stored.
Andrew Geissler4873add2020-11-02 18:44:49 -06001365 T
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001366 Points to a directory were BitBake places temporary files, which
1367 consist mostly of task logs and scripts, when building a particular
1368 recipe.
Andrew Geissler4873add2020-11-02 18:44:49 -06001370 TOPDIR
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001371 Points to the build directory. BitBake automatically sets this
1372 variable.