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