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