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