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