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