1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3****************** 4Variables Glossary 5****************** 6 7This chapter lists common variables used in the OpenEmbedded build 8system and gives an overview of their function and contents. 9 10:term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>` 11:term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FEATURE_PACKAGES>` 12:term:`G <GCCPIE>` :term:`H <HOMEPAGE>` :term:`I <ICECC_DISABLED>` 13:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>` 14:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P` 15:term:`R <RANLIB>` :term:`S` :term:`T` 16:term:`U <UBOOT_CONFIG>` :term:`V <VOLATILE_LOG_DIR>` 17:term:`W <WARN_QA>` :term:`X <XSERVER>` 18 19.. glossary:: 20 :sorted: 21 22 :term:`ABIEXTENSION` 23 Extension to the Application Binary Interface (ABI) field of the GNU 24 canonical architecture name (e.g. "eabi"). 25 26 ABI extensions are set in the machine include files. For example, the 27 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the 28 following extension:: 29 30 ABIEXTENSION = "eabi" 31 32 :term:`ALLOW_EMPTY` 33 Specifies whether to produce an output package even if it is empty. 34 By default, BitBake does not produce empty packages. This default 35 behavior can cause issues when there is an 36 :term:`RDEPENDS` or some other hard runtime 37 requirement on the existence of the package. 38 39 Like all package-controlling variables, you must always use them in 40 conjunction with a package name override, as in:: 41 42 ALLOW_EMPTY:${PN} = "1" 43 ALLOW_EMPTY:${PN}-dev = "1" 44 ALLOW_EMPTY:${PN}-staticdev = "1" 45 46 :term:`ALTERNATIVE` 47 Lists commands in a package that need an alternative binary naming 48 scheme. Sometimes the same command is provided in multiple packages. 49 When this occurs, the OpenEmbedded build system needs to use the 50 alternatives system to create a different binary naming scheme so the 51 commands can co-exist. 52 53 To use the variable, list out the package's commands that are also 54 provided by another package. For example, if the ``busybox`` package 55 has four such commands, you identify them as follows:: 56 57 ALTERNATIVE:busybox = "sh sed test bracket" 58 59 For more information on the alternatives system, see the 60 ":ref:`ref-classes-update-alternatives`" 61 section. 62 63 :term:`ALTERNATIVE_LINK_NAME` 64 Used by the alternatives system to map duplicated commands to actual 65 locations. For example, if the ``bracket`` command provided by the 66 ``busybox`` package is duplicated through another package, you must 67 use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual 68 location:: 69 70 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" 71 72 In this example, the binary for the ``bracket`` command (i.e. ``[``) 73 from the ``busybox`` package resides in ``/usr/bin/``. 74 75 .. note:: 76 77 If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``. 78 79 For more information on the alternatives system, see the 80 ":ref:`ref-classes-update-alternatives`" 81 section. 82 83 :term:`ALTERNATIVE_PRIORITY` 84 Used by the alternatives system to create default priorities for 85 duplicated commands. You can use the variable to create a single 86 default regardless of the command name or package, a default for 87 specific duplicated commands regardless of the package, or a default 88 for specific commands tied to particular packages. Here are the 89 available syntax forms:: 90 91 ALTERNATIVE_PRIORITY = "priority" 92 ALTERNATIVE_PRIORITY[name] = "priority" 93 ALTERNATIVE_PRIORITY_pkg[name] = "priority" 94 95 For more information on the alternatives system, see the 96 ":ref:`ref-classes-update-alternatives`" 97 section. 98 99 :term:`ALTERNATIVE_TARGET` 100 Used by the alternatives system to create default link locations for 101 duplicated commands. You can use the variable to create a single 102 default location for all duplicated commands regardless of the 103 command name or package, a default for specific duplicated commands 104 regardless of the package, or a default for specific commands tied to 105 particular packages. Here are the available syntax forms:: 106 107 ALTERNATIVE_TARGET = "target" 108 ALTERNATIVE_TARGET[name] = "target" 109 ALTERNATIVE_TARGET_pkg[name] = "target" 110 111 .. note:: 112 113 If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value 114 from the :term:`ALTERNATIVE_LINK_NAME` variable. 115 116 If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the 117 same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``" 118 appended to it. 119 120 Finally, if the file referenced has not been renamed, the 121 alternatives system will rename it to avoid the need to rename 122 alternative files in the :ref:`ref-tasks-install` 123 task while retaining support for the command if necessary. 124 125 For more information on the alternatives system, see the 126 ":ref:`ref-classes-update-alternatives`" section. 127 128 :term:`ANY_OF_DISTRO_FEATURES` 129 When inheriting the :ref:`ref-classes-features_check` 130 class, this variable identifies a list of distribution features where 131 at least one must be enabled in the current configuration in order 132 for the OpenEmbedded build system to build the recipe. In other words, 133 if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES` 134 appear in :term:`DISTRO_FEATURES` within the current configuration, then 135 the recipe will be skipped, and if the build system attempts to build 136 the recipe then an error will be triggered. 137 138 :term:`APPEND` 139 An override list of append strings for each target specified with 140 :term:`LABELS`. 141 142 See the :ref:`ref-classes-grub-efi` class for more 143 information on how this variable is used. 144 145 :term:`AR` 146 The minimal command and arguments used to run ``ar``. 147 148 :term:`ARCHIVER_MODE` 149 When used with the :ref:`ref-classes-archiver` class, 150 determines the type of information used to create a released archive. 151 You can use this variable to create archives of patched source, 152 original source, configured source, and so forth by employing the 153 following variable flags (varflags):: 154 155 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. 156 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. 157 ARCHIVER_MODE[src] = "configured" # Uses configured source files. 158 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch. 159 ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff. 160 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data. 161 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files. 162 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files. 163 164 For information on how the variable works, see the 165 ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`. 166 167 :term:`AS` 168 Minimal command and arguments needed to run the assembler. 169 170 :term:`ASSUME_PROVIDED` 171 Lists recipe names (:term:`PN` values) BitBake does not 172 attempt to build. Instead, BitBake assumes these recipes have already 173 been built. 174 175 In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native 176 tools that should not be built. An example is ``git-native``, which 177 when specified, allows for the Git binary from the host to be used 178 rather than building ``git-native``. 179 180 :term:`ASSUME_SHLIBS` 181 Provides additional ``shlibs`` provider mapping information, which 182 adds to or overwrites the information provided automatically by the 183 system. Separate multiple entries using spaces. 184 185 As an example, use the following form to add an ``shlib`` provider of 186 shlibname in packagename with the optional version:: 187 188 shlibname:packagename[_version] 189 190 Here is an example that adds a shared library named ``libEGL.so.1`` 191 as being provided by the ``libegl-implementation`` package:: 192 193 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" 194 195 :term:`AUTHOR` 196 The email address used to contact the original author or authors in 197 order to send patches and forward bugs. 198 199 :term:`AUTO_LIBNAME_PKGS` 200 When the :ref:`ref-classes-debian` class is inherited, 201 which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which 202 packages should be checked for libraries and renamed according to 203 Debian library package naming. 204 205 The default value is "${PACKAGES}", which causes the 206 :ref:`ref-classes-debian` class to act on all packages that are 207 explicitly generated by the recipe. 208 209 :term:`AUTOREV` 210 When :term:`SRCREV` is set to the value of this variable, it specifies to 211 use the latest source revision in the repository. Here is an example:: 212 213 SRCREV = "${AUTOREV}" 214 215 If you use the previous statement to retrieve the latest version of 216 software, you need to be sure :term:`PV` contains 217 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you have a kernel 218 recipe that inherits the :ref:`ref-classes-kernel` class and you 219 use the previous statement. In this example, ``${SRCPV}`` does not 220 automatically get into :term:`PV`. Consequently, you need to change 221 :term:`PV` in your recipe so that it does contain ``${SRCPV}``. 222 223 For more information see the 224 ":ref:`dev-manual/packages:automatically incrementing a package version number`" 225 section in the Yocto Project Development Tasks Manual. 226 227 :term:`AUTO_SYSLINUXMENU` 228 Enables creating an automatic menu for the syslinux bootloader. You 229 must set this variable in your recipe. The 230 :ref:`ref-classes-syslinux` class checks this variable. 231 232 :term:`AVAILTUNES` 233 The list of defined CPU and Application Binary Interface (ABI) 234 tunings (i.e. "tunes") available for use by the OpenEmbedded build 235 system. 236 237 The list simply presents the tunes that are available. Not all tunes 238 may be compatible with a particular machine configuration, or with 239 each other in a 240 :ref:`Multilib <dev-manual/libraries:combining multiple versions of library files into one image>` 241 configuration. 242 243 To add a tune to the list, be sure to append it with spaces using the 244 "+=" BitBake operator. Do not simply replace the list by using the 245 "=" operator. See the 246 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake 247 User Manual for more information. 248 249 :term:`AZ_SAS` 250 Azure Storage Shared Access Signature, when using the 251 :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` 252 This variable can be defined to be used by the fetcher to authenticate 253 and gain access to non-public artifacts:: 254 255 AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>"" 256 257 For more information see Microsoft's Azure Storage documentation at 258 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview 259 260 :term:`B` 261 The directory within the :term:`Build Directory` in which the 262 OpenEmbedded build system places generated objects during a recipe's 263 build process. By default, this directory is the same as the 264 :term:`S` directory, which is defined as:: 265 266 S = "${WORKDIR}/${BP}" 267 268 You can separate the (:term:`S`) directory and the directory pointed to 269 by the :term:`B` variable. Most Autotools-based recipes support 270 separating these directories. The build system defaults to using 271 separate directories for ``gcc`` and some kernel recipes. 272 273 :term:`BAD_RECOMMENDATIONS` 274 Lists "recommended-only" packages to not install. Recommended-only 275 packages are packages installed only through the 276 :term:`RRECOMMENDS` variable. You can prevent any 277 of these "recommended" packages from being installed by listing them 278 with the :term:`BAD_RECOMMENDATIONS` variable:: 279 280 BAD_RECOMMENDATIONS = "package_name package_name package_name ..." 281 282 You can set this variable globally in your ``local.conf`` file or you 283 can attach it to a specific image recipe by using the recipe name 284 override:: 285 286 BAD_RECOMMENDATIONS:pn-target_image = "package_name" 287 288 It is important to realize that if you choose to not install packages 289 using this variable and some other packages are dependent on them 290 (i.e. listed in a recipe's :term:`RDEPENDS` 291 variable), the OpenEmbedded build system ignores your request and 292 will install the packages to avoid dependency errors. 293 294 This variable is supported only when using the IPK and RPM 295 packaging backends. DEB is not supported. 296 297 See the :term:`NO_RECOMMENDATIONS` and the 298 :term:`PACKAGE_EXCLUDE` variables for related 299 information. 300 301 :term:`BASE_LIB` 302 The library directory name for the CPU or Application Binary 303 Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib 304 context. See the ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`" 305 section in the Yocto Project Development Tasks Manual for information 306 on Multilib. 307 308 The :term:`BASE_LIB` variable is defined in the machine include files in 309 the :term:`Source Directory`. If Multilib is not 310 being used, the value defaults to "lib". 311 312 :term:`BASE_WORKDIR` 313 Points to the base of the work directory for all recipes. The default 314 value is "${TMPDIR}/work". 315 316 :term:`BB_ALLOWED_NETWORKS` 317 Specifies a space-delimited list of hosts that the fetcher is allowed 318 to use to obtain the required source code. Following are 319 considerations surrounding this variable: 320 321 - This host list is only used if :term:`BB_NO_NETWORK` is either not set 322 or set to "0". 323 324 - There is limited support for wildcard matching against the beginning of 325 host names. For example, the following setting matches 326 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``:: 327 328 BB_ALLOWED_NETWORKS = "*.gnu.org" 329 330 .. note:: 331 332 The use of the "``*``" character only works at the beginning of 333 a host name and it must be isolated from the remainder of the 334 host name. You cannot use the wildcard character in any other 335 location of the name or combined with the front part of the 336 name. 337 338 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` 339 is not. 340 341 - Mirrors not in the host list are skipped and logged in debug. 342 343 - Attempts to access networks not in the host list cause a failure. 344 345 Using :term:`BB_ALLOWED_NETWORKS` in conjunction with 346 :term:`PREMIRRORS` is very useful. Adding the host 347 you want to use to :term:`PREMIRRORS` results in the source code being 348 fetched from an allowed location and avoids raising an error when a 349 host that is not allowed is in a :term:`SRC_URI` 350 statement. This is because the fetcher does not attempt to use the 351 host listed in :term:`SRC_URI` after a successful fetch from the 352 :term:`PREMIRRORS` occurs. 353 354 :term:`BB_BASEHASH_IGNORE_VARS` 355 See :term:`bitbake:BB_BASEHASH_IGNORE_VARS` in the BitBake manual. 356 357 :term:`BB_CACHEDIR` 358 See :term:`bitbake:BB_CACHEDIR` in the BitBake manual. 359 360 :term:`BB_CHECK_SSL_CERTS` 361 See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual. 362 363 :term:`BB_CONSOLELOG` 364 See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual. 365 366 :term:`BB_CURRENTTASK` 367 See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual. 368 369 :term:`BB_DANGLINGAPPENDS_WARNONLY` 370 Defines how BitBake handles situations where an append file 371 (``.bbappend``) has no corresponding recipe file (``.bb``). This 372 condition often occurs when layers get out of sync (e.g. ``oe-core`` 373 bumps a recipe version and the old recipe no longer exists and the 374 other layer has not been updated to the new version of the recipe 375 yet). 376 377 The default fatal behavior is safest because it is the sane reaction 378 given something is out of sync. It is important to realize when your 379 changes are no longer being applied. 380 381 You can change the default behavior by setting this variable to "1", 382 "yes", or "true" in your ``local.conf`` file, which is located in the 383 :term:`Build Directory`: Here is an example:: 384 385 BB_DANGLINGAPPENDS_WARNONLY = "1" 386 387 :term:`BB_DEFAULT_TASK` 388 See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual. 389 390 :term:`BB_DEFAULT_UMASK` 391 See :term:`bitbake:BB_DEFAULT_UMASK` in the BitBake manual. 392 393 :term:`BB_DISKMON_DIRS` 394 Monitors disk space and available inodes during the build and allows 395 you to control the build based on these parameters. 396 397 Disk space monitoring is disabled by default. To enable monitoring, 398 add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file 399 found in the :term:`Build Directory`. Use the 400 following form: 401 402 .. code-block:: none 403 404 BB_DISKMON_DIRS = "action,dir,threshold [...]" 405 406 where: 407 408 action is: 409 ABORT: Immediately stop the build when 410 a threshold is broken. 411 STOPTASKS: Stop the build after the currently 412 executing tasks have finished when 413 a threshold is broken. 414 WARN: Issue a warning but continue the 415 build when a threshold is broken. 416 Subsequent warnings are issued as 417 defined by the BB_DISKMON_WARNINTERVAL 418 variable, which must be defined in 419 the conf/local.conf file. 420 421 dir is: 422 Any directory you choose. You can specify one or 423 more directories to monitor by separating the 424 groupings with a space. If two directories are 425 on the same device, only the first directory 426 is monitored. 427 428 threshold is: 429 Either the minimum available disk space, 430 the minimum number of free inodes, or 431 both. You must specify at least one. To 432 omit one or the other, simply omit the value. 433 Specify the threshold using G, M, K for Gbytes, 434 Mbytes, and Kbytes, respectively. If you do 435 not specify G, M, or K, Kbytes is assumed by 436 default. Do not use GB, MB, or KB. 437 438 Here are some examples:: 439 440 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" 441 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" 442 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" 443 444 The first example works only if you also provide the 445 :term:`BB_DISKMON_WARNINTERVAL` 446 variable in the ``conf/local.conf``. This example causes the build 447 system to immediately stop when either the disk space in 448 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops 449 below 100 Kbytes. Because two directories are provided with the 450 variable, the build system also issue a warning when the disk space 451 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number 452 of free inodes drops below 100 Kbytes. Subsequent warnings are issued 453 during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL` 454 variable. 455 456 The second example stops the build after all currently executing 457 tasks complete when the minimum disk space in the ``${TMPDIR}`` 458 directory drops below 1 Gbyte. No disk monitoring occurs for the free 459 inodes in this case. 460 461 The final example immediately stops the build when the number of 462 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No 463 disk space monitoring for the directory itself occurs in this case. 464 465 :term:`BB_DISKMON_WARNINTERVAL` 466 Defines the disk space and free inode warning intervals. To set these 467 intervals, define the variable in your ``conf/local.conf`` file in 468 the :term:`Build Directory`. 469 470 If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you 471 must also use the :term:`BB_DISKMON_DIRS` 472 variable and define its action as "WARN". During the build, 473 subsequent warnings are issued each time disk space or number of free 474 inodes further reduces by the respective interval. 475 476 If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you 477 do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk 478 monitoring interval defaults to the following:: 479 480 BB_DISKMON_WARNINTERVAL = "50M,5K" 481 482 When specifying the variable in your configuration file, use the 483 following form: 484 485 .. code-block:: none 486 487 BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval" 488 489 where: 490 491 disk_space_interval is: 492 An interval of memory expressed in either 493 G, M, or K for Gbytes, Mbytes, or Kbytes, 494 respectively. You cannot use GB, MB, or KB. 495 496 disk_inode_interval is: 497 An interval of free inodes expressed in either 498 G, M, or K for Gbytes, Mbytes, or Kbytes, 499 respectively. You cannot use GB, MB, or KB. 500 501 Here is an example:: 502 503 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 504 BB_DISKMON_WARNINTERVAL = "50M,5K" 505 506 These variables cause the 507 OpenEmbedded build system to issue subsequent warnings each time the 508 available disk space further reduces by 50 Mbytes or the number of 509 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` 510 directory. Subsequent warnings based on the interval occur each time 511 a respective interval is reached beyond the initial warning (i.e. 1 512 Gbytes and 100 Kbytes). 513 514 :term:`BB_ENV_PASSTHROUGH` 515 See :term:`bitbake:BB_ENV_PASSTHROUGH` in the BitBake manual. 516 517 :term:`BB_ENV_PASSTHROUGH_ADDITIONS` 518 See :term:`bitbake:BB_ENV_PASSTHROUGH_ADDITIONS` in the BitBake manual. 519 520 :term:`BB_FETCH_PREMIRRORONLY` 521 See :term:`bitbake:BB_FETCH_PREMIRRORONLY` in the BitBake manual. 522 523 :term:`BB_FILENAME` 524 See :term:`bitbake:BB_FILENAME` in the BitBake manual. 525 526 :term:`BB_GENERATE_MIRROR_TARBALLS` 527 Causes tarballs of the source control repositories (e.g. Git 528 repositories), including metadata, to be placed in the 529 :term:`DL_DIR` directory. 530 531 For performance reasons, creating and placing tarballs of these 532 repositories is not the default action by the OpenEmbedded build 533 system:: 534 535 BB_GENERATE_MIRROR_TARBALLS = "1" 536 537 Set this variable in your 538 ``local.conf`` file in the :term:`Build Directory`. 539 540 Once you have the tarballs containing your source files, you can 541 clean up your :term:`DL_DIR` directory by deleting any Git or other 542 source control work directories. 543 544 :term:`BB_GENERATE_SHALLOW_TARBALLS` 545 See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual. 546 547 :term:`BB_GIT_SHALLOW` 548 See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual. 549 550 :term:`BB_GIT_SHALLOW_DEPTH` 551 See :term:`bitbake:BB_GIT_SHALLOW_DEPTH` in the BitBake manual. 552 553 :term:`BB_HASHCHECK_FUNCTION` 554 See :term:`bitbake:BB_HASHCHECK_FUNCTION` in the BitBake manual. 555 556 :term:`BB_HASHCONFIG_IGNORE_VARS` 557 See :term:`bitbake:BB_HASHCONFIG_IGNORE_VARS` in the BitBake manual. 558 559 :term:`BB_HASHSERVE` 560 See :term:`bitbake:BB_HASHSERVE` in the BitBake manual. 561 562 :term:`BB_HASHSERVE_UPSTREAM` 563 See :term:`bitbake:BB_HASHSERVE_UPSTREAM` in the BitBake manual. 564 565 :term:`BB_INVALIDCONF` 566 See :term:`bitbake:BB_INVALIDCONF` in the BitBake manual. 567 568 :term:`BB_LOGCONFIG` 569 See :term:`bitbake:BB_LOGCONFIG` in the BitBake manual. 570 571 :term:`BB_LOGFMT` 572 See :term:`bitbake:BB_LOGFMT` in the BitBake manual. 573 574 :term:`BB_MULTI_PROVIDER_ALLOWED` 575 See :term:`bitbake:BB_MULTI_PROVIDER_ALLOWED` in the BitBake manual. 576 577 :term:`BB_NICE_LEVEL` 578 See :term:`bitbake:BB_NICE_LEVEL` in the BitBake manual. 579 580 :term:`BB_NO_NETWORK` 581 See :term:`bitbake:BB_NO_NETWORK` in the BitBake manual. 582 583 :term:`BB_NUMBER_PARSE_THREADS` 584 See :term:`bitbake:BB_NUMBER_PARSE_THREADS` in the BitBake manual. 585 586 :term:`BB_NUMBER_THREADS` 587 The maximum number of tasks BitBake should run in parallel at any one 588 time. The OpenEmbedded build system automatically configures this 589 variable to be equal to the number of cores on the build system. For 590 example, a system with a dual core processor that also uses 591 hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default 592 to "4". 593 594 For single socket systems (i.e. one CPU), you should not have to 595 override this variable to gain optimal parallelism during builds. 596 However, if you have very large systems that employ multiple physical 597 CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable 598 is not set higher than "20". 599 600 For more information on speeding up builds, see the 601 ":ref:`dev-manual/speeding-up-build:speeding up a build`" 602 section in the Yocto Project Development Tasks Manual. 603 604 On the other hand, if your goal is to limit the amount of system 605 resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS` 606 to a number lower than the number of CPU threads in your machine 607 won't be sufficient. That's because each package will still be built 608 and installed through a number of parallel jobs specified by the 609 :term:`PARALLEL_MAKE` variable, which is by default the number of CPU 610 threads in your system, and is not impacted by the 611 :term:`BB_NUMBER_THREADS` value. 612 613 So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set 614 :term:`PARALLEL_MAKE`, most of your system resources will be consumed 615 anyway. 616 617 Therefore, if you intend to reduce the load of your build system by 618 setting :term:`BB_NUMBER_THREADS` to a relatively low value compared 619 to the number of CPU threads on your system, you should also set 620 :term:`PARALLEL_MAKE` to a similarly low value. 621 622 An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage 623 of build system resources under control is to use the smarter 624 :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or 625 :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake 626 from starting new tasks as long as thresholds are exceeded. Anyway, 627 as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the 628 tasks already being run from using all CPU threads on the system 629 if :term:`PARALLEL_MAKE` is not set to a low value. 630 631 :term:`BB_ORIGENV` 632 See :term:`bitbake:BB_ORIGENV` in the BitBake manual. 633 634 :term:`BB_PRESERVE_ENV` 635 See :term:`bitbake:BB_PRESERVE_ENV` in the BitBake manual. 636 637 :term:`BB_PRESSURE_MAX_CPU` 638 See :term:`bitbake:BB_PRESSURE_MAX_CPU` in the BitBake manual. 639 640 :term:`BB_PRESSURE_MAX_IO` 641 See :term:`bitbake:BB_PRESSURE_MAX_IO` in the BitBake manual. 642 643 :term:`BB_PRESSURE_MAX_MEMORY` 644 See :term:`bitbake:BB_PRESSURE_MAX_MEMORY` in the BitBake manual. 645 646 :term:`BB_RUNFMT` 647 See :term:`bitbake:BB_RUNFMT` in the BitBake manual. 648 649 :term:`BB_RUNTASK` 650 See :term:`bitbake:BB_RUNTASK` in the BitBake manual. 651 652 :term:`BB_SCHEDULER` 653 See :term:`bitbake:BB_SCHEDULER` in the BitBake manual. 654 655 :term:`BB_SCHEDULERS` 656 See :term:`bitbake:BB_SCHEDULERS` in the BitBake manual. 657 658 :term:`BB_SERVER_TIMEOUT` 659 Specifies the time (in seconds) after which to unload the BitBake 660 server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how 661 long the BitBake server stays resident between invocations. 662 663 For example, the following statement in your ``local.conf`` file 664 instructs the server to be unloaded after 20 seconds of inactivity:: 665 666 BB_SERVER_TIMEOUT = "20" 667 668 If you want the server to never be unloaded, 669 set :term:`BB_SERVER_TIMEOUT` to "-1". 670 671 :term:`BB_SETSCENE_DEPVALID` 672 See :term:`bitbake:BB_SETSCENE_DEPVALID` in the BitBake manual. 673 674 :term:`BB_SIGNATURE_EXCLUDE_FLAGS` 675 See :term:`bitbake:BB_SIGNATURE_EXCLUDE_FLAGS` in the BitBake manual. 676 677 :term:`BB_SIGNATURE_HANDLER` 678 See :term:`bitbake:BB_SIGNATURE_HANDLER` in the BitBake manual. 679 680 :term:`BB_SRCREV_POLICY` 681 See :term:`bitbake:BB_SRCREV_POLICY` in the BitBake manual. 682 683 :term:`BB_STRICT_CHECKSUM` 684 See :term:`bitbake:BB_STRICT_CHECKSUM` in the BitBake manual. 685 686 :term:`BB_TASK_IONICE_LEVEL` 687 See :term:`bitbake:BB_TASK_IONICE_LEVEL` in the BitBake manual. 688 689 :term:`BB_TASK_NICE_LEVEL` 690 See :term:`bitbake:BB_TASK_NICE_LEVEL` in the BitBake manual. 691 692 :term:`BB_TASKHASH` 693 See :term:`bitbake:BB_TASKHASH` in the BitBake manual. 694 695 :term:`BB_VERBOSE_LOGS` 696 See :term:`bitbake:BB_VERBOSE_LOGS` in the BitBake manual. 697 698 :term:`BB_WORKERCONTEXT` 699 See :term:`bitbake:BB_WORKERCONTEXT` in the BitBake manual. 700 701 :term:`BBCLASSEXTEND` 702 Allows you to extend a recipe so that it builds variants of the 703 software. There are common variants for recipes as "natives" like 704 ``quilt-native``, which is a copy of Quilt built to run on the build 705 system; "crosses" such as ``gcc-cross``, which is a compiler built to 706 run on the build machine but produces binaries that run on the target 707 :term:`MACHINE`; ":ref:`ref-classes-nativesdk`", which 708 targets the SDK machine instead of :term:`MACHINE`; and "mulitlibs" in 709 the form "``multilib:``\ multilib_name". 710 711 To build a different variant of the recipe with a minimal amount of 712 code, it usually is as simple as adding the following to your recipe:: 713 714 BBCLASSEXTEND =+ "native nativesdk" 715 BBCLASSEXTEND =+ "multilib:multilib_name" 716 717 .. note:: 718 719 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe 720 variants by rewriting variable values and applying overrides such 721 as ``:class-native``. For example, to generate a native version of 722 a recipe, a :term:`DEPENDS` on "foo" is rewritten 723 to a :term:`DEPENDS` on "foo-native". 724 725 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. 726 Parsing once adds some limitations. For example, it is not 727 possible to include a different file depending on the variant, 728 since ``include`` statements are processed when the recipe is 729 parsed. 730 731 :term:`BBDEBUG` 732 See :term:`bitbake:BBDEBUG` in the BitBake manual. 733 734 :term:`BBFILE_COLLECTIONS` 735 Lists the names of configured layers. These names are used to find 736 the other ``BBFILE_*`` variables. Typically, each layer will append 737 its name to this variable in its ``conf/layer.conf`` file. 738 739 :term:`BBFILE_PATTERN` 740 Variable that expands to match files from 741 :term:`BBFILES` in a particular layer. This variable 742 is used in the ``conf/layer.conf`` file and must be suffixed with the 743 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). 744 745 :term:`BBFILE_PRIORITY` 746 Assigns the priority for recipe files in each layer. 747 748 This variable is useful in situations where the same recipe appears 749 in more than one layer. Setting this variable allows you to 750 prioritize a layer against other layers that contain the same recipe 751 --- effectively letting you control the precedence for the multiple 752 layers. The precedence established through this variable stands 753 regardless of a recipe's version (:term:`PV` variable). For 754 example, a layer that has a recipe with a higher :term:`PV` value but for 755 which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still 756 has a lower precedence. 757 758 A larger value for the :term:`BBFILE_PRIORITY` variable results in a 759 higher precedence. For example, the value 6 has a higher precedence 760 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable 761 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable 762 for more information. The default priority, if unspecified for a 763 layer with no dependencies, is the lowest defined priority + 1 (or 1 764 if no priorities are defined). 765 766 .. tip:: 767 768 You can use the command ``bitbake-layers show-layers`` 769 to list all configured layers along with their priorities. 770 771 :term:`BBFILES` 772 A space-separated list of recipe files BitBake uses to build 773 software. 774 775 When specifying recipe files, you can pattern match using Python's 776 `glob <https://docs.python.org/3/library/glob.html>`__ syntax. 777 For details on the syntax, see the documentation by following the 778 previous link. 779 780 :term:`BBFILES_DYNAMIC` 781 Activates content when identified layers are present. You identify 782 the layers by the collections that the layers define. 783 784 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files 785 whose corresponding ``.bb`` file is in a layer that attempts to 786 modify other layers through ``.bbappend`` but does not want to 787 introduce a hard dependency on those other layers. 788 789 Use the following form for :term:`BBFILES_DYNAMIC`: 790 ``collection_name:filename_pattern``. 791 792 The following example identifies two collection names and two 793 filename patterns:: 794 795 BBFILES_DYNAMIC += " \ 796 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ 797 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ 798 " 799 800 This next example shows an error message that occurs because invalid 801 entries are found, which cause parsing to fail: 802 803 .. code-block:: none 804 805 ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not: 806 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend 807 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend 808 809 :term:`BBINCLUDED` 810 See :term:`bitbake:BBINCLUDED` in the BitBake manual. 811 812 :term:`BBINCLUDELOGS` 813 Variable that controls how BitBake displays logs on build failure. 814 815 :term:`BBINCLUDELOGS_LINES` 816 If :term:`BBINCLUDELOGS` is set, specifies the 817 maximum number of lines from the task log file to print when 818 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, 819 the entire log is printed. 820 821 :term:`BBLAYERS` 822 Lists the layers to enable during the build. This variable is defined 823 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. 824 Here is an example:: 825 826 BBLAYERS = " \ 827 /home/scottrif/poky/meta \ 828 /home/scottrif/poky/meta-poky \ 829 /home/scottrif/poky/meta-yocto-bsp \ 830 /home/scottrif/poky/meta-mykernel \ 831 " 832 833 This example enables four layers, one of which is a custom, 834 user-defined layer named ``meta-mykernel``. 835 836 :term:`BBLAYERS_FETCH_DIR` 837 See :term:`bitbake:BBLAYERS_FETCH_DIR` in the BitBake manual. 838 839 :term:`BBMASK` 840 Prevents BitBake from processing recipes and recipe append files. 841 842 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and 843 ``.bbappend`` files. BitBake ignores any recipe or recipe append 844 files that match any of the expressions. It is as if BitBake does not 845 see them at all. Consequently, matching files are not parsed or 846 otherwise used by BitBake. 847 848 The values you provide are passed to Python's regular expression 849 compiler. Consequently, the syntax follows Python's Regular 850 Expression (re) syntax. The expressions are compared against the full 851 paths to the files. For complete syntax information, see Python's 852 documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax. 853 854 The following example uses a complete regular expression to tell 855 BitBake to ignore all recipe and recipe append files in the 856 ``meta-ti/recipes-misc/`` directory:: 857 858 BBMASK = "meta-ti/recipes-misc/" 859 860 If you want to mask out multiple directories or recipes, you can 861 specify multiple regular expression fragments. This next example 862 masks out multiple directories and individual recipes:: 863 864 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" 865 BBMASK += "/meta-oe/recipes-support/" 866 BBMASK += "/meta-foo/.*/openldap" 867 BBMASK += "opencv.*\.bbappend" 868 BBMASK += "lzma" 869 870 .. note:: 871 872 When specifying a directory name, use the trailing slash character 873 to ensure you match just that directory name. 874 875 :term:`BBMULTICONFIG` 876 Specifies each additional separate configuration when you are 877 building targets with multiple configurations. Use this variable in 878 your ``conf/local.conf`` configuration file. Specify a 879 multiconfigname for each configuration file you are using. For 880 example, the following line specifies three configuration files:: 881 882 BBMULTICONFIG = "configA configB configC" 883 884 Each configuration file you use must reside in a ``multiconfig`` 885 subdirectory of a configuration directory within a layer, or 886 within the :term:`Build Directory` (e.g. 887 ``build_directory/conf/multiconfig/configA.conf`` or 888 ``mylayer/conf/multiconfig/configB.conf``). 889 890 For information on how to use :term:`BBMULTICONFIG` in an environment 891 that supports building targets with multiple configurations, see the 892 ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" 893 section in the Yocto Project Development Tasks Manual. 894 895 :term:`BBPATH` 896 See :term:`bitbake:BBPATH` in the BitBake manual. 897 898 :term:`BBSERVER` 899 If defined in the BitBake environment, :term:`BBSERVER` points to the 900 BitBake remote server. 901 902 Use the following format to export the variable to the BitBake 903 environment:: 904 905 export BBSERVER=localhost:$port 906 907 By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`. 908 Consequently, :term:`BBSERVER` is excluded from checksum and dependency 909 data. 910 911 :term:`BBTARGETS` 912 See :term:`bitbake:BBTARGETS` in the BitBake manual. 913 914 :term:`BINCONFIG` 915 When inheriting the :ref:`ref-classes-binconfig-disabled` class, this 916 variable specifies binary configuration scripts to disable in favor of 917 using ``pkg-config`` to query the information. The 918 :ref:`ref-classes-binconfig-disabled` class will modify the specified 919 scripts to return an error so that calls to them can be easily found 920 and replaced. 921 922 To add multiple scripts, separate them by spaces. Here is an example 923 from the ``libpng`` recipe:: 924 925 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" 926 927 :term:`BINCONFIG_GLOB` 928 When inheriting the :ref:`ref-classes-binconfig` class, 929 this variable specifies a wildcard for configuration scripts that 930 need editing. The scripts are edited to correct any paths that have 931 been set up during compilation so that they are correct for use when 932 installed into the sysroot and called by the build processes of other 933 recipes. 934 935 .. note:: 936 937 The :term:`BINCONFIG_GLOB` variable uses 938 `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, 939 which is recognition and expansion of wildcards during pattern 940 matching. Shell globbing is very similar to 941 `fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__ 942 and `glob <https://docs.python.org/3/library/glob.html>`__. 943 944 For more information on how this variable works, see 945 ``meta/classes-recipe/binconfig.bbclass`` in the :term:`Source Directory`. 946 You can also find general 947 information on the class in the 948 ":ref:`ref-classes-binconfig`" section. 949 950 :term:`BITBAKE_UI` 951 See :term:`bitbake:BITBAKE_UI` in the BitBake manual. 952 953 :term:`BP` 954 The base recipe name and version but without any special recipe name 955 suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is 956 comprised of the following:: 957 958 ${BPN}-${PV} 959 960 :term:`BPN` 961 This variable is a version of the :term:`PN` variable with 962 common prefixes and suffixes removed, such as ``nativesdk-``, 963 ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``. 964 The exact lists of prefixes and suffixes removed are specified by the 965 :term:`MLPREFIX` and 966 :term:`SPECIAL_PKGSUFFIX` variables, 967 respectively. 968 969 :term:`BUGTRACKER` 970 Specifies a URL for an upstream bug tracking website for a recipe. 971 The OpenEmbedded build system does not use this variable. Rather, the 972 variable is a useful pointer in case a bug in the software being 973 built needs to be manually reported. 974 975 :term:`BUILD_ARCH` 976 Specifies the architecture of the build host (e.g. ``i686``). The 977 OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the 978 machine name reported by the ``uname`` command. 979 980 :term:`BUILD_AS_ARCH` 981 Specifies the architecture-specific assembler flags for the build 982 host. By default, the value of :term:`BUILD_AS_ARCH` is empty. 983 984 :term:`BUILD_CC_ARCH` 985 Specifies the architecture-specific C compiler flags for the build 986 host. By default, the value of :term:`BUILD_CC_ARCH` is empty. 987 988 :term:`BUILD_CCLD` 989 Specifies the linker command to be used for the build host when the C 990 compiler is being used as the linker. By default, :term:`BUILD_CCLD` 991 points to GCC and passes as arguments the value of 992 :term:`BUILD_CC_ARCH`, assuming 993 :term:`BUILD_CC_ARCH` is set. 994 995 :term:`BUILD_CFLAGS` 996 Specifies the flags to pass to the C compiler when building for the 997 build host. When building in the ``-native`` context, 998 :term:`CFLAGS` is set to the value of this variable by 999 default. 1000 1001 :term:`BUILD_CPPFLAGS` 1002 Specifies the flags to pass to the C preprocessor (i.e. to both the C 1003 and the C++ compilers) when building for the build host. When 1004 building in the ``-native`` context, :term:`CPPFLAGS` 1005 is set to the value of this variable by default. 1006 1007 :term:`BUILD_CXXFLAGS` 1008 Specifies the flags to pass to the C++ compiler when building for the 1009 build host. When building in the ``-native`` context, 1010 :term:`CXXFLAGS` is set to the value of this variable 1011 by default. 1012 1013 :term:`BUILD_FC` 1014 Specifies the Fortran compiler command for the build host. By 1015 default, :term:`BUILD_FC` points to Gfortran and passes as arguments the 1016 value of :term:`BUILD_CC_ARCH`, assuming 1017 :term:`BUILD_CC_ARCH` is set. 1018 1019 :term:`BUILD_LD` 1020 Specifies the linker command for the build host. By default, 1021 :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments 1022 the value of :term:`BUILD_LD_ARCH`, assuming 1023 :term:`BUILD_LD_ARCH` is set. 1024 1025 :term:`BUILD_LD_ARCH` 1026 Specifies architecture-specific linker flags for the build host. By 1027 default, the value of :term:`BUILD_LD_ARCH` is empty. 1028 1029 :term:`BUILD_LDFLAGS` 1030 Specifies the flags to pass to the linker when building for the build 1031 host. When building in the ``-native`` context, 1032 :term:`LDFLAGS` is set to the value of this variable 1033 by default. 1034 1035 :term:`BUILD_OPTIMIZATION` 1036 Specifies the optimization flags passed to the C compiler when 1037 building for the build host or the SDK. The flags are passed through 1038 the :term:`BUILD_CFLAGS` and 1039 :term:`BUILDSDK_CFLAGS` default values. 1040 1041 The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2 1042 -pipe". 1043 1044 :term:`BUILD_OS` 1045 Specifies the operating system in use on the build host (e.g. 1046 "linux"). The OpenEmbedded build system sets the value of 1047 :term:`BUILD_OS` from the OS reported by the ``uname`` command --- the 1048 first word, converted to lower-case characters. 1049 1050 :term:`BUILD_PREFIX` 1051 The toolchain binary prefix used for native recipes. The OpenEmbedded 1052 build system uses the :term:`BUILD_PREFIX` value to set the 1053 :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes. 1054 1055 :term:`BUILD_STRIP` 1056 Specifies the command to be used to strip debugging symbols from 1057 binaries produced for the build host. By default, :term:`BUILD_STRIP` 1058 points to 1059 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. 1060 1061 :term:`BUILD_SYS` 1062 Specifies the system, including the architecture and the operating 1063 system, to use when building for the build host (i.e. when building 1064 :ref:`ref-classes-native` recipes). 1065 1066 The OpenEmbedded build system automatically sets this variable based 1067 on :term:`BUILD_ARCH`, 1068 :term:`BUILD_VENDOR`, and 1069 :term:`BUILD_OS`. You do not need to set the 1070 :term:`BUILD_SYS` variable yourself. 1071 1072 :term:`BUILD_VENDOR` 1073 Specifies the vendor name to use when building for the build host. 1074 The default value is an empty string (""). 1075 1076 :term:`BUILDDIR` 1077 Points to the location of the :term:`Build Directory`. You can define 1078 this directory indirectly through the :ref:`structure-core-script` script 1079 by passing in a :term:`Build Directory` path when you run the script. If 1080 you run the script and do not provide a :term:`Build Directory` path, the 1081 :term:`BUILDDIR` defaults to ``build`` in the current directory. 1082 1083 :term:`BUILDHISTORY_COMMIT` 1084 When inheriting the :ref:`ref-classes-buildhistory` class, this variable 1085 specifies whether or not to commit the build history output in a local 1086 Git repository. If set to "1", this local repository will be maintained 1087 automatically by the :ref:`ref-classes-buildhistory` class and a commit 1088 will be created on every build for changes to each top-level subdirectory 1089 of the build history output (images, packages, and sdk). If you want to 1090 track changes to build history over time, you should set this value to 1091 "1". 1092 1093 By default, the :ref:`ref-classes-buildhistory` class 1094 enables committing the buildhistory output in a local Git repository:: 1095 1096 BUILDHISTORY_COMMIT ?= "1" 1097 1098 :term:`BUILDHISTORY_COMMIT_AUTHOR` 1099 When inheriting the :ref:`ref-classes-buildhistory` 1100 class, this variable specifies the author to use for each Git commit. 1101 In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the 1102 :term:`BUILDHISTORY_COMMIT` variable must 1103 be set to "1". 1104 1105 Git requires that the value you provide for the 1106 :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name 1107 email@host". Providing an email address or host that is not valid 1108 does not produce an error. 1109 1110 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1111 as follows:: 1112 1113 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" 1114 1115 :term:`BUILDHISTORY_DIR` 1116 When inheriting the :ref:`ref-classes-buildhistory` 1117 class, this variable specifies the directory in which build history 1118 information is kept. For more information on how the variable works, 1119 see the :ref:`ref-classes-buildhistory` class. 1120 1121 By default, the :ref:`ref-classes-buildhistory` class sets the directory 1122 as follows:: 1123 1124 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" 1125 1126 :term:`BUILDHISTORY_FEATURES` 1127 When inheriting the :ref:`ref-classes-buildhistory` 1128 class, this variable specifies the build history features to be 1129 enabled. For more information on how build history works, see the 1130 ":ref:`dev-manual/build-quality:maintaining build output quality`" 1131 section in the Yocto Project Development Tasks Manual. 1132 1133 You can specify these features in the form of a space-separated list: 1134 1135 - *image:* Analysis of the contents of images, which includes the 1136 list of installed packages among other things. 1137 1138 - *package:* Analysis of the contents of individual packages. 1139 1140 - *sdk:* Analysis of the contents of the software development kit 1141 (SDK). 1142 1143 - *task:* Save output file signatures for 1144 :ref:`shared state <overview-manual/concepts:shared state cache>` 1145 (sstate) tasks. 1146 This saves one file per task and lists the SHA-256 checksums for 1147 each file staged (i.e. the output of the task). 1148 1149 By default, the :ref:`ref-classes-buildhistory` class enables the 1150 following features:: 1151 1152 BUILDHISTORY_FEATURES ?= "image package sdk" 1153 1154 :term:`BUILDHISTORY_IMAGE_FILES` 1155 When inheriting the :ref:`ref-classes-buildhistory` 1156 class, this variable specifies a list of paths to files copied from 1157 the image contents into the build history directory under an 1158 "image-files" directory in the directory for the image, so that you 1159 can track the contents of each file. The default is to copy 1160 ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for 1161 changes in user and group entries. You can modify the list to include 1162 any file. Specifying an invalid path does not produce an error. 1163 Consequently, you can include files that might not always be present. 1164 1165 By default, the :ref:`ref-classes-buildhistory` class provides paths to 1166 the following files:: 1167 1168 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" 1169 1170 :term:`BUILDHISTORY_PATH_PREFIX_STRIP` 1171 When inheriting the :ref:`ref-classes-buildhistory` 1172 class, this variable specifies a common path prefix that should be 1173 stripped off the beginning of paths in the task signature list when the 1174 ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be 1175 useful when build history is populated from multiple sources that may not 1176 all use the same top level directory. 1177 1178 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1179 as follows:: 1180 1181 BUILDHISTORY_PATH_PREFIX_STRIP ?= "" 1182 1183 In this case, no prefixes will be stripped. 1184 1185 :term:`BUILDHISTORY_PUSH_REPO` 1186 When inheriting the :ref:`ref-classes-buildhistory` class, this variable 1187 optionally specifies a remote repository to which build history pushes 1188 Git changes. In order for :term:`BUILDHISTORY_PUSH_REPO` to work, 1189 :term:`BUILDHISTORY_COMMIT` must be set to "1". 1190 1191 The repository should correspond to a remote address that specifies a 1192 repository as understood by Git, or alternatively to a remote name 1193 that you have set up manually using ``git remote`` within the local 1194 repository. 1195 1196 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1197 as follows:: 1198 1199 BUILDHISTORY_PUSH_REPO ?= "" 1200 1201 :term:`BUILDNAME` 1202 See :term:`bitbake:BUILDNAME` in the BitBake manual. 1203 1204 :term:`BUILDSDK_CFLAGS` 1205 Specifies the flags to pass to the C compiler when building for the 1206 SDK. When building in the ``nativesdk-`` context, 1207 :term:`CFLAGS` is set to the value of this variable by 1208 default. 1209 1210 :term:`BUILDSDK_CPPFLAGS` 1211 Specifies the flags to pass to the C pre-processor (i.e. to both the 1212 C and the C++ compilers) when building for the SDK. When building in 1213 the ``nativesdk-`` context, :term:`CPPFLAGS` is set 1214 to the value of this variable by default. 1215 1216 :term:`BUILDSDK_CXXFLAGS` 1217 Specifies the flags to pass to the C++ compiler when building for the 1218 SDK. When building in the ``nativesdk-`` context, 1219 :term:`CXXFLAGS` is set to the value of this variable 1220 by default. 1221 1222 :term:`BUILDSDK_LDFLAGS` 1223 Specifies the flags to pass to the linker when building for the SDK. 1224 When building in the ``nativesdk-`` context, 1225 :term:`LDFLAGS` is set to the value of this variable 1226 by default. 1227 1228 :term:`BUILDSTATS_BASE` 1229 Points to the location of the directory that holds build statistics 1230 when you use and enable the :ref:`ref-classes-buildstats` class. The 1231 :term:`BUILDSTATS_BASE` directory defaults to 1232 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. 1233 1234 :term:`BUSYBOX_SPLIT_SUID` 1235 For the BusyBox recipe, specifies whether to split the output 1236 executable file into two parts: one for features that require 1237 ``setuid root``, and one for the remaining features (i.e. those that 1238 do not require ``setuid root``). 1239 1240 The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in 1241 splitting the output executable file. Set the variable to "0" to get 1242 a single output executable file. 1243 1244 :term:`BZRDIR` 1245 See :term:`bitbake:BZRDIR` in the BitBake manual. 1246 1247 :term:`CACHE` 1248 Specifies the directory BitBake uses to store a cache of the 1249 :term:`Metadata` so it does not need to be parsed every time 1250 BitBake is started. 1251 1252 :term:`CC` 1253 The minimal command and arguments used to run the C compiler. 1254 1255 :term:`CFLAGS` 1256 Specifies the flags to pass to the C compiler. This variable is 1257 exported to an environment variable and thus made visible to the 1258 software being built during the compilation step. 1259 1260 Default initialization for :term:`CFLAGS` varies depending on what is 1261 being built: 1262 1263 - :term:`TARGET_CFLAGS` when building for the 1264 target 1265 1266 - :term:`BUILD_CFLAGS` when building for the 1267 build host (i.e. ``-native``) 1268 1269 - :term:`BUILDSDK_CFLAGS` when building for 1270 an SDK (i.e. ``nativesdk-``) 1271 1272 :term:`CLASSOVERRIDE` 1273 An internal variable specifying the special class override that 1274 should currently apply (e.g. "class-target", "class-native", and so 1275 forth). The classes that use this variable (e.g. 1276 :ref:`ref-classes-native`, :ref:`ref-classes-nativesdk`, and so forth) 1277 set the variable to appropriate values. 1278 1279 .. note:: 1280 1281 :term:`CLASSOVERRIDE` gets its default "class-target" value from the 1282 ``bitbake.conf`` file. 1283 1284 As an example, the following override allows you to install extra 1285 files, but only when building for the target:: 1286 1287 do_install:append:class-target() { 1288 install my-extra-file ${D}${sysconfdir} 1289 } 1290 1291 Here is an example where ``FOO`` is set to 1292 "native" when building for the build host, and to "other" when not 1293 building for the build host:: 1294 1295 FOO:class-native = "native" 1296 FOO = "other" 1297 1298 The underlying mechanism behind :term:`CLASSOVERRIDE` is simply 1299 that it is included in the default value of 1300 :term:`OVERRIDES`. 1301 1302 :term:`CLEANBROKEN` 1303 If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the 1304 ``make clean`` command does not work for the software being built. 1305 Consequently, the OpenEmbedded build system will not try to run 1306 ``make clean`` during the :ref:`ref-tasks-configure` 1307 task, which is the default behavior. 1308 1309 :term:`COMBINED_FEATURES` 1310 Provides a list of hardware features that are enabled in both 1311 :term:`MACHINE_FEATURES` and 1312 :term:`DISTRO_FEATURES`. This select list of 1313 features contains features that make sense to be controlled both at 1314 the machine and distribution configuration level. For example, the 1315 "bluetooth" feature requires hardware support but should also be 1316 optional at the distribution level, in case the hardware supports 1317 Bluetooth but you do not ever intend to use it. 1318 1319 :term:`COMMERCIAL_AUDIO_PLUGINS` 1320 This variable is specific to the :yocto_git:`GStreamer recipes 1321 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. 1322 It allows to build the GStreamer `"ugly" 1323 <https://github.com/GStreamer/gst-plugins-ugly>`__ and 1324 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins. 1325 1326 See the :ref:`dev-manual/licenses:other variables related to commercial licenses` 1327 section for usage details. 1328 1329 :term:`COMMERCIAL_VIDEO_PLUGINS` 1330 This variable is specific to the :yocto_git:`GStreamer recipes 1331 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. 1332 It allows to build the GStreamer `"ugly" 1333 <https://github.com/GStreamer/gst-plugins-ugly>`__ and 1334 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins. 1335 1336 See the :ref:`dev-manual/licenses:other variables related to commercial licenses` 1337 section for usage details. 1338 1339 :term:`COMMON_LICENSE_DIR` 1340 Points to ``meta/files/common-licenses`` in the 1341 :term:`Source Directory`, which is where generic license 1342 files reside. 1343 1344 :term:`COMPATIBLE_HOST` 1345 A regular expression that resolves to one or more hosts (when the 1346 recipe is native) or one or more targets (when the recipe is 1347 non-native) with which a recipe is compatible. The regular expression 1348 is matched against :term:`HOST_SYS`. You can use the 1349 variable to stop recipes from being built for classes of systems with 1350 which the recipes are not compatible. Stopping these builds is 1351 particularly useful with kernels. The variable also helps to increase 1352 parsing speed since the build system skips parsing recipes not 1353 compatible with the current system. 1354 1355 :term:`COMPATIBLE_MACHINE` 1356 A regular expression that resolves to one or more target machines 1357 with which a recipe is compatible. The regular expression is matched 1358 against :term:`MACHINEOVERRIDES`. You can use 1359 the variable to stop recipes from being built for machines with which 1360 the recipes are not compatible. Stopping these builds is particularly 1361 useful with kernels. The variable also helps to increase parsing 1362 speed since the build system skips parsing recipes not compatible 1363 with the current machine. 1364 1365 :term:`COMPLEMENTARY_GLOB` 1366 Defines wildcards to match when installing a list of complementary 1367 packages for all the packages explicitly (or implicitly) installed in 1368 an image. 1369 1370 The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching 1371 (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), 1372 which is similar to the Unix style pathname pattern expansion 1373 (`glob <https://docs.python.org/3/library/glob.html>`__). 1374 1375 The resulting list of complementary packages is associated with an 1376 item that can be added to 1377 :term:`IMAGE_FEATURES`. An example usage of 1378 this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES` 1379 will install -dev packages (containing headers and other development 1380 files) for every package in the image. 1381 1382 To add a new feature item pointing to a wildcard, use a variable flag 1383 to specify the feature item name and use the value to specify the 1384 wildcard. Here is an example:: 1385 1386 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' 1387 1388 .. note:: 1389 1390 When installing complementary packages, recommends relationships 1391 (set via :term:`RRECOMMENDS`) are always ignored. 1392 1393 :term:`COMPONENTS_DIR` 1394 Stores sysroot components for each recipe. The OpenEmbedded build 1395 system uses :term:`COMPONENTS_DIR` when constructing recipe-specific 1396 sysroots for other recipes. 1397 1398 The default is 1399 "``${``\ :term:`STAGING_DIR`\ ``}-components``." 1400 (i.e. 1401 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). 1402 1403 :term:`CONF_VERSION` 1404 Tracks the version of the local configuration file (i.e. 1405 ``local.conf``). The value for :term:`CONF_VERSION` increments each time 1406 ``build/conf/`` compatibility changes. 1407 1408 :term:`CONFFILES` 1409 Identifies editable or configurable files that are part of a package. 1410 If the Package Management System (PMS) is being used to update 1411 packages on the target system, it is possible that configuration 1412 files you have changed after the original installation and that you 1413 now want to remain unchanged are overwritten. In other words, 1414 editable files might exist in the package that you do not want reset 1415 as part of the package update process. You can use the :term:`CONFFILES` 1416 variable to list the files in the package that you wish to prevent 1417 the PMS from overwriting during this update process. 1418 1419 To use the :term:`CONFFILES` variable, provide a package name override 1420 that identifies the resulting package. Then, provide a 1421 space-separated list of files. Here is an example:: 1422 1423 CONFFILES:${PN} += "${sysconfdir}/file1 \ 1424 ${sysconfdir}/file2 ${sysconfdir}/file3" 1425 1426 There is a relationship between the :term:`CONFFILES` and :term:`FILES` 1427 variables. The files listed within :term:`CONFFILES` must be a subset of 1428 the files listed within :term:`FILES`. Because the configuration files 1429 you provide with :term:`CONFFILES` are simply being identified so that 1430 the PMS will not overwrite them, it makes sense that the files must 1431 already be included as part of the package through the :term:`FILES` 1432 variable. 1433 1434 .. note:: 1435 1436 When specifying paths as part of the :term:`CONFFILES` variable, it is 1437 good practice to use appropriate path variables. 1438 For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` 1439 rather than ``/usr/bin``. You can find a list of these variables at 1440 the top of the ``meta/conf/bitbake.conf`` file in the 1441 :term:`Source Directory`. 1442 1443 :term:`CONFIG_INITRAMFS_SOURCE` 1444 Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The 1445 OpenEmbedded build system receives and uses this kernel Kconfig 1446 variable as an environment variable. By default, the variable is set 1447 to null (""). 1448 1449 The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive 1450 with a ``.cpio`` suffix or a space-separated list of directories and 1451 files for building the :term:`Initramfs` image. A cpio archive should contain 1452 a filesystem archive to be used as an :term:`Initramfs` image. Directories 1453 should contain a filesystem layout to be included in the :term:`Initramfs` 1454 image. Files should contain entries according to the format described 1455 by the ``usr/gen_init_cpio`` program in the kernel tree. 1456 1457 If you specify multiple directories and files, the :term:`Initramfs` image 1458 will be the aggregate of all of them. 1459 1460 For information on creating an :term:`Initramfs`, see the 1461 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 1462 in the Yocto Project Development Tasks Manual. 1463 1464 :term:`CONFIG_SITE` 1465 A list of files that contains ``autoconf`` test results relevant to 1466 the current build. This variable is used by the Autotools utilities 1467 when running ``configure``. 1468 1469 :term:`CONFIGURE_FLAGS` 1470 The minimal arguments for GNU configure. 1471 1472 :term:`CONFLICT_DISTRO_FEATURES` 1473 When inheriting the :ref:`ref-classes-features_check` 1474 class, this variable identifies distribution features that would be 1475 in conflict should the recipe be built. In other words, if the 1476 :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also 1477 appears in :term:`DISTRO_FEATURES` within the current configuration, then 1478 the recipe will be skipped, and if the build system attempts to build 1479 the recipe then an error will be triggered. 1480 1481 :term:`CONVERSION_CMD` 1482 This variable is used for storing image conversion commands. 1483 Image conversion can convert an image into different objects like: 1484 1485 - Compressed version of the image 1486 1487 - Checksums for the image 1488 1489 An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types` 1490 class is:: 1491 1492 CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}" 1493 1494 :term:`COPY_LIC_DIRS` 1495 If set to "1" along with the 1496 :term:`COPY_LIC_MANIFEST` variable, the 1497 OpenEmbedded build system copies into the image the license files, 1498 which are located in ``/usr/share/common-licenses``, for each 1499 package. The license files are placed in directories within the image 1500 itself during build time. 1501 1502 .. note:: 1503 1504 The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for 1505 newly installed packages to an image, which might be most suitable for 1506 read-only filesystems that cannot be upgraded. See the 1507 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1508 You can also reference the ":ref:`dev-manual/licenses:providing license text`" 1509 section in the Yocto Project Development Tasks Manual for 1510 information on providing license text. 1511 1512 :term:`COPY_LIC_MANIFEST` 1513 If set to "1", the OpenEmbedded build system copies the license 1514 manifest for the image to 1515 ``/usr/share/common-licenses/license.manifest`` within the image 1516 itself during build time. 1517 1518 .. note:: 1519 1520 The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for 1521 newly installed packages to an image, which might be most suitable for 1522 read-only filesystems that cannot be upgraded. See the 1523 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1524 You can also reference the ":ref:`dev-manual/licenses:providing license text`" 1525 section in the Yocto Project Development Tasks Manual for 1526 information on providing license text. 1527 1528 :term:`COPYLEFT_LICENSE_EXCLUDE` 1529 A space-separated list of licenses to exclude from the source archived by 1530 the :ref:`ref-classes-archiver` class. In other words, if a license in a 1531 recipe's :term:`LICENSE` value is in the value of 1532 :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the 1533 class. 1534 1535 .. note:: 1536 1537 The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the 1538 :term:`COPYLEFT_LICENSE_INCLUDE` variable. 1539 1540 The default value, which is "CLOSED Proprietary", for 1541 :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the 1542 :ref:`ref-classes-copyleft_filter` class, which 1543 is inherited by the :ref:`ref-classes-archiver` class. 1544 1545 :term:`COPYLEFT_LICENSE_INCLUDE` 1546 A space-separated list of licenses to include in the source archived 1547 by the :ref:`ref-classes-archiver` class. In other 1548 words, if a license in a recipe's :term:`LICENSE` 1549 value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its 1550 source is archived by the class. 1551 1552 The default value is set by the :ref:`ref-classes-copyleft_filter` class, 1553 which is inherited by the :ref:`ref-classes-archiver` class. The default 1554 value includes "GPL*", "LGPL*", and "AGPL*". 1555 1556 :term:`COPYLEFT_PN_EXCLUDE` 1557 A list of recipes to exclude in the source archived by the 1558 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_EXCLUDE` 1559 variable overrides the license inclusion and exclusion caused through the 1560 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` 1561 variables, respectively. 1562 1563 The default value, which is "" indicating to not explicitly exclude 1564 any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the 1565 :ref:`ref-classes-copyleft_filter` class, which is inherited by the 1566 :ref:`ref-classes-archiver` class. 1567 1568 :term:`COPYLEFT_PN_INCLUDE` 1569 A list of recipes to include in the source archived by the 1570 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_INCLUDE` 1571 variable overrides the license inclusion and exclusion caused through the 1572 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` 1573 variables, respectively. 1574 1575 The default value, which is "" indicating to not explicitly include 1576 any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the 1577 :ref:`ref-classes-copyleft_filter` class, which is inherited by the 1578 :ref:`ref-classes-archiver` class. 1579 1580 :term:`COPYLEFT_RECIPE_TYPES` 1581 A space-separated list of recipe types to include in the source 1582 archived by the :ref:`archiver <ref-classes-archiver>` class. 1583 Recipe types are ``target``, :ref:`ref-classes-native`, 1584 :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`, 1585 :ref:`ref-classes-crosssdk`, and :ref:`ref-classes-cross-canadian`. 1586 1587 The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES` 1588 is set by the :ref:`ref-classes-copyleft_filter` class, which is 1589 inherited by the :ref:`ref-classes-archiver` class. 1590 1591 :term:`CORE_IMAGE_EXTRA_INSTALL` 1592 Specifies the list of packages to be added to the image. You should 1593 only set this variable in the ``local.conf`` configuration file found 1594 in the :term:`Build Directory`. 1595 1596 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer 1597 supported. 1598 1599 :term:`COREBASE` 1600 Specifies the parent directory of the OpenEmbedded-Core Metadata 1601 layer (i.e. ``meta``). 1602 1603 It is an important distinction that :term:`COREBASE` points to the parent 1604 of this layer and not the layer itself. Consider an example where you 1605 have cloned the Poky Git repository and retained the ``poky`` name 1606 for your local copy of the repository. In this case, :term:`COREBASE` 1607 points to the ``poky`` folder because it is the parent directory of 1608 the ``poky/meta`` layer. 1609 1610 :term:`COREBASE_FILES` 1611 Lists files from the :term:`COREBASE` directory that 1612 should be copied other than the layers listed in the 1613 ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows 1614 to copy metadata from the OpenEmbedded build system 1615 into the extensible SDK. 1616 1617 Explicitly listing files in :term:`COREBASE` is needed because it 1618 typically contains build directories and other files that should not 1619 normally be copied into the extensible SDK. Consequently, the value 1620 of :term:`COREBASE_FILES` is used in order to only copy the files that 1621 are actually needed. 1622 1623 :term:`CPP` 1624 The minimal command and arguments used to run the C preprocessor. 1625 1626 :term:`CPPFLAGS` 1627 Specifies the flags to pass to the C pre-processor (i.e. to both the 1628 C and the C++ compilers). This variable is exported to an environment 1629 variable and thus made visible to the software being built during the 1630 compilation step. 1631 1632 Default initialization for :term:`CPPFLAGS` varies depending on what is 1633 being built: 1634 1635 - :term:`TARGET_CPPFLAGS` when building for 1636 the target 1637 1638 - :term:`BUILD_CPPFLAGS` when building for the 1639 build host (i.e. ``-native``) 1640 1641 - :term:`BUILDSDK_CPPFLAGS` when building 1642 for an SDK (i.e. ``nativesdk-``) 1643 1644 :term:`CROSS_COMPILE` 1645 The toolchain binary prefix for the target tools. The 1646 :term:`CROSS_COMPILE` variable is the same as the 1647 :term:`TARGET_PREFIX` variable. 1648 1649 .. note:: 1650 1651 The OpenEmbedded build system sets the :term:`CROSS_COMPILE` 1652 variable only in certain contexts (e.g. when building for kernel 1653 and kernel module recipes). 1654 1655 :term:`CVE_CHECK_IGNORE` 1656 This variable is deprecated and should be replaced by :term:`CVE_STATUS`. 1657 1658 :term:`CVE_CHECK_SHOW_WARNINGS` 1659 Specifies whether or not the :ref:`ref-classes-cve-check` 1660 class should generate warning messages on the console when unpatched 1661 CVEs are found. The default is "1", but you may wish to set it to "0" if 1662 you are already examining/processing the logs after the build has 1663 completed and thus do not need the warning messages. 1664 1665 :term:`CVE_CHECK_SKIP_RECIPE` 1666 The list of package names (:term:`PN`) for which 1667 CVEs (Common Vulnerabilities and Exposures) are ignored. 1668 1669 :term:`CVE_DB_UPDATE_INTERVAL` 1670 Specifies the CVE database update interval in seconds, as used by 1671 ``cve-update-db-native``. The default value is "86400" i.e. once a day 1672 (24*60*60). If the value is set to "0" then the update will be forced 1673 every time. Alternatively, a negative value e.g. "-1" will disable 1674 updates entirely. 1675 1676 :term:`CVE_PRODUCT` 1677 In a recipe, defines the name used to match the recipe name 1678 against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__. 1679 1680 The default is ${:term:`BPN`} (except for recipes that inherit the 1681 :ref:`ref-classes-pypi` class where it is set based upon 1682 :term:`PYPI_PACKAGE`). If it does not match the name in the NIST CVE 1683 database or matches with multiple entries in the database, the default 1684 value needs to be changed. 1685 1686 Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`:: 1687 1688 CVE_PRODUCT = "oracle_berkeley_db berkeley_db" 1689 1690 Sometimes the product name is not specific enough, for example 1691 "tar" has been matching CVEs for the GNU ``tar`` package and also 1692 the ``node-tar`` node.js extension. To avoid this problem, use the 1693 vendor name as a prefix. The syntax for this is:: 1694 1695 CVE_PRODUCT = "vendor:package" 1696 1697 :term:`CVE_STATUS` 1698 The CVE ID which is patched or should be ignored. Here is 1699 an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`:: 1700 1701 CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows" 1702 1703 It has the format "reason: description" and the description is optional. 1704 The Reason is mapped to the final CVE state by mapping via 1705 :term:`CVE_CHECK_STATUSMAP` 1706 1707 :term:`CVE_STATUS_GROUPS` 1708 If there are many CVEs with the same status and reason, they can by simplified by using this 1709 variable instead of many similar lines with :term:`CVE_STATUS`:: 1710 1711 CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED" 1712 1713 CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002" 1714 CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows" 1715 CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004" 1716 CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally" 1717 1718 :term:`CVE_CHECK_STATUSMAP` 1719 Mapping variable for all possible reasons of :term:`CVE_STATUS`: 1720 ``Patched``, ``Unpatched`` and ``Ignored``. 1721 See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details:: 1722 1723 CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored" 1724 1725 :term:`CVE_VERSION` 1726 In a recipe, defines the version used to match the recipe version 1727 against the version in the `NIST CVE database <https://nvd.nist.gov/>`__ 1728 when usign :ref:`ref-classes-cve-check`. 1729 1730 The default is ${:term:`PV`} but if recipes use custom version numbers 1731 which do not map to upstream software component release versions and the versions 1732 used in the CVE database, then this variable can be used to set the 1733 version number for :ref:`ref-classes-cve-check`. Example:: 1734 1735 CVE_VERSION = "2.39" 1736 1737 :term:`CVSDIR` 1738 The directory in which files checked out under the CVS system are 1739 stored. 1740 1741 :term:`CXX` 1742 The minimal command and arguments used to run the C++ compiler. 1743 1744 :term:`CXXFLAGS` 1745 Specifies the flags to pass to the C++ compiler. This variable is 1746 exported to an environment variable and thus made visible to the 1747 software being built during the compilation step. 1748 1749 Default initialization for :term:`CXXFLAGS` varies depending on what is 1750 being built: 1751 1752 - :term:`TARGET_CXXFLAGS` when building for 1753 the target 1754 1755 - :term:`BUILD_CXXFLAGS` when building for the 1756 build host (i.e. ``-native``) 1757 1758 - :term:`BUILDSDK_CXXFLAGS` when building 1759 for an SDK (i.e. ``nativesdk-``) 1760 1761 :term:`D` 1762 The destination directory. The location in the :term:`Build Directory` 1763 where components are installed by the 1764 :ref:`ref-tasks-install` task. This location defaults 1765 to:: 1766 1767 ${WORKDIR}/image 1768 1769 .. note:: 1770 1771 Tasks that read from or write to this directory should run under 1772 :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`. 1773 1774 :term:`DATE` 1775 The date the build was started. Dates appear using the year, month, 1776 and day (YMD) format (e.g. "20150209" for February 9th, 2015). 1777 1778 :term:`DATETIME` 1779 The date and time on which the current build started. The format is 1780 suitable for timestamps. 1781 1782 :term:`DEBIAN_NOAUTONAME` 1783 When the :ref:`ref-classes-debian` class is inherited, 1784 which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a 1785 particular package should not be renamed according to Debian library 1786 package naming. You must use the package name as an override when you 1787 set this variable. Here is an example from the ``fontconfig`` recipe:: 1788 1789 DEBIAN_NOAUTONAME:fontconfig-utils = "1" 1790 1791 :term:`DEBIANNAME` 1792 When the :ref:`ref-classes-debian` class is inherited, 1793 which is the default behavior, :term:`DEBIANNAME` allows you to override 1794 the library name for an individual package. Overriding the library 1795 name in these cases is rare. You must use the package name as an 1796 override when you set this variable. Here is an example from the 1797 ``dbus`` recipe:: 1798 1799 DEBIANNAME:${PN} = "dbus-1" 1800 1801 :term:`DEBUG_BUILD` 1802 Specifies to build packages with debugging information. This 1803 influences the value of the :term:`SELECTED_OPTIMIZATION` variable. 1804 1805 :term:`DEBUG_OPTIMIZATION` 1806 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when 1807 compiling a system for debugging. This variable defaults to "-O 1808 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". 1809 1810 :term:`DEBUG_PREFIX_MAP` 1811 Allows to set C compiler options, such as ``-fdebug-prefix-map``, 1812 ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to 1813 replace build-time paths by install-time ones in the debugging sections 1814 of binaries. This makes compiler output files location independent, 1815 at the cost of having to pass an extra command to tell the debugger 1816 where source files are. 1817 1818 This is used by the Yocto Project to guarantee 1819 :doc:`/test-manual/reproducible-builds` even when the source code of 1820 a package uses the ``__FILE__`` or ``assert()`` macros. See the 1821 `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__ 1822 website for details. 1823 1824 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 1825 not intended to be user-configurable. 1826 1827 :term:`DEFAULT_PREFERENCE` 1828 Specifies a weak bias for recipe selection priority. 1829 1830 The most common usage of this is variable is to set it to "-1" within 1831 a recipe for a development version of a piece of software. Using the 1832 variable in this way causes the stable version of the recipe to build 1833 by default in the absence of :term:`PREFERRED_VERSION` being used to 1834 build the development version. 1835 1836 .. note:: 1837 1838 The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden 1839 by :term:`BBFILE_PRIORITY` if that variable is different between two 1840 layers that contain different versions of the same recipe. 1841 1842 :term:`DEFAULTTUNE` 1843 The default CPU and Application Binary Interface (ABI) tunings (i.e. 1844 the "tune") used by the OpenEmbedded build system. The 1845 :term:`DEFAULTTUNE` helps define 1846 :term:`TUNE_FEATURES`. 1847 1848 The default tune is either implicitly or explicitly set by the 1849 machine (:term:`MACHINE`). However, you can override 1850 the setting using available tunes as defined with 1851 :term:`AVAILTUNES`. 1852 1853 :term:`DEPENDS` 1854 Lists a recipe's build-time dependencies. These are dependencies on 1855 other recipes whose contents (e.g. headers and shared libraries) are 1856 needed by the recipe at build time. 1857 1858 As an example, consider a recipe ``foo`` that contains the following 1859 assignment:: 1860 1861 DEPENDS = "bar" 1862 1863 The practical effect of the previous assignment is that all files 1864 installed by bar will be available in the appropriate staging sysroot, 1865 given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time 1866 the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is 1867 implemented by having :ref:`ref-tasks-configure` depend on the 1868 :ref:`ref-tasks-populate_sysroot` task of each recipe listed in 1869 :term:`DEPENDS`, through a 1870 ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` 1871 declaration in the :ref:`ref-classes-base` class. 1872 1873 .. note:: 1874 1875 It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST` 1876 explicitly. The standard classes and build-related variables are 1877 configured to automatically use the appropriate staging sysroots. 1878 1879 As another example, :term:`DEPENDS` can also be used to add utilities 1880 that run on the build machine during the build. For example, a recipe 1881 that makes use of a code generator built by the recipe ``codegen`` 1882 might have the following:: 1883 1884 DEPENDS = "codegen-native" 1885 1886 For more 1887 information, see the :ref:`ref-classes-native` class and 1888 the :term:`EXTRANATIVEPATH` variable. 1889 1890 .. note:: 1891 1892 - :term:`DEPENDS` is a list of recipe names. Or, to be more precise, 1893 it is a list of :term:`PROVIDES` names, which 1894 usually match recipe names. Putting a package name such as 1895 "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo" 1896 instead, as this will put files from all the packages that make 1897 up ``foo``, which includes those from ``foo-dev``, into the 1898 sysroot. 1899 1900 - One recipe having another recipe in :term:`DEPENDS` does not by 1901 itself add any runtime dependencies between the packages 1902 produced by the two recipes. However, as explained in the 1903 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 1904 section in the Yocto Project Overview and Concepts Manual, 1905 runtime dependencies will often be added automatically, meaning 1906 :term:`DEPENDS` alone is sufficient for most recipes. 1907 1908 - Counterintuitively, :term:`DEPENDS` is often necessary even for 1909 recipes that install precompiled components. For example, if 1910 ``libfoo`` is a precompiled library that links against 1911 ``libbar``, then linking against ``libfoo`` requires both 1912 ``libfoo`` and ``libbar`` to be available in the sysroot. 1913 Without a :term:`DEPENDS` from the recipe that installs ``libfoo`` 1914 to the recipe that installs ``libbar``, other recipes might 1915 fail to link against ``libfoo``. 1916 1917 For information on runtime dependencies, see the :term:`RDEPENDS` 1918 variable. You can also see the 1919 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and 1920 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" 1921 sections in the BitBake User Manual for additional information on tasks 1922 and dependencies. 1923 1924 :term:`DEPLOY_DIR` 1925 Points to the general area that the OpenEmbedded build system uses to 1926 place images, packages, SDKs, and other output files that are ready 1927 to be used outside of the build system. By default, this directory 1928 resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``. 1929 1930 For more information on the structure of the Build Directory, see 1931 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 1932 For more detail on the contents of the ``deploy`` directory, see the 1933 ":ref:`overview-manual/concepts:images`", 1934 ":ref:`overview-manual/concepts:package feeds`", and 1935 ":ref:`overview-manual/concepts:application development sdk`" sections all in the 1936 Yocto Project Overview and Concepts Manual. 1937 1938 :term:`DEPLOY_DIR_DEB` 1939 Points to the area that the OpenEmbedded build system uses to place 1940 Debian packages that are ready to be used outside of the build 1941 system. This variable applies only when :term:`PACKAGE_CLASSES` contains 1942 ":ref:`ref-classes-package_deb`". 1943 1944 The BitBake configuration file initially defines the 1945 :term:`DEPLOY_DIR_DEB` variable as a sub-folder of 1946 :term:`DEPLOY_DIR`:: 1947 1948 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" 1949 1950 The :ref:`ref-classes-package_deb` class uses the 1951 :term:`DEPLOY_DIR_DEB` variable to make sure the 1952 :ref:`ref-tasks-package_write_deb` task 1953 writes Debian packages into the appropriate folder. For more 1954 information on how packaging works, see the 1955 ":ref:`overview-manual/concepts:package feeds`" section 1956 in the Yocto Project Overview and Concepts Manual. 1957 1958 :term:`DEPLOY_DIR_IMAGE` 1959 Points to the area that the OpenEmbedded build system uses to place 1960 images and other associated output files that are ready to be 1961 deployed onto the target machine. The directory is machine-specific 1962 as it contains the ``${MACHINE}`` name. By default, this directory 1963 resides within the :term:`Build Directory` as 1964 ``${DEPLOY_DIR}/images/${MACHINE}/``. 1965 1966 It must not be used directly in recipes when deploying files. Instead, 1967 it's only useful when a recipe needs to "read" a file already deployed 1968 by a dependency. So, it should be filled with the contents of 1969 :term:`DEPLOYDIR` by the :ref:`ref-classes-deploy` class or with the 1970 contents of :term:`IMGDEPLOYDIR` by the :ref:`ref-classes-image` class. 1971 1972 For more information on the structure of the :term:`Build Directory`, see 1973 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 1974 For more detail on the contents of the ``deploy`` directory, see the 1975 ":ref:`overview-manual/concepts:images`" and 1976 ":ref:`overview-manual/concepts:application development sdk`" sections both in 1977 the Yocto Project Overview and Concepts Manual. 1978 1979 :term:`DEPLOY_DIR_IPK` 1980 Points to the area that the OpenEmbedded build system uses to place 1981 IPK packages that are ready to be used outside of the build system. 1982 This variable applies only when :term:`PACKAGE_CLASSES` contains 1983 ":ref:`ref-classes-package_ipk`". 1984 1985 The BitBake configuration file initially defines this variable as a 1986 sub-folder of :term:`DEPLOY_DIR`:: 1987 1988 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" 1989 1990 The :ref:`ref-classes-package_ipk` class uses the :term:`DEPLOY_DIR_IPK` 1991 variable to make sure the :ref:`ref-tasks-package_write_ipk` task 1992 writes IPK packages into the appropriate folder. For more information 1993 on how packaging works, see the 1994 ":ref:`overview-manual/concepts:package feeds`" section 1995 in the Yocto Project Overview and Concepts Manual. 1996 1997 :term:`DEPLOY_DIR_RPM` 1998 Points to the area that the OpenEmbedded build system uses to place 1999 RPM packages that are ready to be used outside of the build system. 2000 This variable applies only when :term:`PACKAGE_CLASSES` contains 2001 ":ref:`ref-classes-package_rpm`". 2002 2003 The BitBake configuration file initially defines this variable as a 2004 sub-folder of :term:`DEPLOY_DIR`:: 2005 2006 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" 2007 2008 The :ref:`ref-classes-package_rpm` class uses the 2009 :term:`DEPLOY_DIR_RPM` variable to make sure the 2010 :ref:`ref-tasks-package_write_rpm` task 2011 writes RPM packages into the appropriate folder. For more information 2012 on how packaging works, see the 2013 ":ref:`overview-manual/concepts:package feeds`" section 2014 in the Yocto Project Overview and Concepts Manual. 2015 2016 :term:`DEPLOYDIR` 2017 When inheriting the :ref:`ref-classes-deploy` class, the 2018 :term:`DEPLOYDIR` points to a temporary work area for deployed files that 2019 is set in the :ref:`ref-classes-deploy` class as follows:: 2020 2021 DEPLOYDIR = "${WORKDIR}/deploy-${PN}" 2022 2023 Recipes inheriting the :ref:`ref-classes-deploy` class should copy files to be 2024 deployed into :term:`DEPLOYDIR`, and the class will take care of copying 2025 them into :term:`DEPLOY_DIR_IMAGE` 2026 afterwards. 2027 2028 :term:`DESCRIPTION` 2029 The package description used by package managers. If not set, 2030 :term:`DESCRIPTION` takes the value of the :term:`SUMMARY` 2031 variable. 2032 2033 :term:`DEV_PKG_DEPENDENCY` 2034 Provides an easy way for recipes to disable or adjust the runtime recommendation 2035 (:term:`RRECOMMENDS`) of the ``${PN}-dev`` package on the main 2036 (``${PN}``) package. 2037 2038 :term:`DISABLE_STATIC` 2039 Used in order to disable static linking by default (in order to save 2040 space, since static libraries are often unused in embedded systems.) 2041 The default value is " --disable-static", however it can be set to "" 2042 in order to enable static linking if desired. Certain recipes do this 2043 individually, and also there is a 2044 ``meta/conf/distro/include/no-static-libs.inc`` include file that 2045 disables static linking for a number of recipes. Some software 2046 packages or build tools (such as CMake) have explicit support for 2047 enabling / disabling static linking, and in those cases 2048 :term:`DISABLE_STATIC` is not used. 2049 2050 :term:`DISTRO` 2051 The short name of the distribution. For information on the long name 2052 of the distribution, see the :term:`DISTRO_NAME` 2053 variable. 2054 2055 The :term:`DISTRO` variable corresponds to a distribution configuration 2056 file whose root name is the same as the variable's argument and whose 2057 filename extension is ``.conf``. For example, the distribution 2058 configuration file for the Poky distribution is named ``poky.conf`` 2059 and resides in the ``meta-poky/conf/distro`` directory of the 2060 :term:`Source Directory`. 2061 2062 Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as 2063 follows:: 2064 2065 DISTRO = "poky" 2066 2067 Distribution configuration files are located in a ``conf/distro`` 2068 directory within the :term:`Metadata` that contains the 2069 distribution configuration. The value for :term:`DISTRO` must not contain 2070 spaces, and is typically all lower-case. 2071 2072 .. note:: 2073 2074 If the :term:`DISTRO` variable is blank, a set of default configurations 2075 are used, which are specified within 2076 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2077 2078 :term:`DISTRO_CODENAME` 2079 Specifies a codename for the distribution being built. 2080 2081 :term:`DISTRO_EXTRA_RDEPENDS` 2082 Specifies a list of distro-specific packages to add to all images. 2083 This variable takes effect through ``packagegroup-base`` so the 2084 variable only really applies to the more full-featured images that 2085 include ``packagegroup-base``. You can use this variable to keep 2086 distro policy out of generic images. As with all other distro 2087 variables, you set this variable in the distro ``.conf`` file. 2088 2089 :term:`DISTRO_EXTRA_RRECOMMENDS` 2090 Specifies a list of distro-specific packages to add to all images if 2091 the packages exist. The packages might not exist or be empty (e.g. 2092 kernel modules). The list of packages are automatically installed but 2093 you can remove them. 2094 2095 :term:`DISTRO_FEATURES` 2096 The software support you want in your distribution for various 2097 features. You define your distribution features in the distribution 2098 configuration file. 2099 2100 In most cases, the presence or absence of a feature in 2101 :term:`DISTRO_FEATURES` is translated to the appropriate option supplied 2102 to the configure script during the 2103 :ref:`ref-tasks-configure` task for recipes that 2104 optionally support the feature. For example, specifying "x11" in 2105 :term:`DISTRO_FEATURES`, causes every piece of software built for the 2106 target that can optionally support X11 to have its X11 support 2107 enabled. 2108 2109 .. note:: 2110 2111 Just enabling :term:`DISTRO_FEATURES` alone doesn't 2112 enable feature support for packages. Mechanisms such as making 2113 :term:`PACKAGECONFIG` track :term:`DISTRO_FEATURES` are used 2114 to enable/disable package features. 2115 2116 Two more examples are Bluetooth and NFS support. For a more complete 2117 list of features that ships with the Yocto Project and that you can 2118 provide with this variable, see the ":ref:`ref-features-distro`" section. 2119 2120 :term:`DISTRO_FEATURES_BACKFILL` 2121 A space-separated list of features to be added to :term:`DISTRO_FEATURES` 2122 if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. 2123 2124 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 2125 not intended to be user-configurable. It is best to just reference 2126 the variable to see which distro features are being 2127 :ref:`backfilled <ref-features-backfill>` for all distro configurations. 2128 2129 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 2130 A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL` 2131 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added 2132 to :term:`DISTRO_FEATURES`) during the build. 2133 2134 This corresponds to an opt-out mechanism. When new default distro 2135 features are introduced, distribution maintainers can review (`consider`) 2136 them and decide to exclude them from the 2137 :ref:`backfilled <ref-features-backfill>` features. Therefore, the 2138 combination of :term:`DISTRO_FEATURES_BACKFILL` and 2139 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to 2140 add new default features without breaking existing distributions. 2141 2142 2143 :term:`DISTRO_FEATURES_DEFAULT` 2144 A convenience variable that gives you the default list of distro 2145 features with the exception of any features specific to the C library 2146 (``libc``). 2147 2148 When creating a custom distribution, you might find it useful to be 2149 able to reuse the default 2150 :term:`DISTRO_FEATURES` options without the 2151 need to write out the full set. Here is an example that uses 2152 :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file:: 2153 2154 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" 2155 2156 :term:`DISTRO_FEATURES_FILTER_NATIVE` 2157 Specifies a list of features that if present in the target 2158 :term:`DISTRO_FEATURES` value should be 2159 included in :term:`DISTRO_FEATURES` when building native recipes. This 2160 variable is used in addition to the features filtered using the 2161 :term:`DISTRO_FEATURES_NATIVE` 2162 variable. 2163 2164 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` 2165 Specifies a list of features that if present in the target 2166 :term:`DISTRO_FEATURES` value should be included in 2167 :term:`DISTRO_FEATURES` when building :ref:`ref-classes-nativesdk` 2168 recipes. This variable is used in addition to the features filtered using 2169 the :term:`DISTRO_FEATURES_NATIVESDK` variable. 2170 2171 :term:`DISTRO_FEATURES_NATIVE` 2172 Specifies a list of features that should be included in 2173 :term:`DISTRO_FEATURES` when building native 2174 recipes. This variable is used in addition to the features filtered 2175 using the 2176 :term:`DISTRO_FEATURES_FILTER_NATIVE` 2177 variable. 2178 2179 :term:`DISTRO_FEATURES_NATIVESDK` 2180 Specifies a list of features that should be included in 2181 :term:`DISTRO_FEATURES` when building 2182 :ref:`ref-classes-nativesdk` recipes. This variable is used 2183 in addition to the features filtered using the 2184 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` variable. 2185 2186 :term:`DISTRO_NAME` 2187 The long name of the distribution. For information on the short name 2188 of the distribution, see the :term:`DISTRO` variable. 2189 2190 The :term:`DISTRO_NAME` variable corresponds to a distribution 2191 configuration file whose root name is the same as the variable's 2192 argument and whose filename extension is ``.conf``. For example, the 2193 distribution configuration file for the Poky distribution is named 2194 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory 2195 of the :term:`Source Directory`. 2196 2197 Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set 2198 as follows:: 2199 2200 DISTRO_NAME = "Poky (Yocto Project Reference Distro)" 2201 2202 Distribution configuration files are located in a ``conf/distro`` 2203 directory within the :term:`Metadata` that contains the 2204 distribution configuration. 2205 2206 .. note:: 2207 2208 If the :term:`DISTRO_NAME` variable is blank, a set of default 2209 configurations are used, which are specified within 2210 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2211 2212 :term:`DISTRO_VERSION` 2213 The version of the distribution. 2214 2215 :term:`DISTROOVERRIDES` 2216 A colon-separated list of overrides specific to the current 2217 distribution. By default, this list includes the value of 2218 :term:`DISTRO`. 2219 2220 You can extend :term:`DISTROOVERRIDES` to add extra overrides that should 2221 apply to the distribution. 2222 2223 The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it 2224 is included in the default value of 2225 :term:`OVERRIDES`. 2226 2227 Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf 2228 </poky/tree/meta-poky/conf/distro/poky-tiny.conf>`:: 2229 2230 DISTROOVERRIDES = "poky:poky-tiny" 2231 2232 :term:`DL_DIR` 2233 The central download directory used by the build process to store 2234 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring 2235 for everything except Git repositories. If you want tarballs of Git 2236 repositories, use the 2237 :term:`BB_GENERATE_MIRROR_TARBALLS` 2238 variable. 2239 2240 You can set this directory by defining the :term:`DL_DIR` variable in the 2241 ``conf/local.conf`` file. This directory is self-maintaining and you 2242 should not have to touch it. By default, the directory is 2243 ``downloads`` in the :term:`Build Directory`:: 2244 2245 #DL_DIR ?= "${TOPDIR}/downloads" 2246 2247 To specify a different download directory, 2248 simply remove the comment from the line and provide your directory. 2249 2250 During a first build, the system downloads many different source code 2251 tarballs from various upstream projects. Downloading can take a 2252 while, particularly if your network connection is slow. Tarballs are 2253 all stored in the directory defined by :term:`DL_DIR` and the build 2254 system looks there first to find source tarballs. 2255 2256 .. note:: 2257 2258 When wiping and rebuilding, you can preserve this directory to 2259 speed up this part of subsequent builds. 2260 2261 You can safely share this directory between multiple builds on the 2262 same development machine. For additional information on how the build 2263 process gets source files when working behind a firewall or proxy 2264 server, see this specific question in the ":doc:`faq`" 2265 chapter. You can also refer to the 2266 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 2267 Wiki page. 2268 2269 :term:`DOC_COMPRESS` 2270 When inheriting the :ref:`ref-classes-compress_doc` 2271 class, this variable sets the compression policy used when the 2272 OpenEmbedded build system compresses man pages and info pages. By 2273 default, the compression method used is gz (gzip). Other policies 2274 available are xz and bz2. 2275 2276 For information on policies and on how to use this variable, see the 2277 comments in the ``meta/classes-recipe/compress_doc.bbclass`` file. 2278 2279 :term:`DT_FILES` 2280 Space-separated list of device tree source files to compile using 2281 a recipe that inherits the :ref:`ref-classes-devicetree` class. These 2282 are relative to the :term:`DT_FILES_PATH`. 2283 2284 For convenience, both ``.dts`` and ``.dtb`` extensions can be used. 2285 2286 Use an empty string (default) to build all device tree sources within 2287 the :term:`DT_FILES_PATH` directory. 2288 2289 :term:`DT_FILES_PATH` 2290 When compiling out-of-tree device tree sources using a recipe that 2291 inherits the :ref:`ref-classes-devicetree` class, this variable specifies 2292 the path to the directory containing dts files to build. 2293 2294 Defaults to the :term:`S` directory. 2295 2296 :term:`DT_PADDING_SIZE` 2297 When inheriting the :ref:`ref-classes-devicetree` class, this variable 2298 specifies the size of padding appended to the device tree blob, used as 2299 extra space typically for additional properties during boot. 2300 2301 :term:`EFI_PROVIDER` 2302 When building bootable images (i.e. where ``hddimg``, ``iso``, or 2303 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the 2304 :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The 2305 default is "grub-efi", but "systemd-boot" can be used instead. 2306 2307 See the :ref:`ref-classes-systemd-boot` and :ref:`ref-classes-image-live` 2308 classes for more information. 2309 2310 :term:`ENABLE_BINARY_LOCALE_GENERATION` 2311 Variable that controls which locales for ``glibc`` are generated 2312 during the build (useful if the target device has 64Mbytes of RAM or 2313 less). 2314 2315 :term:`ERR_REPORT_DIR` 2316 When used with the :ref:`ref-classes-report-error` class, specifies the 2317 path used for storing the debug files created by the :ref:`error reporting 2318 tool <dev-manual/error-reporting-tool:using the error reporting tool>`, 2319 which allows you to submit build errors you encounter to a central 2320 database. By default, the value of this variable is 2321 ``${``\ :term:`LOG_DIR`\ ``}/error-report``. 2322 2323 You can set :term:`ERR_REPORT_DIR` to the path you want the error 2324 reporting tool to store the debug files as follows in your 2325 ``local.conf`` file:: 2326 2327 ERR_REPORT_DIR = "path" 2328 2329 :term:`ERROR_QA` 2330 Specifies the quality assurance checks whose failures are reported as 2331 errors by the OpenEmbedded build system. You set this variable in 2332 your distribution configuration file. For a list of the checks you 2333 can control with this variable, see the 2334 ":ref:`ref-classes-insane`" section. 2335 2336 :term:`ESDK_CLASS_INHERIT_DISABLE` 2337 A list of classes to remove from the :term:`INHERIT` 2338 value globally within the extensible SDK configuration. The 2339 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the 2340 default value:: 2341 2342 ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc" 2343 2344 Some classes are not generally applicable within the extensible SDK 2345 context. You can use this variable to disable those classes. 2346 2347 For additional information on how to customize the extensible SDK's 2348 configuration, see the 2349 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2350 section in the Yocto Project Application Development and the 2351 Extensible Software Development Kit (eSDK) manual. 2352 2353 :term:`ESDK_LOCALCONF_ALLOW` 2354 A list of variables allowed through from the OpenEmbedded build 2355 system configuration into the extensible SDK configuration. By 2356 default, the list of variables is empty and is set in the 2357 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. 2358 2359 This list overrides the variables specified using the 2360 :term:`ESDK_LOCALCONF_REMOVE` variable as well as 2361 other variables automatically added due to the "/" character 2362 being found at the start of the 2363 value, which is usually indicative of being a path and thus might not 2364 be valid on the system where the SDK is installed. 2365 2366 For additional information on how to customize the extensible SDK's 2367 configuration, see the 2368 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2369 section in the Yocto Project Application Development and the 2370 Extensible Software Development Kit (eSDK) manual. 2371 2372 :term:`ESDK_LOCALCONF_REMOVE` 2373 A list of variables not allowed through from the OpenEmbedded build 2374 system configuration into the extensible SDK configuration. Usually, 2375 these are variables that are specific to the machine on which the 2376 build system is running and thus would be potentially problematic 2377 within the extensible SDK. 2378 2379 By default, :term:`ESDK_LOCALCONF_REMOVE` is set in the 2380 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and 2381 excludes the following variables: 2382 2383 - :term:`CONF_VERSION` 2384 - :term:`BB_NUMBER_THREADS` 2385 - :term:`BB_NUMBER_PARSE_THREADS` 2386 - :term:`PARALLEL_MAKE` 2387 - :term:`PRSERV_HOST` 2388 - :term:`SSTATE_MIRRORS` :term:`DL_DIR` 2389 - :term:`SSTATE_DIR` :term:`TMPDIR` 2390 - :term:`BB_SERVER_TIMEOUT` 2391 2392 For additional information on how to customize the extensible SDK's 2393 configuration, see the 2394 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2395 section in the Yocto Project Application Development and the 2396 Extensible Software Development Kit (eSDK) manual. 2397 2398 :term:`EXCLUDE_FROM_SHLIBS` 2399 Triggers the OpenEmbedded build system's shared libraries resolver to 2400 exclude an entire package when scanning for shared libraries. 2401 2402 .. note:: 2403 2404 The shared libraries resolver's functionality results in part from 2405 the internal function ``package_do_shlibs``, which is part of the 2406 :ref:`ref-tasks-package` task. You should be aware that the shared 2407 libraries resolver might implicitly define some dependencies between 2408 packages. 2409 2410 The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the 2411 :term:`PRIVATE_LIBS` variable, which excludes a 2412 package's particular libraries only and not the whole package. 2413 2414 Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a 2415 particular package:: 2416 2417 EXCLUDE_FROM_SHLIBS = "1" 2418 2419 :term:`EXCLUDE_FROM_WORLD` 2420 Directs BitBake to exclude a recipe from world builds (i.e. 2421 ``bitbake world``). During world builds, BitBake locates, parses and 2422 builds all recipes found in every layer exposed in the 2423 ``bblayers.conf`` configuration file. 2424 2425 To exclude a recipe from a world build using this variable, set the 2426 variable to "1" in the recipe. 2427 2428 .. note:: 2429 2430 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a 2431 world build in order to satisfy dependencies of other recipes. Adding 2432 a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not 2433 explicitly added to the list of build targets in a world build. 2434 2435 :term:`EXTENDPE` 2436 Used with file and pathnames to create a prefix for a recipe's 2437 version based on the recipe's :term:`PE` value. If :term:`PE` 2438 is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that 2439 value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1"). 2440 If a recipe's :term:`PE` is not set (the default) or is equal to zero, 2441 :term:`EXTENDPE` becomes "". 2442 2443 See the :term:`STAMP` variable for an example. 2444 2445 :term:`EXTENDPKGV` 2446 The full package version specification as it appears on the final 2447 packages produced by a recipe. The variable's value is normally used 2448 to fix a runtime dependency to the exact same version of another 2449 package in the same recipe:: 2450 2451 RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" 2452 2453 The dependency relationships are intended to force the package 2454 manager to upgrade these types of packages in lock-step. 2455 2456 :term:`EXTERNAL_KERNEL_TOOLS` 2457 When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these 2458 tools are not in the source tree. 2459 2460 When kernel tools are available in the tree, they are preferred over 2461 any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS` 2462 variable tells the OpenEmbedded build system to prefer the installed 2463 external tools. See the :ref:`ref-classes-kernel-yocto` class in 2464 ``meta/classes-recipe`` to see how the variable is used. 2465 2466 :term:`EXTERNAL_TOOLCHAIN` 2467 When you intend to use an 2468 :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`, 2469 this variable allows to specify the directory where this toolchain was 2470 installed. 2471 2472 :term:`EXTERNALSRC` 2473 When inheriting the :ref:`ref-classes-externalsrc` 2474 class, this variable points to the source tree, which is outside of 2475 the OpenEmbedded build system. When set, this variable sets the 2476 :term:`S` variable, which is what the OpenEmbedded build 2477 system uses to locate unpacked recipe source code. 2478 2479 See the ":ref:`ref-classes-externalsrc`" section for details. You 2480 can also find information on how to use this variable in the 2481 ":ref:`dev-manual/building:building software from an external source`" 2482 section in the Yocto Project Development Tasks Manual. 2483 2484 :term:`EXTERNALSRC_BUILD` 2485 When inheriting the :ref:`ref-classes-externalsrc` 2486 class, this variable points to the directory in which the recipe's 2487 source code is built, which is outside of the OpenEmbedded build 2488 system. When set, this variable sets the :term:`B` variable, 2489 which is what the OpenEmbedded build system uses to locate the 2490 :term:`Build Directory`. 2491 2492 See the ":ref:`ref-classes-externalsrc`" section for details. You 2493 can also find information on how to use this variable in the 2494 ":ref:`dev-manual/building:building software from an external source`" 2495 section in the Yocto Project Development Tasks Manual. 2496 2497 :term:`EXTRA_AUTORECONF` 2498 For recipes inheriting the :ref:`ref-classes-autotools` 2499 class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to 2500 pass to the ``autoreconf`` command that is executed during the 2501 :ref:`ref-tasks-configure` task. 2502 2503 The default value is "--exclude=autopoint". 2504 2505 :term:`EXTRA_IMAGE_FEATURES` 2506 A list of additional features to include in an image. When listing 2507 more than one feature, separate them with a space. 2508 2509 Typically, you configure this variable in your ``local.conf`` file, 2510 which is found in the :term:`Build Directory`. Although you can use this 2511 variable from within a recipe, best practices dictate that you do not. 2512 2513 .. note:: 2514 2515 To enable primary features from within the image recipe, use the 2516 :term:`IMAGE_FEATURES` variable. 2517 2518 Here are some examples of features you can add: 2519 2520 - "dbg-pkgs" --- adds -dbg packages for all installed packages including 2521 symbol information for debugging and profiling. 2522 2523 - "debug-tweaks" --- makes an image suitable for debugging. For example, allows root logins without passwords and 2524 enables post-installation logging. See the 'allow-empty-password' and 2525 'post-install-logging' features in the ":ref:`ref-features-image`" 2526 section for more information. 2527 - "dev-pkgs" --- adds -dev packages for all installed packages. This is 2528 useful if you want to develop against the libraries in the image. 2529 - "read-only-rootfs" --- creates an image whose root filesystem is 2530 read-only. See the 2531 ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`" 2532 section in the Yocto Project Development Tasks Manual for more 2533 information 2534 - "tools-debug" --- adds debugging tools such as gdb and strace. 2535 - "tools-sdk" --- adds development tools such as gcc, make, 2536 pkgconfig and so forth. 2537 - "tools-testapps" --- adds useful testing tools 2538 such as ts_print, aplay, arecord and so forth. 2539 2540 For a complete list of image features that ships with the Yocto 2541 Project, see the ":ref:`ref-features-image`" section. 2542 2543 For an example that shows how to customize your image by using this 2544 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 2545 section in the Yocto Project Development Tasks Manual. 2546 2547 :term:`EXTRA_IMAGECMD` 2548 Specifies additional options for the image creation command that has 2549 been specified in :term:`IMAGE_CMD`. When setting 2550 this variable, use an override for the associated image type. Here is 2551 an example:: 2552 2553 EXTRA_IMAGECMD:ext3 ?= "-i 4096" 2554 2555 :term:`EXTRA_IMAGEDEPENDS` 2556 A list of recipes to build that do not provide packages for 2557 installing into the root filesystem. 2558 2559 Sometimes a recipe is required to build the final image but is not 2560 needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS` 2561 variable to list these recipes and thus specify the dependencies. A 2562 typical example is a required bootloader in a machine configuration. 2563 2564 .. note:: 2565 2566 To add packages to the root filesystem, see the various 2567 :term:`RDEPENDS` and :term:`RRECOMMENDS` variables. 2568 2569 :term:`EXTRA_OECMAKE` 2570 Additional `CMake <https://cmake.org/overview/>`__ options. See the 2571 :ref:`ref-classes-cmake` class for additional information. 2572 2573 :term:`EXTRA_OECONF` 2574 Additional ``configure`` script options. See 2575 :term:`PACKAGECONFIG_CONFARGS` for 2576 additional information on passing configure script options. 2577 2578 :term:`EXTRA_OEMAKE` 2579 Additional GNU ``make`` options. 2580 2581 Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the 2582 variable to specify any required GNU options. 2583 2584 :term:`PARALLEL_MAKE` and 2585 :term:`PARALLEL_MAKEINST` also make use of 2586 :term:`EXTRA_OEMAKE` to pass the required flags. 2587 2588 :term:`EXTRA_OESCONS` 2589 When inheriting the :ref:`ref-classes-scons` class, this 2590 variable specifies additional configuration options you want to pass 2591 to the ``scons`` command line. 2592 2593 :term:`EXTRA_OEMESON` 2594 Additional `Meson <https://mesonbuild.com/>`__ options. See the 2595 :ref:`ref-classes-meson` class for additional information. 2596 2597 In addition to standard Meson options, such options correspond to 2598 `Meson build options <https://mesonbuild.com/Build-options.html>`__ 2599 defined in the ``meson_options.txt`` file in the sources to build. 2600 Here is an example:: 2601 2602 EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled" 2603 2604 Note that any custom value for the Meson ``--buildtype`` option 2605 should be set through the :term:`MESON_BUILDTYPE` variable. 2606 2607 :term:`EXTRA_USERS_PARAMS` 2608 When inheriting the :ref:`ref-classes-extrausers` 2609 class, this variable provides image level user and group operations. 2610 This is a more global method of providing user and group 2611 configuration as compared to using the 2612 :ref:`ref-classes-useradd` class, which ties user and 2613 group configurations to a specific recipe. 2614 2615 The set list of commands you can configure using the 2616 :term:`EXTRA_USERS_PARAMS` is shown in the 2617 :ref:`ref-classes-extrausers` class. These commands map to the normal 2618 Unix commands of the same names:: 2619 2620 # EXTRA_USERS_PARAMS = "\ 2621 # useradd -p '' tester; \ 2622 # groupadd developers; \ 2623 # userdel nobody; \ 2624 # groupdel -g video; \ 2625 # groupmod -g 1020 developers; \ 2626 # usermod -s /bin/sh tester; \ 2627 # " 2628 2629 Hardcoded passwords are supported via the ``-p`` parameters for 2630 ``useradd`` or ``usermod``, but only hashed. 2631 2632 Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns 2633 passwords. First on host, create the (escaped) password hash:: 2634 2635 printf "%q" $(mkpasswd -m sha256crypt tester01) 2636 2637 The resulting hash is set to a variable and used in ``useradd`` command parameters:: 2638 2639 inherit extrausers 2640 PASSWD = "\$X\$ABC123\$A-Long-Hash" 2641 EXTRA_USERS_PARAMS = "\ 2642 useradd -p '${PASSWD}' tester-jim; \ 2643 useradd -p '${PASSWD}' tester-sue; \ 2644 " 2645 2646 Finally, here is an example that sets the root password:: 2647 2648 inherit extrausers 2649 EXTRA_USERS_PARAMS = "\ 2650 usermod -p '${PASSWD}' root; \ 2651 " 2652 2653 .. note:: 2654 2655 From a security perspective, hardcoding a default password is not 2656 generally a good idea or even legal in some jurisdictions. It is 2657 recommended that you do not do this if you are building a production 2658 image. 2659 2660 Additionally there is a special ``passwd-expire`` command that will 2661 cause the password for a user to be expired and thus force changing it 2662 on first login, for example:: 2663 2664 EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;" 2665 2666 .. note:: 2667 2668 At present, ``passwd-expire`` may only work for remote logins when 2669 using OpenSSH and not dropbear as an SSH server. 2670 2671 :term:`EXTRANATIVEPATH` 2672 A list of subdirectories of 2673 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` 2674 added to the beginning of the environment variable ``PATH``. As an 2675 example, the following prepends 2676 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to 2677 ``PATH``:: 2678 2679 EXTRANATIVEPATH = "foo bar" 2680 2681 :term:`FAKEROOT` 2682 See :term:`bitbake:FAKEROOT` in the BitBake manual. 2683 2684 :term:`FAKEROOTBASEENV` 2685 See :term:`bitbake:FAKEROOTBASEENV` in the BitBake manual. 2686 2687 :term:`FAKEROOTCMD` 2688 See :term:`bitbake:FAKEROOTCMD` in the BitBake manual. 2689 2690 :term:`FAKEROOTDIRS` 2691 See :term:`bitbake:FAKEROOTDIRS` in the BitBake manual. 2692 2693 :term:`FAKEROOTENV` 2694 See :term:`bitbake:FAKEROOTENV` in the BitBake manual. 2695 2696 :term:`FAKEROOTNOENV` 2697 See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual. 2698 2699 :term:`FEATURE_PACKAGES` 2700 Defines one or more packages to include in an image when a specific 2701 item is included in :term:`IMAGE_FEATURES`. 2702 When setting the value, :term:`FEATURE_PACKAGES` should have the name of 2703 the feature item as an override. Here is an example:: 2704 2705 FEATURE_PACKAGES_widget = "package1 package2" 2706 2707 In this example, if "widget" were added to :term:`IMAGE_FEATURES`, 2708 package1 and package2 would be included in the image. 2709 2710 .. note:: 2711 2712 Packages installed by features defined through :term:`FEATURE_PACKAGES` 2713 are often package groups. While similarly named, you should not 2714 confuse the :term:`FEATURE_PACKAGES` variable with package groups, which 2715 are discussed elsewhere in the documentation. 2716 2717 :term:`FEED_DEPLOYDIR_BASE_URI` 2718 Points to the base URL of the server and location within the 2719 document-root that provides the metadata and packages required by 2720 OPKG to support runtime package management of IPK packages. You set 2721 this variable in your ``local.conf`` file. 2722 2723 Consider the following example:: 2724 2725 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" 2726 2727 This example assumes you are serving 2728 your packages over HTTP and your databases are located in a directory 2729 named ``BOARD-dir``, which is underneath your HTTP server's 2730 document-root. In this case, the OpenEmbedded build system generates 2731 a set of configuration files for you in your target that work with 2732 the feed. 2733 2734 :term:`FETCHCMD` 2735 See :term:`bitbake:FETCHCMD` in the BitBake manual. 2736 2737 :term:`FILE` 2738 See :term:`bitbake:FILE` in the BitBake manual. 2739 2740 :term:`FILES` 2741 The list of files and directories that are placed in a package. The 2742 :term:`PACKAGES` variable lists the packages 2743 generated by a recipe. 2744 2745 To use the :term:`FILES` variable, provide a package name override that 2746 identifies the resulting package. Then, provide a space-separated 2747 list of files or paths that identify the files you want included as 2748 part of the resulting package. Here is an example:: 2749 2750 FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" 2751 2752 .. note:: 2753 2754 - When specifying files or paths, you can pattern match using 2755 Python's 2756 `glob <https://docs.python.org/3/library/glob.html>`__ 2757 syntax. For details on the syntax, see the documentation by 2758 following the previous link. 2759 2760 - When specifying paths as part of the :term:`FILES` variable, it is 2761 good practice to use appropriate path variables. For example, 2762 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` 2763 rather than ``/usr/bin``. You can find a list of these 2764 variables at the top of the ``meta/conf/bitbake.conf`` file in 2765 the :term:`Source Directory`. You will also 2766 find the default values of the various ``FILES:*`` variables in 2767 this file. 2768 2769 If some of the files you provide with the :term:`FILES` variable are 2770 editable and you know they should not be overwritten during the 2771 package update process by the Package Management System (PMS), you 2772 can identify these files so that the PMS will not overwrite them. See 2773 the :term:`CONFFILES` variable for information on 2774 how to identify these files to the PMS. 2775 2776 :term:`FILES_SOLIBSDEV` 2777 Defines the file specification to match 2778 :term:`SOLIBSDEV`. In other words, 2779 :term:`FILES_SOLIBSDEV` defines the full path name of the development 2780 symbolic link (symlink) for shared libraries on the target platform. 2781 2782 The following statement from the ``bitbake.conf`` shows how it is 2783 set:: 2784 2785 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" 2786 2787 :term:`FILESEXTRAPATHS` 2788 A colon-separated list to extend the search path the OpenEmbedded build 2789 system uses when looking for files and patches as it processes recipes 2790 and append files. The default directories BitBake uses when it processes 2791 recipes are initially defined by the :term:`FILESPATH` variable. You can 2792 extend :term:`FILESPATH` variable by using :term:`FILESEXTRAPATHS`. 2793 2794 Best practices dictate that you accomplish this by using 2795 :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you 2796 prepend paths as follows:: 2797 2798 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 2799 2800 In the above example, the build system first 2801 looks for files in a directory that has the same name as the 2802 corresponding append file. 2803 2804 .. note:: 2805 2806 When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate 2807 expansion (``:=``) operator. Immediate expansion makes sure that 2808 BitBake evaluates :term:`THISDIR` at the time the 2809 directive is encountered rather than at some later time when 2810 expansion might result in a directory that does not contain the 2811 files you need. 2812 2813 Also, include the trailing separating colon character if you are 2814 prepending. The trailing colon character is necessary because you 2815 are directing BitBake to extend the path by prepending directories 2816 to the search path. 2817 2818 Here is another common use:: 2819 2820 FILESEXTRAPATHS:prepend := "${THISDIR}/files:" 2821 2822 In this example, the build system extends the 2823 :term:`FILESPATH` variable to include a directory named ``files`` that is 2824 in the same directory as the corresponding append file. 2825 2826 This next example specifically adds three paths:: 2827 2828 FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:" 2829 2830 A final example shows how you can extend the search path and include 2831 a :term:`MACHINE`-specific override, which is useful 2832 in a BSP layer:: 2833 2834 FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:" 2835 2836 The previous statement appears in the 2837 ``linux-yocto-dev.bbappend`` file, which is found in the 2838 :ref:`overview-manual/development-environment:yocto project source repositories` in 2839 ``meta-intel/common/recipes-kernel/linux``. Here, the machine 2840 override is a special :term:`PACKAGE_ARCH` 2841 definition for multiple ``meta-intel`` machines. 2842 2843 .. note:: 2844 2845 For a layer that supports a single BSP, the override could just be 2846 the value of :term:`MACHINE`. 2847 2848 By prepending paths in ``.bbappend`` files, you allow multiple append 2849 files that reside in different layers but are used for the same 2850 recipe to correctly extend the path. 2851 2852 :term:`FILESOVERRIDES` 2853 A colon-separated list to specify a subset of :term:`OVERRIDES` used by 2854 the OpenEmbedded build system for creating :term:`FILESPATH`. The 2855 :term:`FILESOVERRIDES` variable uses overrides to automatically extend 2856 the :term:`FILESPATH` variable. For an example of how that works, see the 2857 :term:`FILESPATH` variable description. Additionally, you find more 2858 information on how overrides are handled in the 2859 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 2860 section of the BitBake User Manual. 2861 2862 By default, the :term:`FILESOVERRIDES` variable is defined as:: 2863 2864 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" 2865 2866 .. note:: 2867 2868 Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up 2869 with expected overrides and are used in an expected manner by the 2870 build system. 2871 2872 :term:`FILESPATH` 2873 A colon-separated list specifying the default set of directories the 2874 OpenEmbedded build system uses when searching for patches and files. 2875 2876 During the build process, BitBake searches each directory in 2877 :term:`FILESPATH` in the specified order when looking for files and 2878 patches specified by each ``file://`` URI in a recipe's 2879 :term:`SRC_URI` statements. 2880 2881 The default value for the :term:`FILESPATH` variable is defined in the 2882 :ref:`ref-classes-base` class found in ``meta/classes-global`` in the 2883 :term:`Source Directory`:: 2884 2885 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ 2886 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" 2887 2888 The 2889 :term:`FILESPATH` variable is automatically extended using the overrides 2890 from the :term:`FILESOVERRIDES` variable. 2891 2892 .. note:: 2893 2894 - Do not hand-edit the :term:`FILESPATH` variable. If you want the 2895 build system to look in directories other than the defaults, 2896 extend the :term:`FILESPATH` variable by using the 2897 :term:`FILESEXTRAPATHS` variable. 2898 2899 - Be aware that the default :term:`FILESPATH` directories do not map 2900 to directories in custom layers where append files 2901 (``.bbappend``) are used. If you want the build system to find 2902 patches or files that reside with your append files, you need 2903 to extend the :term:`FILESPATH` variable by using the 2904 :term:`FILESEXTRAPATHS` variable. 2905 2906 You can take advantage of this searching behavior in useful ways. For 2907 example, consider a case where there is the following directory structure 2908 for general and machine-specific configurations:: 2909 2910 files/defconfig 2911 files/MACHINEA/defconfig 2912 files/MACHINEB/defconfig 2913 2914 Also in the example, the :term:`SRC_URI` statement contains 2915 "file://defconfig". Given this scenario, you can set 2916 :term:`MACHINE` to "MACHINEA" and cause the build 2917 system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to 2918 "MACHINEB" and the build system uses files from ``files/MACHINEB``. 2919 Finally, for any machine other than "MACHINEA" and "MACHINEB", the 2920 build system uses files from ``files/defconfig``. 2921 2922 You can find out more about the patching process in the 2923 ":ref:`overview-manual/concepts:patching`" section 2924 in the Yocto Project Overview and Concepts Manual and the 2925 ":ref:`dev-manual/new-recipe:patching code`" section in 2926 the Yocto Project Development Tasks Manual. See the 2927 :ref:`ref-tasks-patch` task as well. 2928 2929 :term:`FILESYSTEM_PERMS_TABLES` 2930 Allows you to define your own file permissions settings table as part 2931 of your configuration for the packaging process. For example, suppose 2932 you need a consistent set of custom permissions for a set of groups 2933 and users across an entire work project. It is best to do this in the 2934 packages themselves but this is not always possible. 2935 2936 By default, the OpenEmbedded build system uses the ``fs-perms.txt``, 2937 which is located in the ``meta/files`` folder in the :term:`Source Directory`. 2938 If you create your own file 2939 permissions setting table, you should place it in your layer or the 2940 distro's layer. 2941 2942 You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the 2943 ``conf/local.conf`` file, which is found in the :term:`Build Directory`, 2944 to point to your custom ``fs-perms.txt``. You can specify more than a 2945 single file permissions setting table. The paths you specify to these 2946 files must be defined within the :term:`BBPATH` variable. 2947 2948 For guidance on how to create your own file permissions settings 2949 table file, examine the existing ``fs-perms.txt``. 2950 2951 :term:`FIT_ADDRESS_CELLS` 2952 Specifies the value of the ``#address-cells`` value for the 2953 description of the FIT image. 2954 2955 The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` 2956 class, which corresponds to 32 bit addresses. 2957 2958 For platforms that need to set 64 bit addresses, for example in 2959 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to 2960 set this value to "2", as two 32 bit values (cells) will be needed 2961 to represent such addresses. 2962 2963 Here is an example setting "0x400000000" as a load address:: 2964 2965 FIT_ADDRESS_CELLS = "2" 2966 UBOOT_LOADADDRESS= "0x04 0x00000000" 2967 2968 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. 2969 2970 :term:`FIT_CONF_DEFAULT_DTB` 2971 Specifies the default device tree binary (dtb) file for a FIT image 2972 when multiple ones are provided. 2973 2974 This variable is used in the :ref:`ref-classes-kernel-fitimage` class. 2975 2976 :term:`FIT_DESC` 2977 Specifies the description string encoded into a FIT image. The 2978 default value is set by the :ref:`ref-classes-kernel-fitimage` class as 2979 follows:: 2980 2981 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" 2982 2983 :term:`FIT_GENERATE_KEYS` 2984 Decides whether to generate the keys for signing the FIT image if 2985 they don't already exist. The keys are created in 2986 :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0" 2987 by the :ref:`ref-classes-kernel-fitimage` class. 2988 2989 :term:`FIT_HASH_ALG` 2990 Specifies the hash algorithm used in creating the FIT Image. 2991 This variable is set by default to "sha256" by the 2992 :ref:`ref-classes-kernel-fitimage` class. 2993 2994 :term:`FIT_KERNEL_COMP_ALG` 2995 The compression algorithm to use for the kernel image inside the FIT Image. 2996 At present, the only supported values are "gzip" (default), "lzo" or "none". 2997 If you set this variable to anything other than "none" you may also need 2998 to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`. 2999 3000 This variable is used in the :ref:`ref-classes-kernel-uboot` class. 3001 3002 :term:`FIT_KERNEL_COMP_ALG_EXTENSION` 3003 File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default 3004 value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you 3005 set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this 3006 variable to ".lzo". 3007 3008 :term:`FIT_KEY_GENRSA_ARGS` 3009 Arguments to ``openssl genrsa`` for generating a RSA private key for 3010 signing the FIT image. The default value is set to "-F4" by the 3011 :ref:`ref-classes-kernel-fitimage` class. 3012 3013 :term:`FIT_KEY_REQ_ARGS` 3014 Arguments to ``openssl req`` for generating a certificate for signing 3015 the FIT image. The default value is "-batch -new" by the 3016 :ref:`ref-classes-kernel-fitimage` class, "batch" for 3017 non interactive mode and "new" for generating new keys. 3018 3019 :term:`FIT_KEY_SIGN_PKCS` 3020 Format for the public key certificate used for signing the FIT image. 3021 The default value is set to "x509" by the 3022 :ref:`ref-classes-kernel-fitimage` class. 3023 3024 :term:`FIT_SIGN_ALG` 3025 Specifies the signature algorithm used in creating the FIT Image. 3026 This variable is set by default to "rsa2048" by the 3027 :ref:`ref-classes-kernel-fitimage` class. 3028 3029 :term:`FIT_PAD_ALG` 3030 Specifies the padding algorithm used in creating the FIT Image. 3031 The default value is set to "pkcs-1.5" by the 3032 :ref:`ref-classes-kernel-fitimage` class. 3033 3034 :term:`FIT_SIGN_INDIVIDUAL` 3035 If set to "1", then the :ref:`ref-classes-kernel-fitimage` 3036 class will sign the kernel, dtb and ramdisk images individually in addition 3037 to signing the FIT image itself. This could be useful if you are 3038 intending to verify signatures in another context than booting via 3039 U-Boot. 3040 3041 This variable is set to "0" by default. 3042 3043 :term:`FIT_SIGN_NUMBITS` 3044 Size of the private key used in the FIT image, in number of bits. 3045 The default value for this variable is set to "2048" 3046 by the :ref:`ref-classes-kernel-fitimage` class. 3047 3048 :term:`FONT_EXTRA_RDEPENDS` 3049 When inheriting the :ref:`ref-classes-fontcache` class, 3050 this variable specifies the runtime dependencies for font packages. 3051 By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils". 3052 3053 :term:`FONT_PACKAGES` 3054 When inheriting the :ref:`ref-classes-fontcache` class, this variable 3055 identifies packages containing font files that need to be cached by 3056 Fontconfig. By default, the :ref:`ref-classes-fontcache` class assumes 3057 that fonts are in the recipe's main package (i.e. 3058 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you 3059 need are in a package other than that main package. 3060 3061 :term:`FORCE_RO_REMOVE` 3062 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED`` 3063 during the generation of the root filesystem. 3064 3065 Set the variable to "1" to force the removal of these packages. 3066 3067 :term:`FULL_OPTIMIZATION` 3068 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when 3069 compiling an optimized system. This variable defaults to "-O2 -pipe 3070 ${DEBUG_FLAGS}". 3071 3072 :term:`GCCPIE` 3073 Enables Position Independent Executables (PIE) within the GNU C 3074 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented 3075 Programming (ROP) attacks much more difficult to execute. 3076 3077 By default the ``security_flags.inc`` file enables PIE by setting the 3078 variable as follows:: 3079 3080 GCCPIE ?= "--enable-default-pie" 3081 3082 :term:`GCCVERSION` 3083 Specifies the default version of the GNU C Compiler (GCC) used for 3084 compilation. By default, :term:`GCCVERSION` is set to "8.x" in the 3085 ``meta/conf/distro/include/tcmode-default.inc`` include file:: 3086 3087 GCCVERSION ?= "8.%" 3088 3089 You can override this value by setting it in a 3090 configuration file such as the ``local.conf``. 3091 3092 :term:`GDB` 3093 The minimal command and arguments to run the GNU Debugger. 3094 3095 :term:`GIR_EXTRA_LIBS_PATH` 3096 Allows to specify an extra search path for ``.so`` files 3097 in GLib related recipes using GObject introspection, 3098 and which do not compile without this setting. 3099 See the ":ref:`dev-manual/gobject-introspection:enabling gobject introspection support`" 3100 section for details. 3101 3102 :term:`GITDIR` 3103 The directory in which a local copy of a Git repository is stored 3104 when it is cloned. 3105 3106 :term:`GITHUB_BASE_URI` 3107 When inheriting the :ref:`ref-classes-github-releases` 3108 class, specifies the base URL for fetching releases for the github 3109 project you wish to fetch sources from. The default value is as follows:: 3110 3111 GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/" 3112 3113 :term:`GLIBC_GENERATE_LOCALES` 3114 Specifies the list of GLIBC locales to generate should you not wish 3115 to generate all LIBC locals, which can be time consuming. 3116 3117 .. note:: 3118 3119 If you specifically remove the locale ``en_US.UTF-8``, you must set 3120 :term:`IMAGE_LINGUAS` appropriately. 3121 3122 You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file. 3123 By default, all locales are generated:: 3124 3125 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" 3126 3127 :term:`GO_IMPORT` 3128 When inheriting the :ref:`ref-classes-go` class, this mandatory variable 3129 sets the import path for the Go package that will be created for the code 3130 to build. If you have a ``go.mod`` file in the source directory, this 3131 typically matches the path in the ``module`` line in this file. 3132 3133 Other Go programs importing this package will use this path. 3134 3135 Here is an example setting from the 3136 :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>` 3137 recipe:: 3138 3139 GO_IMPORT = "golang.org/x/example" 3140 3141 :term:`GO_INSTALL` 3142 When inheriting the :ref:`ref-classes-go` class, this optional variable 3143 specifies which packages in the sources should be compiled and 3144 installed in the Go build space by the 3145 `go install <https://go.dev/ref/mod#go-install>`__ command. 3146 3147 Here is an example setting from the 3148 :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>` 3149 recipe:: 3150 3151 GO_INSTALL = "\ 3152 ${GO_IMPORT}/cmd/crucible \ 3153 ${GO_IMPORT}/cmd/habtool \ 3154 " 3155 3156 By default, :term:`GO_INSTALL` is defined as:: 3157 3158 GO_INSTALL ?= "${GO_IMPORT}/..." 3159 3160 The ``...`` wildcard means that it will catch all 3161 packages found in the sources. 3162 3163 See the :term:`GO_INSTALL_FILTEROUT` variable for 3164 filtering out unwanted packages from the ones 3165 found from the :term:`GO_INSTALL` value. 3166 3167 :term:`GO_INSTALL_FILTEROUT` 3168 When using the Go "vendor" mechanism to bring in dependencies for a Go 3169 package, the default :term:`GO_INSTALL` setting, which uses the ``...`` 3170 wildcard, will include the vendored packages in the build, which produces 3171 incorrect results. 3172 3173 There are also some Go packages that are structured poorly, so that the 3174 ``...`` wildcard results in building example or test code that should not 3175 be included in the build, or could fail to build. 3176 3177 This optional variable allows for filtering out a subset of the sources. 3178 It defaults to excluding everything under the ``vendor`` subdirectory 3179 under package's main directory. This is the normal location for vendored 3180 packages, but it can be overridden by a recipe to filter out other 3181 subdirectories if needed. 3182 3183 :term:`GO_WORKDIR` 3184 When using Go Modules, the current working directory must be the directory 3185 containing the ``go.mod`` file, or one of its subdirectories. When the 3186 ``go`` tool is used, it will automatically look for the ``go.mod`` file 3187 in the Go working directory or in any parent directory, but not in 3188 subdirectories. 3189 3190 When using the :ref:`ref-classes-go-mod` class to use Go modules, 3191 the optional :term:`GO_WORKDIR` variable, defaulting to the value 3192 of :term:`GO_IMPORT`, allows to specify a different Go working directory. 3193 3194 :term:`GROUPADD_PARAM` 3195 When inheriting the :ref:`ref-classes-useradd` class, 3196 this variable specifies for a package what parameters should be 3197 passed to the ``groupadd`` command if you wish to add a group to the 3198 system when the package is installed. 3199 3200 Here is an example from the ``dbus`` recipe:: 3201 3202 GROUPADD_PARAM:${PN} = "-r netdev" 3203 3204 For information on the standard Linux shell command 3205 ``groupadd``, see https://linux.die.net/man/8/groupadd. 3206 3207 :term:`GROUPMEMS_PARAM` 3208 When inheriting the :ref:`ref-classes-useradd` class, 3209 this variable specifies for a package what parameters should be 3210 passed to the ``groupmems`` command if you wish to modify the members 3211 of a group when the package is installed. 3212 3213 For information on the standard Linux shell command ``groupmems``, 3214 see https://linux.die.net/man/8/groupmems. 3215 3216 :term:`GRUB_GFXSERIAL` 3217 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics 3218 and serial in the boot menu. Set this variable to "1" in your 3219 ``local.conf`` or distribution configuration file to enable graphics 3220 and serial in the menu. 3221 3222 See the :ref:`ref-classes-grub-efi` class for more 3223 information on how this variable is used. 3224 3225 :term:`GRUB_OPTS` 3226 Additional options to add to the GNU GRand Unified Bootloader (GRUB) 3227 configuration. Use a semi-colon character (``;``) to separate 3228 multiple options. 3229 3230 The :term:`GRUB_OPTS` variable is optional. See the 3231 :ref:`ref-classes-grub-efi` class for more information 3232 on how this variable is used. 3233 3234 :term:`GRUB_TIMEOUT` 3235 Specifies the timeout before executing the default ``LABEL`` in the 3236 GNU GRand Unified Bootloader (GRUB). 3237 3238 The :term:`GRUB_TIMEOUT` variable is optional. See the 3239 :ref:`ref-classes-grub-efi` class for more information 3240 on how this variable is used. 3241 3242 :term:`GTKIMMODULES_PACKAGES` 3243 When inheriting the :ref:`ref-classes-gtk-immodules-cache` class, 3244 this variable specifies the packages that contain the GTK+ input 3245 method modules being installed when the modules are in packages other 3246 than the main package. 3247 3248 :term:`HGDIR` 3249 See :term:`bitbake:HGDIR` in the BitBake manual. 3250 3251 :term:`HOMEPAGE` 3252 Website where more information about the software the recipe is 3253 building can be found. 3254 3255 :term:`HOST_ARCH` 3256 The name of the target architecture, which is normally the same as 3257 :term:`TARGET_ARCH`. The OpenEmbedded build system 3258 supports many architectures. Here is an example list of architectures 3259 supported. This list is by no means complete as the architecture is 3260 configurable: 3261 3262 - arm 3263 - i586 3264 - x86_64 3265 - powerpc 3266 - powerpc64 3267 - mips 3268 - mipsel 3269 3270 :term:`HOST_CC_ARCH` 3271 Specifies architecture-specific compiler flags that are passed to the 3272 C compiler. 3273 3274 Default initialization for :term:`HOST_CC_ARCH` varies depending on what 3275 is being built: 3276 3277 - :term:`TARGET_CC_ARCH` when building for the 3278 target 3279 3280 - :term:`BUILD_CC_ARCH` when building for the build host (i.e. 3281 ``-native``) 3282 3283 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e. 3284 ``nativesdk-``) 3285 3286 :term:`HOST_OS` 3287 Specifies the name of the target operating system, which is normally 3288 the same as the :term:`TARGET_OS`. The variable can 3289 be set to "linux" for ``glibc``-based systems and to "linux-musl" for 3290 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and 3291 "linux-musleabi" values possible. 3292 3293 :term:`HOST_PREFIX` 3294 Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX` 3295 is normally the same as :term:`TARGET_PREFIX`. 3296 3297 :term:`HOST_SYS` 3298 Specifies the system, including the architecture and the operating 3299 system, for which the build is occurring in the context of the 3300 current recipe. 3301 3302 The OpenEmbedded build system automatically sets this variable based 3303 on :term:`HOST_ARCH`, 3304 :term:`HOST_VENDOR`, and 3305 :term:`HOST_OS` variables. 3306 3307 .. note:: 3308 3309 You do not need to set the variable yourself. 3310 3311 Consider these two examples: 3312 3313 - Given a native recipe on a 32-bit x86 machine running Linux, the 3314 value is "i686-linux". 3315 3316 - Given a recipe being built for a little-endian MIPS target running 3317 Linux, the value might be "mipsel-linux". 3318 3319 :term:`HOST_VENDOR` 3320 Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the 3321 same as :term:`TARGET_VENDOR`. 3322 3323 :term:`HOSTTOOLS` 3324 A space-separated list (filter) of tools on the build host that 3325 should be allowed to be called from within build tasks. Using this 3326 filter helps reduce the possibility of host contamination. If a tool 3327 specified in the value of :term:`HOSTTOOLS` is not found on the build 3328 host, the OpenEmbedded build system produces an error and the build 3329 is not started. 3330 3331 For additional information, see 3332 :term:`HOSTTOOLS_NONFATAL`. 3333 3334 :term:`HOSTTOOLS_NONFATAL` 3335 A space-separated list (filter) of tools on the build host that 3336 should be allowed to be called from within build tasks. Using this 3337 filter helps reduce the possibility of host contamination. Unlike 3338 :term:`HOSTTOOLS`, the OpenEmbedded build system 3339 does not produce an error if a tool specified in the value of 3340 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can 3341 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools. 3342 3343 :term:`ICECC_CLASS_DISABLE` 3344 Identifies user classes that you do not want the Icecream distributed 3345 compile support to consider. This variable is used by the 3346 :ref:`ref-classes-icecc` class. You set this variable in 3347 your ``local.conf`` file. 3348 3349 When you list classes using this variable, the recipes inheriting 3350 those classes will not benefit from distributed compilation across 3351 remote hosts. Instead they will be built locally. 3352 3353 :term:`ICECC_DISABLED` 3354 Disables or enables the ``icecc`` (Icecream) function. For more 3355 information on this function and best practices for using this 3356 variable, see the ":ref:`ref-classes-icecc`" 3357 section. 3358 3359 Setting this variable to "1" in your ``local.conf`` disables the 3360 function:: 3361 3362 ICECC_DISABLED ??= "1" 3363 3364 To enable the function, set the variable as follows:: 3365 3366 ICECC_DISABLED = "" 3367 3368 :term:`ICECC_ENV_EXEC` 3369 Points to the ``icecc-create-env`` script that you provide. This 3370 variable is used by the :ref:`ref-classes-icecc` class. You 3371 set this variable in your ``local.conf`` file. 3372 3373 If you do not point to a script that you provide, the OpenEmbedded 3374 build system uses the default script provided by the 3375 :oe_git:`icecc-create-env_0.1.bb 3376 </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>` 3377 recipe, which is a modified version and not the one that comes with 3378 ``icecream``. 3379 3380 :term:`ICECC_PARALLEL_MAKE` 3381 Extra options passed to the ``make`` command during the 3382 :ref:`ref-tasks-compile` task that specify parallel 3383 compilation. This variable usually takes the form of "-j x", where x 3384 represents the maximum number of parallel threads ``make`` can run. 3385 3386 .. note:: 3387 3388 The options passed affect builds on all enabled machines on the 3389 network, which are machines running the ``iceccd`` daemon. 3390 3391 If your enabled machines support multiple cores, coming up with the 3392 maximum number of parallel threads that gives you the best 3393 performance could take some experimentation since machine speed, 3394 network lag, available memory, and existing machine loads can all 3395 affect build time. Consequently, unlike the 3396 :term:`PARALLEL_MAKE` variable, there is no 3397 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal 3398 performance. 3399 3400 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not 3401 use it (i.e. the system does not detect and assign the number of 3402 cores as is done with :term:`PARALLEL_MAKE`). 3403 3404 :term:`ICECC_PATH` 3405 The location of the ``icecc`` binary. You can set this variable in 3406 your ``local.conf`` file. If your ``local.conf`` file does not define 3407 this variable, the :ref:`ref-classes-icecc` class attempts 3408 to define it by locating ``icecc`` using ``which``. 3409 3410 :term:`ICECC_RECIPE_DISABLE` 3411 Identifies user recipes that you do not want the Icecream distributed 3412 compile support to consider. This variable is used by the 3413 :ref:`ref-classes-icecc` class. You set this variable in 3414 your ``local.conf`` file. 3415 3416 When you list recipes using this variable, you are excluding them 3417 from distributed compilation across remote hosts. Instead they will 3418 be built locally. 3419 3420 :term:`ICECC_RECIPE_ENABLE` 3421 Identifies user recipes that use an empty 3422 :term:`PARALLEL_MAKE` variable that you want to 3423 force remote distributed compilation on using the Icecream 3424 distributed compile support. This variable is used by the 3425 :ref:`ref-classes-icecc` class. You set this variable in 3426 your ``local.conf`` file. 3427 3428 :term:`IMAGE_BASENAME` 3429 The base name of image output files. This variable defaults to the 3430 recipe name (``${``\ :term:`PN`\ ``}``). 3431 3432 :term:`IMAGE_BOOT_FILES` 3433 A space-separated list of files installed into the boot partition 3434 when preparing an image using the Wic tool with the 3435 ``bootimg-partition`` source plugin. By default, 3436 the files are 3437 installed under the same name as the source files. To change the 3438 installed name, separate it from the original name with a semi-colon 3439 (;). Source files need to be located in 3440 :term:`DEPLOY_DIR_IMAGE`. Here are two 3441 examples:: 3442 3443 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" 3444 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" 3445 3446 Alternatively, source files can be picked up using a glob pattern. In 3447 this case, the destination file must have the same name as the base 3448 name of the source file path. To install files into a directory 3449 within the target location, pass its name after a semi-colon (;). 3450 Here are two examples:: 3451 3452 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" 3453 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" 3454 3455 The first example 3456 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles`` 3457 into the root of the target partition. The second example installs 3458 the same files into a ``boot`` directory within the target partition. 3459 3460 You can find information on how to use the Wic tool in the 3461 ":ref:`dev-manual/wic:creating partitioned images using wic`" 3462 section of the Yocto Project Development Tasks Manual. Reference 3463 material for Wic is located in the 3464 ":doc:`/ref-manual/kickstart`" chapter. 3465 3466 :term:`IMAGE_BUILDINFO_FILE` 3467 When using the :ref:`ref-classes-image-buildinfo` class, 3468 specifies the file in the image to write the build information into. The 3469 default value is "``${sysconfdir}/buildinfo``". 3470 3471 :term:`IMAGE_BUILDINFO_VARS` 3472 When using the :ref:`ref-classes-image-buildinfo` class, 3473 specifies the list of variables to include in the `Build Configuration` 3474 section of the output file (as a space-separated list). Defaults to 3475 ":term:`DISTRO` :term:`DISTRO_VERSION`". 3476 3477 :term:`IMAGE_CLASSES` 3478 A list of classes that all images should inherit. This is typically used 3479 to enable functionality across all image recipes. 3480 3481 Classes specified in :term:`IMAGE_CLASSES` must be located in the 3482 ``classes-recipe/`` or ``classes/`` subdirectories. 3483 3484 :term:`IMAGE_CMD` 3485 Specifies the command to create the image file for a specific image 3486 type, which corresponds to the value set in 3487 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, 3488 ``btrfs``, and so forth). When setting this variable, you should use 3489 an override for the associated type. Here is an example:: 3490 3491 IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \ 3492 --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \ 3493 ${EXTRA_IMAGECMD}" 3494 3495 You typically do not need to set this variable unless you are adding 3496 support for a new image type. For more examples on how to set this 3497 variable, see the :ref:`ref-classes-image_types` 3498 class file, which is ``meta/classes-recipe/image_types.bbclass``. 3499 3500 :term:`IMAGE_DEVICE_TABLES` 3501 Specifies one or more files that contain custom device tables that 3502 are passed to the ``makedevs`` command as part of creating an image. 3503 These files list basic device nodes that should be created under 3504 ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set, 3505 ``files/device_table-minimal.txt`` is used, which is located by 3506 :term:`BBPATH`. For details on how you should write 3507 device table files, see ``meta/files/device_table-minimal.txt`` as an 3508 example. 3509 3510 :term:`IMAGE_EFI_BOOT_FILES` 3511 A space-separated list of files installed into the boot partition 3512 when preparing an image using the Wic tool with the 3513 ``bootimg-efi`` source plugin. By default, 3514 the files are 3515 installed under the same name as the source files. To change the 3516 installed name, separate it from the original name with a semi-colon 3517 (;). Source files need to be located in 3518 :term:`DEPLOY_DIR_IMAGE`. Here are two 3519 examples:: 3520 3521 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" 3522 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" 3523 3524 Alternatively, source files can be picked up using a glob pattern. In 3525 this case, the destination file must have the same name as the base 3526 name of the source file path. To install files into a directory 3527 within the target location, pass its name after a semi-colon (;). 3528 Here are two examples:: 3529 3530 IMAGE_EFI_BOOT_FILES = "boot/loader/*" 3531 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" 3532 3533 The first example 3534 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/`` 3535 into the root of the target partition. The second example installs 3536 the same files into a ``boot`` directory within the target partition. 3537 3538 You can find information on how to use the Wic tool in the 3539 ":ref:`dev-manual/wic:creating partitioned images using wic`" 3540 section of the Yocto Project Development Tasks Manual. Reference 3541 material for Wic is located in the 3542 ":doc:`/ref-manual/kickstart`" chapter. 3543 3544 :term:`IMAGE_FEATURES` 3545 The primary list of features to include in an image. Typically, you 3546 configure this variable in an image recipe. Although you can use this 3547 variable from your ``local.conf`` file, which is found in the 3548 :term:`Build Directory`, best practices dictate that you do 3549 not. 3550 3551 .. note:: 3552 3553 To enable extra features from outside the image recipe, use the 3554 :term:`EXTRA_IMAGE_FEATURES` variable. 3555 3556 For a list of image features that ships with the Yocto Project, see 3557 the ":ref:`ref-features-image`" section. 3558 3559 For an example that shows how to customize your image by using this 3560 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 3561 section in the Yocto Project Development Tasks Manual. 3562 3563 :term:`IMAGE_FSTYPES` 3564 Specifies the formats the OpenEmbedded build system uses during the 3565 build when creating the root filesystem. For example, setting 3566 :term:`IMAGE_FSTYPES` as follows causes the build system to create root 3567 filesystems using two formats: ``.ext3`` and ``.tar.bz2``:: 3568 3569 IMAGE_FSTYPES = "ext3 tar.bz2" 3570 3571 For the complete list of supported image formats from which you can 3572 choose, see :term:`IMAGE_TYPES`. 3573 3574 .. note:: 3575 3576 - If an image recipe uses the "inherit image" line and you are 3577 setting :term:`IMAGE_FSTYPES` inside the recipe, you must set 3578 :term:`IMAGE_FSTYPES` prior to using the "inherit image" line. 3579 3580 - Due to the way the OpenEmbedded build system processes this 3581 variable, you cannot update its contents by using ``:append`` 3582 or ``:prepend``. You must use the ``+=`` operator to add one or 3583 more options to the :term:`IMAGE_FSTYPES` variable. 3584 3585 :term:`IMAGE_INSTALL` 3586 Used by recipes to specify the packages to install into an image 3587 through the :ref:`ref-classes-image` class. Use the 3588 :term:`IMAGE_INSTALL` variable with care to avoid ordering issues. 3589 3590 Image recipes set :term:`IMAGE_INSTALL` to specify the packages to 3591 install into an image through :ref:`ref-classes-image`. Additionally, 3592 there are "helper" classes such as the :ref:`ref-classes-core-image` 3593 class which can take lists used with :term:`IMAGE_FEATURES` and turn 3594 them into auto-generated entries in :term:`IMAGE_INSTALL` in addition 3595 to its default contents. 3596 3597 When you use this variable, it is best to use it as follows:: 3598 3599 IMAGE_INSTALL:append = " package-name" 3600 3601 Be sure to include the space 3602 between the quotation character and the start of the package name or 3603 names. 3604 3605 .. note:: 3606 3607 - When working with a 3608 :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 3609 image, do not use the :term:`IMAGE_INSTALL` variable to specify 3610 packages for installation. Instead, use the 3611 :term:`PACKAGE_INSTALL` variable, which 3612 allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a 3613 fixed set of packages and not be affected by :term:`IMAGE_INSTALL`. 3614 For information on creating an :term:`Initramfs`, see the 3615 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" 3616 section in the Yocto Project Development Tasks Manual. 3617 3618 - Using :term:`IMAGE_INSTALL` with the 3619 :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` 3620 BitBake operator within the ``/conf/local.conf`` file or from 3621 within an image recipe is not recommended. Use of this operator in 3622 these ways can cause ordering issues. Since 3623 :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a 3624 default value using the 3625 :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` 3626 operator, using a ``+=`` operation against :term:`IMAGE_INSTALL` 3627 results in unexpected behavior when used within 3628 ``conf/local.conf``. Furthermore, the same operation from within an 3629 image recipe may or may not succeed depending on the specific 3630 situation. In both these cases, the behavior is contrary to how 3631 most users expect the ``+=`` operator to work. 3632 3633 :term:`IMAGE_LINGUAS` 3634 Specifies the list of locales to install into the image during the 3635 root filesystem construction process. The OpenEmbedded build system 3636 automatically splits locale files, which are used for localization, 3637 into separate packages. Setting the :term:`IMAGE_LINGUAS` variable 3638 ensures that any locale packages that correspond to packages already 3639 selected for installation into the image are also installed. Here is 3640 an example:: 3641 3642 IMAGE_LINGUAS = "pt-br de-de" 3643 3644 In this example, the build system ensures any Brazilian Portuguese 3645 and German locale files that correspond to packages in the image are 3646 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as 3647 ``*-locale-pt`` and ``*-locale-de``, since some software packages 3648 only provide locale files by language and not by country-specific 3649 language). 3650 3651 See the :term:`GLIBC_GENERATE_LOCALES` 3652 variable for information on generating GLIBC locales. 3653 3654 3655 :term:`IMAGE_LINK_NAME` 3656 The name of the output image symlink (which does not include 3657 the version part as :term:`IMAGE_NAME` does). The default value 3658 is derived using the :term:`IMAGE_BASENAME` and 3659 :term:`IMAGE_MACHINE_SUFFIX` variables:: 3660 3661 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}" 3662 3663 .. note:: 3664 3665 It is possible to set this to "" to disable symlink creation, 3666 however, you also need to set :term:`IMAGE_NAME` to still have 3667 a reasonable value e.g.:: 3668 3669 IMAGE_LINK_NAME = "" 3670 IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" 3671 3672 :term:`IMAGE_MACHINE_SUFFIX` 3673 Specifies the by default machine-specific suffix for image file names 3674 (before the extension). The default value is set as follows:: 3675 3676 IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}" 3677 3678 The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE` 3679 subdirectory, so you may find it unnecessary to also include this suffix 3680 in the name of every image file. If you prefer to remove the suffix you 3681 can set this variable to an empty string:: 3682 3683 IMAGE_MACHINE_SUFFIX = "" 3684 3685 (Not to be confused with :term:`IMAGE_NAME_SUFFIX`.) 3686 3687 :term:`IMAGE_MANIFEST` 3688 The manifest file for the image. This file lists all the installed 3689 packages that make up the image. The file contains package 3690 information on a line-per-package basis as follows:: 3691 3692 packagename packagearch version 3693 3694 The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest 3695 file as follows:: 3696 3697 IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest" 3698 3699 The location is 3700 derived using the :term:`IMGDEPLOYDIR` 3701 and :term:`IMAGE_NAME` variables. You can find 3702 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" 3703 section in the Yocto Project Overview and Concepts Manual. 3704 3705 :term:`IMAGE_NAME` 3706 The name of the output image files minus the extension. By default 3707 this variable is set using the :term:`IMAGE_LINK_NAME`, and 3708 :term:`IMAGE_VERSION_SUFFIX` variables:: 3709 3710 IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}" 3711 3712 :term:`IMAGE_NAME_SUFFIX` 3713 Suffix used for the image output filename --- defaults to ``".rootfs"`` 3714 to distinguish the image file from other files created during image 3715 building; however if this suffix is redundant or not desired you can 3716 clear the value of this variable (set the value to ""). For example, 3717 this is typically cleared in :term:`Initramfs` image recipes. 3718 3719 :term:`IMAGE_OVERHEAD_FACTOR` 3720 Defines a multiplier that the build system applies to the initial 3721 image size for cases when the multiplier times the returned disk 3722 usage value for the image is greater than the sum of 3723 :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of 3724 the multiplier applied to the initial image size creates free disk 3725 space in the image as overhead. By default, the build process uses a 3726 multiplier of 1.3 for this variable. This default value results in 3727 30% free disk space added to the image when this method is used to 3728 determine the final generated image size. You should be aware that 3729 post install scripts and the package management system uses disk 3730 space inside this overhead area. Consequently, the multiplier does 3731 not produce an image with all the theoretical free disk space. See 3732 :term:`IMAGE_ROOTFS_SIZE` for information on how the build system 3733 determines the overall image size. 3734 3735 The default 30% free disk space typically gives the image enough room 3736 to boot and allows for basic post installs while still leaving a 3737 small amount of free disk space. If 30% free space is inadequate, you 3738 can increase the default value. For example, the following setting 3739 gives you 50% free space added to the image:: 3740 3741 IMAGE_OVERHEAD_FACTOR = "1.5" 3742 3743 Alternatively, you can ensure a specific amount of free disk space is 3744 added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3745 variable. 3746 3747 :term:`IMAGE_PKGTYPE` 3748 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the 3749 OpenEmbedded build system. The variable is defined appropriately by 3750 the :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`, 3751 or :ref:`ref-classes-package_ipk` class. 3752 3753 The :ref:`ref-classes-populate-sdk-*` and :ref:`ref-classes-image` 3754 classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs. 3755 3756 You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the 3757 variable is set indirectly through the appropriate 3758 :ref:`package_* <ref-classes-package>` class using the 3759 :term:`PACKAGE_CLASSES` variable. The 3760 OpenEmbedded build system uses the first package type (e.g. DEB, RPM, 3761 or IPK) that appears with the variable 3762 3763 .. note:: 3764 3765 Files using the ``.tar`` format are never used as a substitute 3766 packaging format for DEB, RPM, and IPK formatted files for your image 3767 or SDK. 3768 3769 :term:`IMAGE_POSTPROCESS_COMMAND` 3770 Specifies a list of functions to call once the OpenEmbedded build 3771 system creates the final image output files. You can specify 3772 functions separated by semicolons:: 3773 3774 IMAGE_POSTPROCESS_COMMAND += "function; ... " 3775 3776 If you need to pass the root filesystem path to a command within the 3777 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3778 directory that becomes the root filesystem image. See the 3779 :term:`IMAGE_ROOTFS` variable for more 3780 information. 3781 3782 :term:`IMAGE_PREPROCESS_COMMAND` 3783 Specifies a list of functions to call before the OpenEmbedded build 3784 system creates the final image output files. You can specify 3785 functions separated by semicolons:: 3786 3787 IMAGE_PREPROCESS_COMMAND += "function; ... " 3788 3789 If you need to pass the root filesystem path to a command within the 3790 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3791 directory that becomes the root filesystem image. See the 3792 :term:`IMAGE_ROOTFS` variable for more 3793 information. 3794 3795 :term:`IMAGE_ROOTFS` 3796 The location of the root filesystem while it is under construction 3797 (i.e. during the :ref:`ref-tasks-rootfs` task). This 3798 variable is not configurable. Do not change it. 3799 3800 :term:`IMAGE_ROOTFS_ALIGNMENT` 3801 Specifies the alignment for the output image file in Kbytes. If the 3802 size of the image is not a multiple of this value, then the size is 3803 rounded up to the nearest multiple of the value. The default value is 3804 "1". See :term:`IMAGE_ROOTFS_SIZE` for 3805 additional information. 3806 3807 :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3808 Defines additional free disk space created in the image in Kbytes. By 3809 default, this variable is set to "0". This free disk space is added 3810 to the image after the build system determines the image size as 3811 described in :term:`IMAGE_ROOTFS_SIZE`. 3812 3813 This variable is particularly useful when you want to ensure that a 3814 specific amount of free disk space is available on a device after an 3815 image is installed and running. For example, to be sure 5 Gbytes of 3816 free disk space is available, set the variable as follows:: 3817 3818 IMAGE_ROOTFS_EXTRA_SPACE = "5242880" 3819 3820 For example, the Yocto Project Build Appliance specifically requests 3821 40 Gbytes of extra space with the line:: 3822 3823 IMAGE_ROOTFS_EXTRA_SPACE = "41943040" 3824 3825 :term:`IMAGE_ROOTFS_SIZE` 3826 Defines the size in Kbytes for the generated image. The OpenEmbedded 3827 build system determines the final size for the generated image using 3828 an algorithm that takes into account the initial disk space used for 3829 the generated image, a requested size for the image, and requested 3830 additional free disk space to be added to the image. Programatically, 3831 the build system determines the final size of the generated image as 3832 follows:: 3833 3834 if (image-du * overhead) < rootfs-size: 3835 internal-rootfs-size = rootfs-size + xspace 3836 else: 3837 internal-rootfs-size = (image-du * overhead) + xspace 3838 where: 3839 image-du = Returned value of the du command on the image. 3840 overhead = IMAGE_OVERHEAD_FACTOR 3841 rootfs-size = IMAGE_ROOTFS_SIZE 3842 internal-rootfs-size = Initial root filesystem size before any modifications. 3843 xspace = IMAGE_ROOTFS_EXTRA_SPACE 3844 3845 See the :term:`IMAGE_OVERHEAD_FACTOR` 3846 and :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3847 variables for related information. 3848 3849 :term:`IMAGE_TYPEDEP` 3850 Specifies a dependency from one image type on another. Here is an 3851 example from the :ref:`ref-classes-image-live` class:: 3852 3853 IMAGE_TYPEDEP:live = "ext3" 3854 3855 In the previous example, the variable ensures that when "live" is 3856 listed with the :term:`IMAGE_FSTYPES` variable, 3857 the OpenEmbedded build system produces an ``ext3`` image first since 3858 one of the components of the live image is an ``ext3`` formatted 3859 partition containing the root filesystem. 3860 3861 :term:`IMAGE_TYPES` 3862 Specifies the complete list of supported image types by default: 3863 3864 - btrfs 3865 - container 3866 - cpio 3867 - cpio.gz 3868 - cpio.lz4 3869 - cpio.lzma 3870 - cpio.xz 3871 - cramfs 3872 - erofs 3873 - erofs-lz4 3874 - erofs-lz4hc 3875 - ext2 3876 - ext2.bz2 3877 - ext2.gz 3878 - ext2.lzma 3879 - ext3 3880 - ext3.gz 3881 - ext4 3882 - ext4.gz 3883 - f2fs 3884 - hddimg 3885 - iso 3886 - jffs2 3887 - jffs2.sum 3888 - multiubi 3889 - squashfs 3890 - squashfs-lz4 3891 - squashfs-lzo 3892 - squashfs-xz 3893 - tar 3894 - tar.bz2 3895 - tar.gz 3896 - tar.lz4 3897 - tar.xz 3898 - tar.zst 3899 - ubi 3900 - ubifs 3901 - wic 3902 - wic.bz2 3903 - wic.gz 3904 - wic.lzma 3905 3906 For more information about these types of images, see 3907 ``meta/classes-recipe/image_types*.bbclass`` in the :term:`Source Directory`. 3908 3909 :term:`IMAGE_VERSION_SUFFIX` 3910 Version suffix that is part of the default :term:`IMAGE_NAME` and 3911 :term:`KERNEL_ARTIFACT_NAME` values. 3912 Defaults to ``"-${DATETIME}"``, however you could set this to a 3913 version string that comes from your external build environment if 3914 desired, and this suffix would then be used consistently across 3915 the build artifacts. 3916 3917 :term:`IMGDEPLOYDIR` 3918 When inheriting the :ref:`ref-classes-image` class directly or 3919 through the :ref:`ref-classes-core-image` class, the 3920 :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files 3921 that is set in the ``image`` class as follows:: 3922 3923 IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete" 3924 3925 Recipes inheriting the :ref:`ref-classes-image` class should copy 3926 files to be deployed into :term:`IMGDEPLOYDIR`, and the class will take 3927 care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards. 3928 3929 :term:`INCOMPATIBLE_LICENSE` 3930 Specifies a space-separated list of license names (as they would 3931 appear in :term:`LICENSE`) that should be excluded 3932 from the build (if set globally), or from an image (if set locally 3933 in an image recipe). 3934 3935 When the variable is set globally, recipes that provide no alternatives to listed 3936 incompatible licenses are not built. Packages that are individually 3937 licensed with the specified incompatible licenses will be deleted. 3938 Most of the time this does not allow a feasible build (because it becomes impossible 3939 to satisfy build time dependencies), so the recommended way to 3940 implement license restrictions is to set the variable in specific 3941 image recipes where the restrictions must apply. That way there 3942 are no build time restrictions, but the license check is still 3943 performed when the image's filesystem is assembled from packages. 3944 3945 There is some support for wildcards in this variable's value, 3946 however it is restricted to specific licenses. Currently only 3947 these wildcards are allowed and expand as follows: 3948 3949 - ``AGPL-3.0*"``: ``AGPL-3.0-only``, ``AGPL-3.0-or-later`` 3950 - ``GPL-3.0*``: ``GPL-3.0-only``, ``GPL-3.0-or-later`` 3951 - ``LGPL-3.0*``: ``LGPL-3.0-only``, ``LGPL-3.0-or-later`` 3952 3953 .. note:: 3954 3955 This functionality is only regularly tested using the following 3956 setting:: 3957 3958 INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*" 3959 3960 3961 Although you can use other settings, you might be required to 3962 remove dependencies on (or provide alternatives to) components that 3963 are required to produce a functional system image. 3964 3965 :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS` 3966 Specifies a space-separated list of package and license pairs that 3967 are allowed to be used even if the license is specified in 3968 :term:`INCOMPATIBLE_LICENSE`. The package and license pairs are 3969 separated using a colon. Example:: 3970 3971 INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only" 3972 3973 :term:`INHERIT` 3974 Causes the named class or classes to be inherited globally. Anonymous 3975 functions in the class or classes are not executed for the base 3976 configuration and in each individual recipe. The OpenEmbedded build 3977 system ignores changes to :term:`INHERIT` in individual recipes. 3978 Classes inherited using :term:`INHERIT` must be located in the 3979 ``classes-global/`` or ``classes/`` subdirectories. 3980 3981 For more information on :term:`INHERIT`, see the 3982 :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" 3983 section in the BitBake User Manual. 3984 3985 :term:`INHERIT_DISTRO` 3986 Lists classes that will be inherited at the distribution level. It is 3987 unlikely that you want to edit this variable. 3988 3989 Classes specified in :term:`INHERIT_DISTRO` must be located in the 3990 ``classes-global/`` or ``classes/`` subdirectories. 3991 3992 The default value of the variable is set as follows in the 3993 ``meta/conf/distro/defaultsetup.conf`` file:: 3994 3995 INHERIT_DISTRO ?= "debian devshell sstate license" 3996 3997 :term:`INHIBIT_DEFAULT_DEPS` 3998 Prevents the default dependencies, namely the C compiler and standard 3999 C library (libc), from being added to :term:`DEPENDS`. 4000 This variable is usually used within recipes that do not require any 4001 compilation using the C compiler. 4002 4003 Set the variable to "1" to prevent the default dependencies from 4004 being added. 4005 4006 :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` 4007 Prevents the OpenEmbedded build system from splitting out debug 4008 information during packaging. By default, the build system splits out 4009 debugging information during the 4010 :ref:`ref-tasks-package` task. For more information on 4011 how debug information is split out, see the 4012 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 4013 variable. 4014 4015 To prevent the build system from splitting out debug information 4016 during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as 4017 follows:: 4018 4019 INHIBIT_PACKAGE_DEBUG_SPLIT = "1" 4020 4021 :term:`INHIBIT_PACKAGE_STRIP` 4022 If set to "1", causes the build to not strip binaries in resulting 4023 packages and prevents the ``-dbg`` package from containing the source 4024 files. 4025 4026 By default, the OpenEmbedded build system strips binaries and puts 4027 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. 4028 Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you 4029 plan to debug in general. 4030 4031 :term:`INHIBIT_SYSROOT_STRIP` 4032 If set to "1", causes the build to not strip binaries in the 4033 resulting sysroot. 4034 4035 By default, the OpenEmbedded build system strips binaries in the 4036 resulting sysroot. When you specifically set the 4037 :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit 4038 this stripping. 4039 4040 If you want to use this variable, include the :ref:`ref-classes-staging` 4041 class. This class uses a ``sys_strip()`` function to test for the variable 4042 and acts accordingly. 4043 4044 .. note:: 4045 4046 Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and 4047 special circumstances. For example, suppose you are building 4048 bare-metal firmware by using an external GCC toolchain. Furthermore, 4049 even if the toolchain's binaries are strippable, there are other files 4050 needed for the build that are not strippable. 4051 4052 :term:`INIT_MANAGER` 4053 Specifies the system init manager to use. Available options are: 4054 4055 - ``sysvinit`` 4056 - ``systemd`` 4057 - ``mdev-busybox`` 4058 4059 With ``sysvinit``, the init manager is set to 4060 :wikipedia:`SysVinit <Init#SysV-style>`, the traditional UNIX init 4061 system. This is the default choice in the Poky distribution, together with 4062 the Udev device manager (see the ":ref:`device-manager`" section). 4063 4064 With ``systemd``, the init manager becomes :wikipedia:`systemd <Systemd>`, 4065 which comes with the :wikipedia:`udev <Udev>` device manager. 4066 4067 With ``mdev-busybox``, the init manager becomes the much simpler BusyBox 4068 init, together with the BusyBox mdev device manager. This is the simplest 4069 and lightest solution, and probably the best choice for low-end systems 4070 with a rather slow CPU and a limited amount of RAM. 4071 4072 More concretely, this is used to include 4073 ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global 4074 configuration. You can have a look at the 4075 :yocto_git:`meta/conf/distro/include/init-manager-*.inc </poky/tree/meta/conf/distro/include>` 4076 files for more information, and also the ":ref:`init-manager`" 4077 section in the Yocto Project Development Tasks Manual. 4078 4079 :term:`INITRAMFS_DEPLOY_DIR_IMAGE` 4080 Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs` 4081 where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is 4082 set by default to ``${DEPLOY_DIR_IMAGE}`` in the 4083 :ref:`ref-classes-kernel` class and it's only meant to be changed when 4084 building an :term:`Initramfs` image from a separate multiconfig via 4085 :term:`INITRAMFS_MULTICONFIG`. 4086 4087 :term:`INITRAMFS_FSTYPES` 4088 Defines the format for the output image of an initial RAM filesystem 4089 (:term:`Initramfs`), which is used during boot. Supported formats are the 4090 same as those supported by the 4091 :term:`IMAGE_FSTYPES` variable. 4092 4093 The default value of this variable, which is set in the 4094 ``meta/conf/bitbake.conf`` configuration file in the 4095 :term:`Source Directory`, is "cpio.gz". The Linux kernel's 4096 :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem 4097 :wikipedia:`initrd <Initrd>` mechanism, expects 4098 an optionally compressed cpio archive. 4099 4100 :term:`INITRAMFS_IMAGE` 4101 Specifies the :term:`PROVIDES` name of an image 4102 recipe that is used to build an initial RAM filesystem (:term:`Initramfs`) 4103 image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an 4104 additional recipe to be built as a dependency to whatever root 4105 filesystem recipe you might be using (e.g. ``core-image-sato``). The 4106 :term:`Initramfs` image recipe you provide should set 4107 :term:`IMAGE_FSTYPES` to 4108 :term:`INITRAMFS_FSTYPES`. 4109 4110 An :term:`Initramfs` image provides a temporary root filesystem used for 4111 early system initialization (e.g. loading of modules needed to locate 4112 and mount the "real" root filesystem). 4113 4114 .. note:: 4115 4116 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` 4117 recipe in the :term:`Source Directory` 4118 for an example :term:`Initramfs` recipe. To select this sample recipe as 4119 the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE` 4120 to "core-image-minimal-initramfs". 4121 4122 You can also find more information by referencing the 4123 ``meta-poky/conf/templates/default/local.conf.sample.extended`` 4124 configuration file in the Source Directory, the :ref:`ref-classes-image` 4125 class, and the :ref:`ref-classes-kernel` class to see how to use the 4126 :term:`INITRAMFS_IMAGE` variable. 4127 4128 If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no 4129 :term:`Initramfs` image is built. 4130 4131 For more information, you can also see the 4132 :term:`INITRAMFS_IMAGE_BUNDLE` 4133 variable, which allows the generated image to be bundled inside the 4134 kernel image. Additionally, for information on creating an :term:`Initramfs` 4135 image, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 4136 in the Yocto Project Development Tasks Manual. 4137 4138 :term:`INITRAMFS_IMAGE_BUNDLE` 4139 Controls whether or not the image recipe specified by 4140 :term:`INITRAMFS_IMAGE` is run through an 4141 extra pass 4142 (:ref:`ref-tasks-bundle_initramfs`) during 4143 kernel compilation in order to build a single binary that contains 4144 both the kernel image and the initial RAM filesystem (:term:`Initramfs`) 4145 image. This makes use of the 4146 :term:`CONFIG_INITRAMFS_SOURCE` kernel 4147 feature. 4148 4149 .. note:: 4150 4151 Bundling the :term:`Initramfs` with the kernel conflates the code in the 4152 :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 4153 compatible software may be part of a bundled :term:`Initramfs`. 4154 4155 .. note:: 4156 4157 Using an extra compilation pass to bundle the :term:`Initramfs` avoids a 4158 circular dependency between the kernel recipe and the :term:`Initramfs` 4159 recipe should the :term:`Initramfs` include kernel modules. Should that be 4160 the case, the :term:`Initramfs` recipe depends on the kernel for the 4161 kernel modules, and the kernel depends on the :term:`Initramfs` recipe 4162 since the :term:`Initramfs` is bundled inside the kernel image. 4163 4164 The combined binary is deposited into the ``tmp/deploy`` directory, 4165 which is part of the :term:`Build Directory`. 4166 4167 Setting the variable to "1" in a configuration file causes the 4168 OpenEmbedded build system to generate a kernel image with the 4169 :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within:: 4170 4171 INITRAMFS_IMAGE_BUNDLE = "1" 4172 4173 By default, the :ref:`ref-classes-kernel` class sets this variable to a 4174 null string as follows:: 4175 4176 INITRAMFS_IMAGE_BUNDLE ?= "" 4177 4178 .. note:: 4179 4180 You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a 4181 configuration file. You cannot set the variable in a recipe file. 4182 4183 See the 4184 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>` 4185 file for additional information. Also, for information on creating an 4186 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 4187 in the Yocto Project Development Tasks Manual. 4188 4189 :term:`INITRAMFS_IMAGE_NAME` 4190 4191 This value needs to stay in sync with :term:`IMAGE_LINK_NAME`, but with 4192 :term:`INITRAMFS_IMAGE` instead of :term:`IMAGE_BASENAME`. The default value 4193 is set as follows: 4194 4195 INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}" 4196 4197 That is, if :term:`INITRAMFS_IMAGE` is set, the value of 4198 :term:`INITRAMFS_IMAGE_NAME` will be set based upon 4199 :term:`INITRAMFS_IMAGE` and :term:`IMAGE_MACHINE_SUFFIX`. 4200 4201 4202 :term:`INITRAMFS_LINK_NAME` 4203 The link name of the initial RAM filesystem image. This variable is 4204 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4205 follows:: 4206 4207 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" 4208 4209 The value of the 4210 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4211 file, has the following value:: 4212 4213 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4214 4215 See the :term:`MACHINE` variable for additional 4216 information. 4217 4218 :term:`INITRAMFS_MULTICONFIG` 4219 Defines the multiconfig to create a multiconfig dependency to be used by 4220 the :ref:`ref-classes-kernel` class. 4221 4222 This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from 4223 a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`. 4224 4225 For more information on how to bundle an :term:`Initramfs` image from a separate 4226 multiconfig see the ":ref:`dev-manual/building:Bundling an Initramfs Image From a Separate Multiconfig`" 4227 section in the Yocto Project Development Tasks Manual. 4228 4229 :term:`INITRAMFS_NAME` 4230 The base name of the initial RAM filesystem image. This variable is 4231 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4232 follows:: 4233 4234 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" 4235 4236 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4237 4238 :term:`INITRD` 4239 Indicates list of filesystem images to concatenate and use as an 4240 initial RAM disk (``initrd``). 4241 4242 The :term:`INITRD` variable is an optional variable used with the 4243 :ref:`ref-classes-image-live` class. 4244 4245 :term:`INITRD_IMAGE` 4246 When building a "live" bootable image (i.e. when 4247 :term:`IMAGE_FSTYPES` contains "live"), 4248 :term:`INITRD_IMAGE` specifies the image recipe that should be built to 4249 provide the initial RAM disk image. The default value is 4250 "core-image-minimal-initramfs". 4251 4252 See the :ref:`ref-classes-image-live` class for more information. 4253 4254 :term:`INITSCRIPT_NAME` 4255 The filename of the initialization script as installed to 4256 ``${sysconfdir}/init.d``. 4257 4258 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. 4259 The variable is mandatory. 4260 4261 :term:`INITSCRIPT_PACKAGES` 4262 A list of the packages that contain initscripts. If multiple packages 4263 are specified, you need to append the package name to the other 4264 ``INITSCRIPT_*`` as an override. 4265 4266 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. 4267 The variable is optional and defaults to the :term:`PN` 4268 variable. 4269 4270 :term:`INITSCRIPT_PARAMS` 4271 Specifies the options to pass to ``update-rc.d``. Here is an example:: 4272 4273 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." 4274 4275 In this example, the script has a runlevel of 99, starts the script 4276 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. 4277 4278 The variable's default value is "defaults", which is set in the 4279 :ref:`ref-classes-update-rc.d` class. 4280 4281 The value in :term:`INITSCRIPT_PARAMS` is passed through to the 4282 ``update-rc.d`` command. For more information on valid parameters, 4283 please see the ``update-rc.d`` manual page at 4284 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html 4285 4286 :term:`INSANE_SKIP` 4287 Specifies the QA checks to skip for a specific package within a 4288 recipe. For example, to skip the check for symbolic link ``.so`` 4289 files in the main package of a recipe, add the following to the 4290 recipe. The package name override must be used, which in this example 4291 is ``${PN}``:: 4292 4293 INSANE_SKIP:${PN} += "dev-so" 4294 4295 See the ":ref:`ref-classes-insane`" section for a 4296 list of the valid QA checks you can specify using this variable. 4297 4298 :term:`INSTALL_TIMEZONE_FILE` 4299 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. 4300 Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the 4301 configuration level to disable this behavior. 4302 4303 :term:`IPK_FEED_URIS` 4304 When the IPK backend is in use and package management is enabled on 4305 the target, you can use this variable to set up ``opkg`` in the 4306 target image to point to package feeds on a nominated server. Once 4307 the feed is established, you can perform installations or upgrades 4308 using the package manager at runtime. 4309 4310 :term:`KARCH` 4311 Defines the kernel architecture used when assembling the 4312 configuration. Architectures supported for this release are: 4313 4314 - powerpc 4315 - i386 4316 - x86_64 4317 - arm 4318 - qemu 4319 - mips 4320 4321 You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. 4322 4323 :term:`KBRANCH` 4324 A regular expression used by the build process to explicitly identify 4325 the kernel branch that is validated, patched, and configured during a 4326 build. You must set this variable to ensure the exact kernel branch 4327 you want is being used by the build process. 4328 4329 Values for this variable are set in the kernel's recipe file and the 4330 kernel's append file. For example, if you are using the 4331 ``linux-yocto_4.12`` kernel, the kernel recipe file is the 4332 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH` 4333 is set as follows in that kernel recipe file:: 4334 4335 KBRANCH ?= "standard/base" 4336 4337 This variable is also used from the kernel's append file to identify 4338 the kernel branch specific to a particular machine or target 4339 hardware. Continuing with the previous kernel example, the kernel's 4340 append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the 4341 BSP layer for a given machine. For example, the append file for the 4342 Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA 4343 machines (``meta-yocto-bsp``) is named 4344 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. 4345 Here are the related statements from that append file:: 4346 4347 KBRANCH:genericx86 = "standard/base" 4348 KBRANCH:genericx86-64 = "standard/base" 4349 KBRANCH:edgerouter = "standard/edgerouter" 4350 KBRANCH:beaglebone = "standard/beaglebone" 4351 4352 The :term:`KBRANCH` statements 4353 identify the kernel branch to use when building for each supported 4354 BSP. 4355 4356 :term:`KBUILD_DEFCONFIG` 4357 When used with the :ref:`ref-classes-kernel-yocto` 4358 class, specifies an "in-tree" kernel configuration file for use 4359 during a kernel build. 4360 4361 Typically, when using a ``defconfig`` to configure a kernel during a 4362 build, you place the file in your layer in the same manner as you 4363 would place patch files and configuration fragment files (i.e. 4364 "out-of-tree"). However, if you want to use a ``defconfig`` file that 4365 is part of the kernel tree (i.e. "in-tree"), you can use the 4366 :term:`KBUILD_DEFCONFIG` variable and append the 4367 :term:`KMACHINE` variable to point to the 4368 ``defconfig`` file. 4369 4370 To use the variable, set it in the append file for your kernel recipe 4371 using the following form:: 4372 4373 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file" 4374 4375 Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses 4376 a ``defconfig`` file named "bcm2709_defconfig":: 4377 4378 KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig" 4379 4380 As an alternative, you can use the following within your append file:: 4381 4382 KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file" 4383 4384 For more 4385 information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the 4386 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" 4387 section in the Yocto Project Linux Kernel Development Manual. 4388 4389 :term:`KCONFIG_MODE` 4390 When used with the :ref:`ref-classes-kernel-yocto` 4391 class, specifies the kernel configuration values to use for options 4392 not specified in the provided ``defconfig`` file. Valid options are:: 4393 4394 KCONFIG_MODE = "alldefconfig" 4395 KCONFIG_MODE = "allnoconfig" 4396 4397 In ``alldefconfig`` mode the options not explicitly specified will be 4398 assigned their Kconfig default value. In ``allnoconfig`` mode the 4399 options not explicitly specified will be disabled in the kernel 4400 config. 4401 4402 In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where 4403 the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file 4404 will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed 4405 in ``${WORKDIR}`` through a meta-layer will be handled in 4406 ``allnoconfig`` mode. 4407 4408 An "in-tree" ``defconfig`` file can be selected via the 4409 :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to 4410 be explicitly set. 4411 4412 A ``defconfig`` file compatible with ``allnoconfig`` mode can be 4413 generated by copying the ``.config`` file from a working Linux kernel 4414 build, renaming it to ``defconfig`` and placing it into the Linux 4415 kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does 4416 not need to be explicitly set. 4417 4418 A ``defconfig`` file compatible with ``alldefconfig`` mode can be 4419 generated using the 4420 :ref:`ref-tasks-savedefconfig` 4421 task and placed into the Linux kernel ``${WORKDIR}`` through your 4422 meta-layer. Explicitely set :term:`KCONFIG_MODE`:: 4423 4424 KCONFIG_MODE = "alldefconfig" 4425 4426 :term:`KERNEL_ALT_IMAGETYPE` 4427 Specifies an alternate kernel image type for creation in addition to 4428 the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and 4429 :term:`KERNEL_IMAGETYPES` variables. 4430 4431 :term:`KERNEL_ARTIFACT_NAME` 4432 Specifies the name of all of the build artifacts. You can change the 4433 name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME` 4434 variable. 4435 4436 The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the 4437 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the 4438 following default value:: 4439 4440 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" 4441 4442 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`IMAGE_MACHINE_SUFFIX` 4443 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information. 4444 4445 :term:`KERNEL_CLASSES` 4446 A list of classes defining kernel image types that the 4447 :ref:`ref-classes-kernel` class should inherit. You typically 4448 append this variable to enable extended image types. An example is 4449 ":ref:`ref-classes-kernel-fitimage`", which enables 4450 FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``. 4451 You can register custom kernel image types with the 4452 :ref:`ref-classes-kernel` class using this variable. 4453 4454 :term:`KERNEL_DANGLING_FEATURES_WARN_ONLY` 4455 When kernel configuration fragments are missing for some 4456 :term:`KERNEL_FEATURES` specified by layers or BSPs, 4457 building and configuring the kernel stops with an error. 4458 4459 You can turn these errors into warnings by setting the 4460 following in ``conf/local.conf``:: 4461 4462 KERNEL_DANGLING_FEATURES_WARN_ONLY = "1" 4463 4464 You will still be warned that runtime issues may occur, 4465 but at least the kernel configuration and build process will 4466 be allowed to continue. 4467 4468 :term:`KERNEL_DEBUG_TIMESTAMPS` 4469 If set to "1", enables timestamping functionality during building 4470 the kernel. The default is "0" to disable this for reproducibility 4471 reasons. 4472 4473 :term:`KERNEL_DEPLOY_DEPEND` 4474 Provides a means of controlling the dependency of an image recipe 4475 on the kernel. The default value is "virtual/kernel:do_deploy", 4476 however for a small initramfs image or other images that do not 4477 need the kernel, this can be set to "" in the image recipe. 4478 4479 :term:`KERNEL_DEVICETREE` 4480 Specifies the name of the generated Linux kernel device tree (i.e. 4481 the ``.dtb``) file. 4482 4483 .. note:: 4484 4485 There is legacy support for specifying the full path to the device 4486 tree. However, providing just the ``.dtb`` file is preferred. 4487 4488 In order to use this variable, the :ref:`ref-classes-kernel-devicetree` 4489 class must be inherited. 4490 4491 :term:`KERNEL_DEVICETREE_BUNDLE` 4492 When set to "1", this variable allows to bundle the Linux kernel 4493 and the Device Tree Binary together in a single file. 4494 4495 This feature is currently only supported on the "arm" (32 bit) 4496 architecture. 4497 4498 This variable is set to "0" by default by the 4499 :ref:`ref-classes-kernel-devicetree` class. 4500 4501 :term:`KERNEL_DTB_LINK_NAME` 4502 The link name of the kernel device tree binary (DTB). This variable 4503 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4504 follows:: 4505 4506 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4507 4508 The 4509 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in 4510 the same file, has the following value:: 4511 4512 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4513 4514 See the :term:`MACHINE` variable for additional 4515 information. 4516 4517 :term:`KERNEL_DTB_NAME` 4518 The base name of the kernel device tree binary (DTB). This variable 4519 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4520 follows:: 4521 4522 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4523 4524 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4525 4526 :term:`KERNEL_DTBDEST` 4527 This variable, used by the :ref:`ref-classes-kernel-devicetree` 4528 class, allows to change the installation directory of the DTB 4529 (Device Tree Binary) files. 4530 4531 It is set by default to "${KERNEL_IMAGEDEST}" by the 4532 :ref:`ref-classes-kernel` class. 4533 4534 :term:`KERNEL_DTBVENDORED` 4535 This variable, used by the :ref:`ref-classes-kernel-devicetree`, 4536 allows to ignore vendor subdirectories when installing DTB 4537 (Device Tree Binary) files, when it is set to "false". 4538 4539 To keep vendor subdirectories, set this variable to "true". 4540 4541 It is set by default to "false" by the :ref:`ref-classes-kernel` class. 4542 4543 :term:`KERNEL_DTC_FLAGS` 4544 Specifies the ``dtc`` flags that are passed to the Linux kernel build 4545 system when generating the device trees (via ``DTC_FLAGS`` environment 4546 variable). 4547 4548 In order to use this variable, the :ref:`ref-classes-kernel-devicetree` 4549 class must be inherited. 4550 4551 :term:`KERNEL_EXTRA_ARGS` 4552 Specifies additional ``make`` command-line arguments the OpenEmbedded 4553 build system passes on when compiling the kernel. 4554 4555 :term:`KERNEL_FEATURES` 4556 Includes additional kernel metadata. In the OpenEmbedded build 4557 system, the default Board Support Packages (BSPs) 4558 :term:`Metadata` is provided through the 4559 :term:`KMACHINE` and :term:`KBRANCH` 4560 variables. You can use the :term:`KERNEL_FEATURES` variable from within 4561 the kernel recipe or kernel append file to further add metadata for 4562 all BSPs or specific BSPs. 4563 4564 The metadata you add through this variable includes config fragments 4565 and features descriptions, which usually includes patches as well as 4566 config fragments. You typically override the :term:`KERNEL_FEATURES` 4567 variable for a specific machine. In this way, you can provide 4568 validated, but optional, sets of kernel configurations and features. 4569 4570 For example, the following example from the ``linux-yocto-rt_4.12`` 4571 kernel recipe adds "netfilter" and "taskstats" features to all BSPs 4572 as well as "virtio" configurations to all QEMU machines. The last two 4573 statements add specific configurations to targeted machine types:: 4574 4575 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" 4576 KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" 4577 KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc" 4578 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" 4579 KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc" 4580 4581 :term:`KERNEL_FIT_LINK_NAME` 4582 The link name of the kernel flattened image tree (FIT) image. This 4583 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` 4584 file as follows:: 4585 4586 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4587 4588 The value of the 4589 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4590 file, has the following value:: 4591 4592 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4593 4594 See the :term:`MACHINE` variable for additional 4595 information. 4596 4597 :term:`KERNEL_FIT_NAME` 4598 The base name of the kernel flattened image tree (FIT) image. This 4599 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` 4600 file as follows:: 4601 4602 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4603 4604 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4605 4606 :term:`KERNEL_IMAGE_LINK_NAME` 4607 The link name for the kernel image. This variable is set in the 4608 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 4609 4610 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4611 4612 The value of 4613 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4614 file, has the following value:: 4615 4616 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4617 4618 See the :term:`MACHINE` variable for additional 4619 information. 4620 4621 :term:`KERNEL_IMAGE_MAXSIZE` 4622 Specifies the maximum size of the kernel image file in kilobytes. If 4623 :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is 4624 checked against the set value during the 4625 :ref:`ref-tasks-sizecheck` task. The task fails if 4626 the kernel image file is larger than the setting. 4627 4628 :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a 4629 limited amount of space in which the kernel image must be stored. 4630 4631 By default, this variable is not set, which means the size of the 4632 kernel image is not checked. 4633 4634 :term:`KERNEL_IMAGE_NAME` 4635 The base name of the kernel image. This variable is set in the 4636 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 4637 4638 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4639 4640 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4641 4642 :term:`KERNEL_IMAGETYPE` 4643 The type of kernel to build for a device, usually set by the machine 4644 configuration files and defaults to "zImage". This variable is used 4645 when building the kernel and is passed to ``make`` as the target to 4646 build. 4647 4648 To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`. 4649 4650 :term:`KERNEL_IMAGETYPES` 4651 Lists additional types of kernel images to build for a device in addition 4652 to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the 4653 machine configuration files. 4654 4655 :term:`KERNEL_MODULE_AUTOLOAD` 4656 Lists kernel modules that need to be auto-loaded during boot. 4657 4658 .. note:: 4659 4660 This variable replaces the deprecated :term:`module_autoload` 4661 variable. 4662 4663 You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it 4664 can be recognized by the kernel recipe or by an out-of-tree kernel 4665 module recipe (e.g. a machine configuration file, a distribution 4666 configuration file, an append file for the recipe, or the recipe 4667 itself). 4668 4669 Specify it as follows:: 4670 4671 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" 4672 4673 Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build 4674 system to populate the ``/etc/modules-load.d/modname.conf`` file with 4675 the list of modules to be auto-loaded on boot. The modules appear 4676 one-per-line in the file. Here is an example of the most common use 4677 case:: 4678 4679 KERNEL_MODULE_AUTOLOAD += "module_name" 4680 4681 For information on how to populate the ``modname.conf`` file with 4682 ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable. 4683 4684 :term:`KERNEL_MODULE_PROBECONF` 4685 Provides a list of modules for which the OpenEmbedded build system 4686 expects to find ``module_conf_``\ modname values that specify 4687 configuration for each of the modules. For information on how to 4688 provide those module configurations, see the 4689 :term:`module_conf_* <module_conf>` variable. 4690 4691 :term:`KERNEL_PACKAGE_NAME` 4692 Specifies the base name of the kernel packages, such as "kernel" 4693 in the kernel packages such as "kernel-modules", "kernel-image" and 4694 "kernel-dbg". 4695 4696 The default value for this variable is set to "kernel" by the 4697 :ref:`ref-classes-kernel` class. 4698 4699 :term:`KERNEL_PATH` 4700 The location of the kernel sources. This variable is set to the value 4701 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` 4702 class. For information on how this variable is used, see the 4703 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4704 section in the Yocto Project Linux Kernel Development Manual. 4705 4706 To help maximize compatibility with out-of-tree drivers used to build 4707 modules, the OpenEmbedded build system also recognizes and uses the 4708 :term:`KERNEL_SRC` variable, which is identical to 4709 the :term:`KERNEL_PATH` variable. Both variables are common variables 4710 used by external Makefiles to point to the kernel source directory. 4711 4712 :term:`KERNEL_SRC` 4713 The location of the kernel sources. This variable is set to the value 4714 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` 4715 class. For information on how this variable is used, see the 4716 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4717 section in the Yocto Project Linux Kernel Development Manual. 4718 4719 To help maximize compatibility with out-of-tree drivers used to build 4720 modules, the OpenEmbedded build system also recognizes and uses the 4721 :term:`KERNEL_PATH` variable, which is identical 4722 to the :term:`KERNEL_SRC` variable. Both variables are common variables 4723 used by external Makefiles to point to the kernel source directory. 4724 4725 :term:`KERNEL_VERSION` 4726 Specifies the version of the kernel as extracted from ``version.h`` 4727 or ``utsrelease.h`` within the kernel sources. Effects of setting 4728 this variable do not take effect until the kernel has been 4729 configured. Consequently, attempting to refer to this variable in 4730 contexts prior to configuration will not work. 4731 4732 :term:`KERNELDEPMODDEPEND` 4733 Specifies whether the data referenced through 4734 :term:`PKGDATA_DIR` is needed or not. 4735 :term:`KERNELDEPMODDEPEND` does not control whether or not that data 4736 exists, but simply whether or not it is used. If you do not need to 4737 use the data, set the :term:`KERNELDEPMODDEPEND` variable in your 4738 :term:`Initramfs` recipe. Setting the variable there when the data is not 4739 needed avoids a potential dependency loop. 4740 4741 :term:`KFEATURE_DESCRIPTION` 4742 Provides a short description of a configuration fragment. You use 4743 this variable in the ``.scc`` file that describes a configuration 4744 fragment file. Here is the variable used in a file named ``smp.scc`` 4745 to describe SMP being enabled:: 4746 4747 define KFEATURE_DESCRIPTION "Enable SMP" 4748 4749 :term:`KMACHINE` 4750 The machine as known by the kernel. Sometimes the machine name used 4751 by the kernel does not match the machine name used by the 4752 OpenEmbedded build system. For example, the machine name that the 4753 OpenEmbedded build system understands as ``core2-32-intel-common`` 4754 goes by a different name in the Linux Yocto kernel. The kernel 4755 understands that machine as ``intel-core2-32``. For cases like these, 4756 the :term:`KMACHINE` variable maps the kernel machine name to the 4757 OpenEmbedded build system machine name. 4758 4759 These mappings between different names occur in the Yocto Linux 4760 Kernel's ``meta`` branch. As an example take a look in the 4761 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:: 4762 4763 LINUX_VERSION:core2-32-intel-common = "3.19.0" 4764 COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}" 4765 SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" 4766 SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" 4767 KMACHINE:core2-32-intel-common = "intel-core2-32" 4768 KBRANCH:core2-32-intel-common = "standard/base" 4769 KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}" 4770 4771 The :term:`KMACHINE` statement says 4772 that the kernel understands the machine name as "intel-core2-32". 4773 However, the OpenEmbedded build system understands the machine as 4774 "core2-32-intel-common". 4775 4776 :term:`KTYPE` 4777 Defines the kernel type to be used in assembling the configuration. 4778 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 4779 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" 4780 section in the 4781 Yocto Project Linux Kernel Development Manual for more information on 4782 kernel types. 4783 4784 You define the :term:`KTYPE` variable in the 4785 :ref:`kernel-dev/advanced:bsp descriptions`. The 4786 value you use must match the value used for the 4787 :term:`LINUX_KERNEL_TYPE` value used by the 4788 kernel recipe. 4789 4790 :term:`LABELS` 4791 Provides a list of targets for automatic configuration. 4792 4793 See the :ref:`ref-classes-grub-efi` class for more 4794 information on how this variable is used. 4795 4796 :term:`LAYERDEPENDS` 4797 Lists the layers, separated by spaces, on which this recipe depends. 4798 Optionally, you can specify a specific layer version for a dependency 4799 by adding it to the end of the layer name. Here is an example:: 4800 4801 LAYERDEPENDS_mylayer = "anotherlayer (=3)" 4802 4803 In this previous example, 4804 version 3 of "anotherlayer" is compared against 4805 :term:`LAYERVERSION`\ ``_anotherlayer``. 4806 4807 An error is produced if any dependency is missing or the version 4808 numbers (if specified) do not match exactly. This variable is used in 4809 the ``conf/layer.conf`` file and must be suffixed with the name of 4810 the specific layer (e.g. ``LAYERDEPENDS_mylayer``). 4811 4812 :term:`LAYERDIR` 4813 When used inside the ``layer.conf`` configuration file, this variable 4814 provides the path of the current layer. This variable is not 4815 available outside of ``layer.conf`` and references are expanded 4816 immediately when parsing of the file completes. 4817 4818 :term:`LAYERDIR_RE` 4819 See :term:`bitbake:LAYERDIR_RE` in the BitBake manual. 4820 4821 :term:`LAYERRECOMMENDS` 4822 Lists the layers, separated by spaces, recommended for use with this 4823 layer. 4824 4825 Optionally, you can specify a specific layer version for a 4826 recommendation by adding the version to the end of the layer name. 4827 Here is an example:: 4828 4829 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" 4830 4831 In this previous example, version 3 of "anotherlayer" is compared 4832 against ``LAYERVERSION_anotherlayer``. 4833 4834 This variable is used in the ``conf/layer.conf`` file and must be 4835 suffixed with the name of the specific layer (e.g. 4836 ``LAYERRECOMMENDS_mylayer``). 4837 4838 :term:`LAYERSERIES_COMPAT` 4839 See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual. 4840 4841 :term:`LAYERVERSION` 4842 Optionally specifies the version of a layer as a single number. You 4843 can use this within :term:`LAYERDEPENDS` for 4844 another layer in order to depend on a specific version of the layer. 4845 This variable is used in the ``conf/layer.conf`` file and must be 4846 suffixed with the name of the specific layer (e.g. 4847 ``LAYERVERSION_mylayer``). 4848 4849 :term:`LD` 4850 The minimal command and arguments used to run the linker. 4851 4852 :term:`LDFLAGS` 4853 Specifies the flags to pass to the linker. This variable is exported 4854 to an environment variable and thus made visible to the software 4855 being built during the compilation step. 4856 4857 Default initialization for :term:`LDFLAGS` varies depending on what is 4858 being built: 4859 4860 - :term:`TARGET_LDFLAGS` when building for the 4861 target 4862 4863 - :term:`BUILD_LDFLAGS` when building for the 4864 build host (i.e. ``-native``) 4865 4866 - :term:`BUILDSDK_LDFLAGS` when building for 4867 an SDK (i.e. ``nativesdk-``) 4868 4869 :term:`LEAD_SONAME` 4870 Specifies the lead (or primary) compiled library file (i.e. ``.so``) 4871 that the :ref:`ref-classes-debian` class applies its 4872 naming policy to given a recipe that packages multiple libraries. 4873 4874 This variable works in conjunction with the :ref:`ref-classes-debian` 4875 class. 4876 4877 :term:`LIC_FILES_CHKSUM` 4878 Checksums of the license text in the recipe source code. 4879 4880 This variable tracks changes in license text of the source code 4881 files. If the license text is changed, it will trigger a build 4882 failure, which gives the developer an opportunity to review any 4883 license change. 4884 4885 This variable must be defined for all recipes (unless 4886 :term:`LICENSE` is set to "CLOSED"). 4887 4888 For more information, see the ":ref:`dev-manual/licenses:tracking license changes`" 4889 section in the Yocto Project Development Tasks Manual. 4890 4891 :term:`LICENSE` 4892 The list of source licenses for the recipe. Follow these rules: 4893 4894 - Do not use spaces within individual license names. 4895 4896 - Separate license names using \| (pipe) when there is a choice 4897 between licenses. 4898 4899 - Separate license names using & (ampersand) when there are 4900 multiple licenses for different parts of the source. 4901 4902 - You can use spaces between license names. 4903 4904 - For standard licenses, use the names of the files in 4905 ``meta/files/common-licenses/`` or the 4906 :term:`SPDXLICENSEMAP` flag names defined in 4907 ``meta/conf/licenses.conf``. 4908 4909 Here are some examples:: 4910 4911 LICENSE = "LGPL-2.1-only | GPL-3.0-only" 4912 LICENSE = "MPL-1.0 & LGPL-2.1-only" 4913 LICENSE = "GPL-2.0-or-later" 4914 4915 The first example is from the 4916 recipes for Qt, which the user may choose to distribute under either 4917 the LGPL version 2.1 or GPL version 3. The second example is from 4918 Cairo where two licenses cover different parts of the source code. 4919 The final example is from ``sysstat``, which presents a single 4920 license. 4921 4922 You can also specify licenses on a per-package basis to handle 4923 situations where components of the output have different licenses. 4924 For example, a piece of software whose code is licensed under GPLv2 4925 but has accompanying documentation licensed under the GNU Free 4926 Documentation License 1.2 could be specified as follows:: 4927 4928 LICENSE = "GFDL-1.2 & GPL-2.0-only" 4929 LICENSE:${PN} = "GPL-2.0.only" 4930 LICENSE:${PN}-doc = "GFDL-1.2" 4931 4932 :term:`LICENSE_CREATE_PACKAGE` 4933 Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded 4934 build system to create an extra package (i.e. 4935 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add 4936 those packages to the 4937 :term:`RRECOMMENDS`\ ``:${PN}``. 4938 4939 The ``${PN}-lic`` package installs a directory in 4940 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base 4941 name, and installs files in that directory that contain license and 4942 copyright information (i.e. copies of the appropriate license files 4943 from ``meta/common-licenses`` that match the licenses specified in 4944 the :term:`LICENSE` variable of the recipe metadata 4945 and copies of files marked in 4946 :term:`LIC_FILES_CHKSUM` as containing 4947 license text). 4948 4949 For related information on providing license text, see the 4950 :term:`COPY_LIC_DIRS` variable, the 4951 :term:`COPY_LIC_MANIFEST` variable, and the 4952 ":ref:`dev-manual/licenses:providing license text`" 4953 section in the Yocto Project Development Tasks Manual. 4954 4955 :term:`LICENSE_FLAGS` 4956 Specifies additional flags for a recipe you must allow through 4957 :term:`LICENSE_FLAGS_ACCEPTED` in 4958 order for the recipe to be built. When providing multiple flags, 4959 separate them with spaces. 4960 4961 This value is independent of :term:`LICENSE` and is 4962 typically used to mark recipes that might require additional licenses 4963 in order to be used in a commercial product. For more information, 4964 see the 4965 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" 4966 section in the Yocto Project Development Tasks Manual. 4967 4968 :term:`LICENSE_FLAGS_ACCEPTED` 4969 Lists license flags that when specified in 4970 :term:`LICENSE_FLAGS` within a recipe should not 4971 prevent that recipe from being built. For more information, see the 4972 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" 4973 section in the Yocto Project Development Tasks Manual. 4974 4975 :term:`LICENSE_PATH` 4976 Path to additional licenses used during the build. By default, the 4977 OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the 4978 directory that holds common license text used during the build. The 4979 :term:`LICENSE_PATH` variable allows you to extend that location to other 4980 areas that have additional licenses:: 4981 4982 LICENSE_PATH += "path-to-additional-common-licenses" 4983 4984 :term:`LINUX_KERNEL_TYPE` 4985 Defines the kernel type to be used in assembling the configuration. 4986 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 4987 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" 4988 section in the 4989 Yocto Project Linux Kernel Development Manual for more information on 4990 kernel types. 4991 4992 If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to 4993 "standard". Together with :term:`KMACHINE`, the 4994 :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by 4995 the kernel tools to find the appropriate description within the 4996 kernel :term:`Metadata` with which to build out the sources 4997 and configuration. 4998 4999 :term:`LINUX_VERSION` 5000 The Linux version from ``kernel.org`` on which the Linux kernel image 5001 being built using the OpenEmbedded build system is based. You define 5002 this variable in the kernel recipe. For example, the 5003 ``linux-yocto-3.4.bb`` kernel recipe found in 5004 ``meta/recipes-kernel/linux`` defines the variables as follows:: 5005 5006 LINUX_VERSION ?= "3.4.24" 5007 5008 The :term:`LINUX_VERSION` variable is used to define :term:`PV` 5009 for the recipe:: 5010 5011 PV = "${LINUX_VERSION}+git${SRCPV}" 5012 5013 :term:`LINUX_VERSION_EXTENSION` 5014 A string extension compiled into the version string of the Linux 5015 kernel built with the OpenEmbedded build system. You define this 5016 variable in the kernel recipe. For example, the linux-yocto kernel 5017 recipes all define the variable as follows:: 5018 5019 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" 5020 5021 Defining this variable essentially sets the Linux kernel 5022 configuration item ``CONFIG_LOCALVERSION``, which is visible through 5023 the ``uname`` command. Here is an example that shows the extension 5024 assuming it was set as previously shown:: 5025 5026 $ uname -r 5027 3.7.0-rc8-custom 5028 5029 :term:`LOG_DIR` 5030 Specifies the directory to which the OpenEmbedded build system writes 5031 overall log files. The default directory is ``${TMPDIR}/log``. 5032 5033 For the directory containing logs specific to each task, see the 5034 :term:`T` variable. 5035 5036 :term:`MACHINE` 5037 Specifies the target device for which the image is built. You define 5038 :term:`MACHINE` in the ``local.conf`` file found in the 5039 :term:`Build Directory`. By default, :term:`MACHINE` is set to 5040 "qemux86", which is an x86-based architecture machine to be emulated 5041 using QEMU:: 5042 5043 MACHINE ?= "qemux86" 5044 5045 The variable corresponds to a machine configuration file of the same 5046 name, through which machine-specific configurations are set. Thus, 5047 when :term:`MACHINE` is set to "qemux86", the corresponding 5048 ``qemux86.conf`` machine configuration file can be found in 5049 the :term:`Source Directory` in 5050 ``meta/conf/machine``. 5051 5052 The list of machines supported by the Yocto Project as shipped 5053 include the following:: 5054 5055 MACHINE ?= "qemuarm" 5056 MACHINE ?= "qemuarm64" 5057 MACHINE ?= "qemumips" 5058 MACHINE ?= "qemumips64" 5059 MACHINE ?= "qemuppc" 5060 MACHINE ?= "qemux86" 5061 MACHINE ?= "qemux86-64" 5062 MACHINE ?= "genericx86" 5063 MACHINE ?= "genericx86-64" 5064 MACHINE ?= "beaglebone" 5065 MACHINE ?= "edgerouter" 5066 5067 The last five are Yocto Project reference hardware 5068 boards, which are provided in the ``meta-yocto-bsp`` layer. 5069 5070 .. note:: 5071 5072 Adding additional Board Support Package (BSP) layers to your 5073 configuration adds new possible settings for :term:`MACHINE`. 5074 5075 :term:`MACHINE_ARCH` 5076 Specifies the name of the machine-specific architecture. This 5077 variable is set automatically from :term:`MACHINE` or 5078 :term:`TUNE_PKGARCH`. You should not hand-edit 5079 the :term:`MACHINE_ARCH` variable. 5080 5081 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 5082 A list of required machine-specific packages to install as part of 5083 the image being built. The build process depends on these packages 5084 being present. Furthermore, because this is a "machine-essential" 5085 variable, the list of packages are essential for the machine to boot. 5086 The impact of this variable affects images based on 5087 ``packagegroup-core-boot``, including the ``core-image-minimal`` 5088 image. 5089 5090 This variable is similar to the 5091 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception 5092 that the image being built has a build dependency on the variable's 5093 list of packages. In other words, the image will not build if a file 5094 in this list is not found. 5095 5096 As an example, suppose the machine for which you are building 5097 requires ``example-init`` to be run during boot to initialize the 5098 hardware. In this case, you would use the following in the machine's 5099 ``.conf`` configuration file:: 5100 5101 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" 5102 5103 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` 5104 A list of recommended machine-specific packages to install as part of 5105 the image being built. The build process does not depend on these 5106 packages being present. However, because this is a 5107 "machine-essential" variable, the list of packages are essential for 5108 the machine to boot. The impact of this variable affects images based 5109 on ``packagegroup-core-boot``, including the ``core-image-minimal`` 5110 image. 5111 5112 This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 5113 variable with the exception that the image being built does not have 5114 a build dependency on the variable's list of packages. In other 5115 words, the image will still build if a package in this list is not 5116 found. Typically, this variable is used to handle essential kernel 5117 modules, whose functionality may be selected to be built into the 5118 kernel rather than as a module, in which case a package will not be 5119 produced. 5120 5121 Consider an example where you have a custom kernel where a specific 5122 touchscreen driver is required for the machine to be usable. However, 5123 the driver can be built as a module or into the kernel depending on 5124 the kernel configuration. If the driver is built as a module, you 5125 want it to be installed. But, when the driver is built into the 5126 kernel, you still want the build to succeed. This variable sets up a 5127 "recommends" relationship so that in the latter case, the build will 5128 not fail due to the missing package. To accomplish this, assuming the 5129 package for the module was called ``kernel-module-ab123``, you would 5130 use the following in the machine's ``.conf`` configuration file:: 5131 5132 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" 5133 5134 .. note:: 5135 5136 In this example, the ``kernel-module-ab123`` recipe needs to 5137 explicitly set its :term:`PACKAGES` variable to ensure that BitBake 5138 does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to 5139 satisfy the dependency. 5140 5141 Some examples of these machine essentials are flash, screen, 5142 keyboard, mouse, or touchscreen drivers (depending on the machine). 5143 5144 :term:`MACHINE_EXTRA_RDEPENDS` 5145 A list of machine-specific packages to install as part of the image 5146 being built that are not essential for the machine to boot. However, 5147 the build process for more fully-featured images depends on the 5148 packages being present. 5149 5150 This variable affects all images based on ``packagegroup-base``, 5151 which does not include the ``core-image-minimal`` or 5152 ``core-image-full-cmdline`` images. 5153 5154 The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable 5155 with the exception that the image being built has a build dependency 5156 on the variable's list of packages. In other words, the image will 5157 not build if a file in this list is not found. 5158 5159 An example is a machine that has WiFi capability but is not essential 5160 for the machine to boot the image. However, if you are building a 5161 more fully-featured image, you want to enable the WiFi. The package 5162 containing the firmware for the WiFi hardware is always expected to 5163 exist, so it is acceptable for the build process to depend upon 5164 finding the package. In this case, assuming the package for the 5165 firmware was called ``wifidriver-firmware``, you would use the 5166 following in the ``.conf`` file for the machine:: 5167 5168 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" 5169 5170 :term:`MACHINE_EXTRA_RRECOMMENDS` 5171 A list of machine-specific packages to install as part of the image 5172 being built that are not essential for booting the machine. The image 5173 being built has no build dependency on this list of packages. 5174 5175 This variable affects only images based on ``packagegroup-base``, 5176 which does not include the ``core-image-minimal`` or 5177 ``core-image-full-cmdline`` images. 5178 5179 This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable 5180 with the exception that the image being built does not have a build 5181 dependency on the variable's list of packages. In other words, the 5182 image will build if a file in this list is not found. 5183 5184 An example is a machine that has WiFi capability but is not essential 5185 For the machine to boot the image. However, if you are building a 5186 more fully-featured image, you want to enable WiFi. In this case, the 5187 package containing the WiFi kernel module will not be produced if the 5188 WiFi driver is built into the kernel, in which case you still want 5189 the build to succeed instead of failing as a result of the package 5190 not being found. To accomplish this, assuming the package for the 5191 module was called ``kernel-module-examplewifi``, you would use the 5192 following in the ``.conf`` file for the machine:: 5193 5194 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" 5195 5196 :term:`MACHINE_FEATURES` 5197 Specifies the list of hardware features the 5198 :term:`MACHINE` is capable of supporting. For related 5199 information on enabling features, see the 5200 :term:`DISTRO_FEATURES`, 5201 :term:`COMBINED_FEATURES`, and 5202 :term:`IMAGE_FEATURES` variables. 5203 5204 For a list of hardware features supported by the Yocto Project as 5205 shipped, see the ":ref:`ref-features-machine`" section. 5206 5207 :term:`MACHINE_FEATURES_BACKFILL` 5208 A list of space-separated features to be added to 5209 :term:`MACHINE_FEATURES` if not also present in 5210 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. 5211 5212 This variable is set in the ``meta/conf/bitbake.conf`` file. It is not 5213 intended to be user-configurable. It is best to just reference the 5214 variable to see which machine features are being 5215 :ref:`backfilled <ref-features-backfill>` for all machine configurations. 5216 5217 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` 5218 A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL` 5219 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added 5220 to :term:`MACHINE_FEATURES`) during the build. 5221 5222 This corresponds to an opt-out mechanism. When new default machine 5223 features are introduced, machine definition maintainers can review 5224 (`consider`) them and decide to exclude them from the 5225 :ref:`backfilled <ref-features-backfill>` features. Therefore, the 5226 combination of :term:`MACHINE_FEATURES_BACKFILL` and 5227 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to 5228 add new default features without breaking existing machine definitions. 5229 5230 :term:`MACHINEOVERRIDES` 5231 A colon-separated list of overrides that apply to the current 5232 machine. By default, this list includes the value of 5233 :term:`MACHINE`. 5234 5235 You can extend :term:`MACHINEOVERRIDES` to add extra overrides that 5236 should apply to a machine. For example, all machines emulated in QEMU 5237 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named 5238 ``meta/conf/machine/include/qemu.inc`` that prepends the following 5239 override to :term:`MACHINEOVERRIDES`:: 5240 5241 MACHINEOVERRIDES =. "qemuall:" 5242 5243 This 5244 override allows variables to be overridden for all machines emulated 5245 in QEMU, like in the following example from the ``connman-conf`` 5246 recipe:: 5247 5248 SRC_URI:append:qemuall = " file://wired.config \ 5249 file://wired-setup \ 5250 " 5251 5252 The underlying mechanism behind 5253 :term:`MACHINEOVERRIDES` is simply that it is included in the default 5254 value of :term:`OVERRIDES`. 5255 5256 :term:`MAINTAINER` 5257 The email address of the distribution maintainer. 5258 5259 :term:`MESON_BUILDTYPE` 5260 Value of the Meson ``--buildtype`` argument used by the 5261 :ref:`ref-classes-meson` class. It defaults to ``debug`` if 5262 :term:`DEBUG_BUILD` is set to "1", and ``plain`` otherwise. 5263 5264 See `Meson build options <https://mesonbuild.com/Builtin-options.html>`__ 5265 for the values you could set in a recipe. Values such as ``plain``, 5266 ``debug``, ``debugoptimized``, ``release`` and ``minsize`` allow 5267 you to specify the inclusion of debugging symbols and the compiler 5268 optimizations (none, performance or size). 5269 5270 :term:`METADATA_BRANCH` 5271 The branch currently checked out for the OpenEmbedded-Core layer (path 5272 determined by :term:`COREBASE`). 5273 5274 :term:`METADATA_REVISION` 5275 The revision currently checked out for the OpenEmbedded-Core layer (path 5276 determined by :term:`COREBASE`). 5277 5278 :term:`MIME_XDG_PACKAGES` 5279 The current implementation of the :ref:`ref-classes-mime-xdg` 5280 class cannot detect ``.desktop`` files installed through absolute 5281 symbolic links. Use this setting to make the class create post-install 5282 and post-remove scripts for these packages anyway, to invoke the 5283 ``update-destop-database`` command. 5284 5285 :term:`MIRRORS` 5286 Specifies additional paths from which the OpenEmbedded build system 5287 gets source code. When the build system searches for source code, it 5288 first tries the local download directory. If that location fails, the 5289 build system tries locations defined by 5290 :term:`PREMIRRORS`, the upstream source, and then 5291 locations specified by :term:`MIRRORS` in that order. 5292 5293 Assuming your distribution (:term:`DISTRO`) is "poky", 5294 the default value for :term:`MIRRORS` is defined in the 5295 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. 5296 5297 :term:`MLPREFIX` 5298 Specifies a prefix has been added to :term:`PN` to create a 5299 special version of a recipe or package (i.e. a Multilib version). The 5300 variable is used in places where the prefix needs to be added to or 5301 removed from a name (e.g. the :term:`BPN` variable). 5302 :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`. 5303 5304 .. note:: 5305 5306 The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation 5307 is historical and comes from a time when ":ref:`ref-classes-nativesdk`" 5308 was a suffix rather than a prefix on the recipe name. When 5309 ":ref:`ref-classes-nativesdk`" was turned into a prefix, it made sense 5310 to set :term:`MLPREFIX` for it as well. 5311 5312 To help understand when :term:`MLPREFIX` might be needed, consider when 5313 :term:`BBCLASSEXTEND` is used to provide a :ref:`ref-classes-nativesdk` 5314 version of a recipe in addition to the target version. If that recipe 5315 declares build-time dependencies on tasks in other recipes by using 5316 :term:`DEPENDS`, then a dependency on "foo" will automatically get 5317 rewritten to a dependency on "nativesdk-foo". However, dependencies like 5318 the following will not get rewritten automatically:: 5319 5320 do_foo[depends] += "recipe:do_foo" 5321 5322 If you want such a dependency to also get transformed, you can do the 5323 following:: 5324 5325 do_foo[depends] += "${MLPREFIX}recipe:do_foo" 5326 5327 :term:`module_autoload` 5328 This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD` 5329 variable. You should replace all occurrences of :term:`module_autoload` 5330 with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example:: 5331 5332 module_autoload_rfcomm = "rfcomm" 5333 5334 should now be replaced with:: 5335 5336 KERNEL_MODULE_AUTOLOAD += "rfcomm" 5337 5338 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. 5339 5340 :term:`module_conf` 5341 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__ 5342 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` 5343 file. 5344 5345 You can use this variable anywhere that it can be recognized by the 5346 kernel recipe or out-of-tree kernel module recipe (e.g. a machine 5347 configuration file, a distribution configuration file, an append file 5348 for the recipe, or the recipe itself). If you use this variable, you 5349 must also be sure to list the module name in the 5350 :term:`KERNEL_MODULE_PROBECONF` 5351 variable. 5352 5353 Here is the general syntax:: 5354 5355 module_conf_module_name = "modprobe.d-syntax" 5356 5357 You must use the kernel module name override. 5358 5359 Run ``man modprobe.d`` in the shell to find out more information on 5360 the exact syntax you want to provide with :term:`module_conf`. 5361 5362 Including :term:`module_conf` causes the OpenEmbedded build system to 5363 populate the ``/etc/modprobe.d/modname.conf`` file with 5364 ``modprobe.d`` syntax lines. Here is an example that adds the options 5365 ``arg1`` and ``arg2`` to a module named ``mymodule``:: 5366 5367 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" 5368 5369 For information on how to specify kernel modules to auto-load on 5370 boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable. 5371 5372 :term:`MODULE_TARBALL_DEPLOY` 5373 Controls creation of the ``modules-*.tgz`` file. Set this variable to 5374 "0" to disable creation of this file, which contains all of the 5375 kernel modules resulting from a kernel build. 5376 5377 :term:`MODULE_TARBALL_LINK_NAME` 5378 The link name of the kernel module tarball. This variable is set in 5379 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 5380 5381 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 5382 5383 The value 5384 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the 5385 same file, has the following value:: 5386 5387 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 5388 5389 See the :term:`MACHINE` variable for additional information. 5390 5391 :term:`MODULE_TARBALL_NAME` 5392 The base name of the kernel module tarball. This variable is set in 5393 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 5394 5395 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" 5396 5397 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 5398 5399 :term:`MOUNT_BASE` 5400 On non-systemd systems (where ``udev-extraconf`` is being used), 5401 specifies the base directory for auto-mounting filesystems. The 5402 default value is "/run/media". 5403 5404 :term:`MULTIMACH_TARGET_SYS` 5405 Uniquely identifies the type of the target system for which packages 5406 are being built. This variable allows output for different types of 5407 target systems to be put into different subdirectories of the same 5408 output directory. 5409 5410 The default value of this variable is:: 5411 5412 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} 5413 5414 Some classes (e.g. :ref:`ref-classes-cross-canadian`) modify the 5415 :term:`MULTIMACH_TARGET_SYS` value. 5416 5417 See the :term:`STAMP` variable for an example. See the 5418 :term:`STAGING_DIR_TARGET` variable for more information. 5419 5420 :term:`NATIVELSBSTRING` 5421 A string identifying the host distribution. Strings consist of the 5422 host distributor ID followed by the release, as reported by the 5423 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For 5424 example, when running a build on Ubuntu 12.10, the value is 5425 "Ubuntu-12.10". If this information is unable to be determined, the 5426 value resolves to "Unknown". 5427 5428 This variable is used by default to isolate native shared state 5429 packages for different distributions (e.g. to avoid problems with 5430 ``glibc`` version incompatibilities). Additionally, the variable is 5431 checked against 5432 :term:`SANITY_TESTED_DISTROS` if that 5433 variable is set. 5434 5435 :term:`NM` 5436 The minimal command and arguments to run ``nm``. 5437 5438 :term:`NO_GENERIC_LICENSE` 5439 Avoids QA errors when you use a non-common, non-CLOSED license in a 5440 recipe. There are packages, such as the linux-firmware package, with many 5441 licenses that are not in any way common. Also, new licenses are added 5442 occasionally to avoid introducing a lot of common license files, 5443 which are only applicable to a specific package. 5444 :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does 5445 not exist in common licenses. 5446 5447 The following example shows how to add :term:`NO_GENERIC_LICENSE` to a 5448 recipe:: 5449 5450 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" 5451 5452 Here is an example that 5453 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched 5454 source:: 5455 5456 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" 5457 5458 :term:`NO_RECOMMENDATIONS` 5459 Prevents installation of all "recommended-only" packages. 5460 Recommended-only packages are packages installed only through the 5461 :term:`RRECOMMENDS` variable). Setting the 5462 :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on:: 5463 5464 NO_RECOMMENDATIONS = "1" 5465 5466 You can set this variable globally in your ``local.conf`` file or you 5467 can attach it to a specific image recipe by using the recipe name 5468 override:: 5469 5470 NO_RECOMMENDATIONS:pn-target_image = "1" 5471 5472 It is important to realize that if you choose to not install packages 5473 using this variable and some other packages are dependent on them 5474 (i.e. listed in a recipe's :term:`RDEPENDS` 5475 variable), the OpenEmbedded build system ignores your request and 5476 will install the packages to avoid dependency errors. 5477 5478 .. note:: 5479 5480 Some recommended packages might be required for certain system 5481 functionality, such as kernel modules. It is up to you to add 5482 packages with the :term:`IMAGE_INSTALL` variable. 5483 5484 This variable is only supported when using the IPK and RPM 5485 packaging backends. DEB is not supported. 5486 5487 See the :term:`BAD_RECOMMENDATIONS` and 5488 the :term:`PACKAGE_EXCLUDE` variables for 5489 related information. 5490 5491 :term:`NOAUTOPACKAGEDEBUG` 5492 Disables auto package from splitting ``.debug`` files. If a recipe 5493 requires ``FILES:${PN}-dbg`` to be set manually, the 5494 :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the 5495 content of the debug package. For example:: 5496 5497 NOAUTOPACKAGEDEBUG = "1" 5498 FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" 5499 FILES:${PN}-dbg = "/usr/src/debug/" 5500 FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" 5501 5502 :term:`NON_MULTILIB_RECIPES` 5503 A list of recipes that should not be built for multilib. OE-Core's 5504 ``multilib.conf`` file defines a reasonable starting point for this 5505 list with:: 5506 5507 NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot" 5508 5509 :term:`OBJCOPY` 5510 The minimal command and arguments to run ``objcopy``. 5511 5512 :term:`OBJDUMP` 5513 The minimal command and arguments to run ``objdump``. 5514 5515 :term:`OE_BINCONFIG_EXTRA_MANGLE` 5516 When inheriting the :ref:`ref-classes-binconfig` class, 5517 this variable specifies additional arguments passed to the "sed" 5518 command. The sed command alters any paths in configuration scripts 5519 that have been set up during compilation. Inheriting this class 5520 results in all paths in these scripts being changed to point into the 5521 ``sysroots/`` directory so that all builds that use the script will 5522 use the correct directories for the cross compiling layout. 5523 5524 See the ``meta/classes-recipe/binconfig.bbclass`` in the 5525 :term:`Source Directory` for details on how this class 5526 applies these additional sed command arguments. 5527 5528 :term:`OECMAKE_GENERATOR` 5529 A variable for the :ref:`ref-classes-cmake` class, allowing to choose 5530 which back-end will be generated by CMake to build an application. 5531 5532 By default, this variable is set to ``Ninja``, which is faster than GNU 5533 make, but if building is broken with Ninja, a recipe can use this 5534 variable to use GNU make instead:: 5535 5536 OECMAKE_GENERATOR = "Unix Makefiles" 5537 5538 :term:`OE_IMPORTS` 5539 An internal variable used to tell the OpenEmbedded build system what 5540 Python modules to import for every Python function run by the system. 5541 5542 .. note:: 5543 5544 Do not set this variable. It is for internal use only. 5545 5546 :term:`OE_INIT_ENV_SCRIPT` 5547 The name of the build environment setup script for the purposes of 5548 setting up the environment within the extensible SDK. The default 5549 value is "oe-init-build-env". 5550 5551 If you use a custom script to set up your build environment, set the 5552 :term:`OE_INIT_ENV_SCRIPT` variable to its name. 5553 5554 :term:`OE_TERMINAL` 5555 Controls how the OpenEmbedded build system spawns interactive 5556 terminals on the host development system (e.g. using the BitBake 5557 command with the ``-c devshell`` command-line option). For more 5558 information, see the ":ref:`dev-manual/development-shell:using a development shell`" section in 5559 the Yocto Project Development Tasks Manual. 5560 5561 You can use the following values for the :term:`OE_TERMINAL` variable: 5562 5563 - auto 5564 - gnome 5565 - xfce 5566 - rxvt 5567 - screen 5568 - konsole 5569 - none 5570 5571 :term:`OEROOT` 5572 The directory from which the top-level build environment setup script 5573 is sourced. The Yocto Project provides a top-level build environment 5574 setup script: :ref:`structure-core-script`. When you run this 5575 script, the :term:`OEROOT` variable resolves to the directory that 5576 contains the script. 5577 5578 For additional information on how this variable is used, see the 5579 initialization script. 5580 5581 :term:`OEQA_REPRODUCIBLE_TEST_TARGET` 5582 Set build target for build reproducibility testing. By default 5583 all available recipes are compiled with "bitbake world", see also :term:`EXCLUDE_FROM_WORLD` 5584 and :doc:`/test-manual/reproducible-builds`. 5585 5586 :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS` 5587 Set build targets which can be rebuilt using :ref:`shared state <overview-manual/concepts:shared state cache>` 5588 when running build reproducibility tests. See :doc:`/test-manual/reproducible-builds`. 5589 5590 :term:`OLDEST_KERNEL` 5591 Declares the oldest version of the Linux kernel that the produced 5592 binaries must support. This variable is passed into the build of the 5593 Embedded GNU C Library (``glibc``). 5594 5595 The default for this variable comes from the 5596 ``meta/conf/bitbake.conf`` configuration file. You can override this 5597 default by setting the variable in a custom distribution 5598 configuration file. 5599 5600 :term:`OVERLAYFS_ETC_DEVICE` 5601 When the :ref:`ref-classes-overlayfs-etc` class is 5602 inherited, specifies the device to be mounted for the read/write 5603 layer of ``/etc``. There is no default, so you must set this if you 5604 wish to enable :ref:`ref-classes-overlayfs-etc`, for 5605 example, assuming ``/dev/mmcblk0p2`` was the desired device:: 5606 5607 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2" 5608 5609 :term:`OVERLAYFS_ETC_EXPOSE_LOWER` 5610 When the :ref:`ref-classes-overlayfs-etc` class is 5611 inherited, if set to "1" then a read-only access to the original 5612 ``/etc`` content will be provided as a ``lower/`` subdirectory of 5613 :term:`OVERLAYFS_ETC_MOUNT_POINT`. The default value is "0". 5614 5615 :term:`OVERLAYFS_ETC_FSTYPE` 5616 When the :ref:`ref-classes-overlayfs-etc` class is 5617 inherited, specifies the file system type for the read/write 5618 layer of ``/etc``. There is no default, so you must set this if you 5619 wish to enable :ref:`ref-classes-overlayfs-etc`, 5620 for example, assuming the file system is ext4:: 5621 5622 OVERLAYFS_ETC_FSTYPE = "ext4" 5623 5624 :term:`OVERLAYFS_ETC_MOUNT_OPTIONS` 5625 When the :ref:`ref-classes-overlayfs-etc` class is 5626 inherited, specifies the mount options for the read-write layer. 5627 The default value is "defaults". 5628 5629 :term:`OVERLAYFS_ETC_MOUNT_POINT` 5630 When the :ref:`ref-classes-overlayfs-etc` class is 5631 inherited, specifies the parent mount path for the filesystem layers. 5632 There is no default, so you must set this if you wish to enable 5633 :ref:`ref-classes-overlayfs-etc`, for example if the desired path is 5634 "/data":: 5635 5636 OVERLAYFS_ETC_MOUNT_POINT = "/data" 5637 5638 :term:`OVERLAYFS_ETC_USE_ORIG_INIT_NAME` 5639 When the :ref:`ref-classes-overlayfs-etc` class is inherited, controls 5640 how the generated init will be named. For more information, see the 5641 :ref:`ref-classes-overlayfs-etc` class documentation. The default value 5642 is "1". 5643 5644 :term:`OVERLAYFS_MOUNT_POINT` 5645 When inheriting the :ref:`ref-classes-overlayfs` class, 5646 specifies mount point(s) to be used. For example:: 5647 5648 OVERLAYFS_MOUNT_POINT[data] = "/data" 5649 5650 The assumes you have a ``data.mount`` systemd unit defined elsewhere in 5651 your BSP (e.g. in ``systemd-machine-units`` recipe) and it is installed 5652 into the image. For more information see :ref:`ref-classes-overlayfs`. 5653 5654 .. note:: 5655 5656 Although the :ref:`ref-classes-overlayfs` class is 5657 inherited by individual recipes, :term:`OVERLAYFS_MOUNT_POINT` 5658 should be set in your machine configuration. 5659 5660 :term:`OVERLAYFS_QA_SKIP` 5661 When inheriting the :ref:`ref-classes-overlayfs` class, 5662 provides the ability to disable QA checks for particular overlayfs 5663 mounts. For example:: 5664 5665 OVERLAYFS_QA_SKIP[data] = "mount-configured" 5666 5667 .. note:: 5668 5669 Although the :ref:`ref-classes-overlayfs` class is 5670 inherited by individual recipes, :term:`OVERLAYFS_QA_SKIP` 5671 should be set in your machine configuration. 5672 5673 :term:`OVERLAYFS_WRITABLE_PATHS` 5674 When inheriting the :ref:`ref-classes-overlayfs` class, 5675 specifies writable paths used at runtime for the recipe. For 5676 example:: 5677 5678 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" 5679 5680 :term:`OVERRIDES` 5681 A colon-separated list of overrides that currently apply. Overrides 5682 are a BitBake mechanism that allows variables to be selectively 5683 overridden at the end of parsing. The set of overrides in 5684 :term:`OVERRIDES` represents the "state" during building, which includes 5685 the current recipe being built, the machine for which it is being 5686 built, and so forth. 5687 5688 As an example, if the string "an-override" appears as an element in 5689 the colon-separated list in :term:`OVERRIDES`, then the following 5690 assignment will override ``FOO`` with the value "overridden" at the 5691 end of parsing:: 5692 5693 FOO:an-override = "overridden" 5694 5695 See the 5696 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 5697 section in the BitBake User Manual for more information on the 5698 overrides mechanism. 5699 5700 The default value of :term:`OVERRIDES` includes the values of the 5701 :term:`CLASSOVERRIDE`, 5702 :term:`MACHINEOVERRIDES`, and 5703 :term:`DISTROOVERRIDES` variables. Another 5704 important override included by default is ``pn-${PN}``. This override 5705 allows variables to be set for a single recipe within configuration 5706 (``.conf``) files. Here is an example:: 5707 5708 FOO:pn-myrecipe = "myrecipe-specific value" 5709 5710 .. note:: 5711 5712 An easy way to see what overrides apply is to search for :term:`OVERRIDES` 5713 in the output of the ``bitbake -e`` command. See the 5714 ":ref:`dev-manual/debugging:viewing variable values`" section in the Yocto 5715 Project Development Tasks Manual for more information. 5716 5717 :term:`P` 5718 The recipe name and version. :term:`P` is comprised of the following:: 5719 5720 ${PN}-${PV} 5721 5722 :term:`P4DIR` 5723 See :term:`bitbake:P4DIR` in the BitBake manual. 5724 5725 :term:`PACKAGE_ADD_METADATA` 5726 This variable defines additional metadata to add to packages. 5727 5728 You may find you need to inject additional metadata into packages. 5729 This variable allows you to do that by setting the injected data as 5730 the value. Multiple fields can be added by splitting the content with 5731 the literal separator "\n". 5732 5733 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable 5734 to do package type specific settings. It can also be made package 5735 specific by using the package name as a suffix. 5736 5737 You can find out more about applying this variable in the 5738 ":ref:`dev-manual/packages:adding custom metadata to packages`" 5739 section in the Yocto Project Development Tasks Manual. 5740 5741 :term:`PACKAGE_ARCH` 5742 The architecture of the resulting package or packages. 5743 5744 By default, the value of this variable is set to 5745 :term:`TUNE_PKGARCH` when building for the 5746 target, :term:`BUILD_ARCH` when building for the 5747 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the 5748 SDK. 5749 5750 .. note:: 5751 5752 See :term:`SDK_ARCH` for more information. 5753 5754 However, if your recipe's output packages are built specific to the 5755 target machine rather than generally for the architecture of the 5756 machine, you should set :term:`PACKAGE_ARCH` to the value of 5757 :term:`MACHINE_ARCH` in the recipe as follows:: 5758 5759 PACKAGE_ARCH = "${MACHINE_ARCH}" 5760 5761 :term:`PACKAGE_ARCHS` 5762 Specifies a list of architectures compatible with the target machine. 5763 This variable is set automatically and should not normally be 5764 hand-edited. Entries are separated using spaces and listed in order 5765 of priority. The default value for :term:`PACKAGE_ARCHS` is "all any 5766 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". 5767 5768 :term:`PACKAGE_BEFORE_PN` 5769 Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so 5770 that those added packages can pick up files that would normally be 5771 included in the default package. 5772 5773 :term:`PACKAGE_CLASSES` 5774 This variable, which is set in the ``local.conf`` configuration file 5775 found in the ``conf`` folder of the 5776 :term:`Build Directory`, specifies the package manager the 5777 OpenEmbedded build system uses when packaging data. 5778 5779 You can provide one or more of the following arguments for the 5780 variable:: 5781 5782 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" 5783 5784 The build system uses only the first argument in the list as the 5785 package manager when creating your image or SDK. However, packages 5786 will be created using any additional packaging classes you specify. 5787 For example, if you use the following in your ``local.conf`` file:: 5788 5789 PACKAGE_CLASSES ?= "package_ipk" 5790 5791 The OpenEmbedded build system uses 5792 the IPK package manager to create your image or SDK. 5793 5794 For information on packaging and build performance effects as a 5795 result of the package manager in use, see the 5796 ":ref:`ref-classes-package`" section. 5797 5798 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 5799 Determines how to split up and package debug and source information 5800 when creating debugging packages to be used with the GNU Project 5801 Debugger (GDB). In general, based on the value of this variable, 5802 you can combine the source and debug info in a single package, 5803 you can break out the source into a separate package that can be 5804 installed independently, or you can choose to not have the source 5805 packaged at all. 5806 5807 The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable: 5808 5809 - "``.debug``": All debugging and source info is placed in a single 5810 ``*-dbg`` package; debug symbol files are placed next to the 5811 binary in a ``.debug`` directory so that, if a binary is installed 5812 into ``/bin``, the corresponding debug symbol file is installed 5813 in ``/bin/.debug``. Source files are installed in the same ``*-dbg`` 5814 package under ``/usr/src/debug``. 5815 5816 - "``debug-file-directory``": As above, all debugging and source info 5817 is placed in a single ``*-dbg`` package; debug symbol files are 5818 placed entirely under the directory ``/usr/lib/debug`` and separated 5819 by the path from where the binary is installed, so that if a binary 5820 is installed in ``/bin``, the corresponding debug symbols are installed 5821 in ``/usr/lib/debug/bin``, and so on. As above, source is installed 5822 in the same package under ``/usr/src/debug``. 5823 5824 - "``debug-with-srcpkg``": Debugging info is placed in the standard 5825 ``*-dbg`` package as with the ``.debug`` value, while source is 5826 placed in a separate ``*-src`` package, which can be installed 5827 independently. This is the default setting for this variable, 5828 as defined in Poky's ``bitbake.conf`` file. 5829 5830 - "``debug-without-src``": The same behavior as with the ``.debug`` 5831 setting, but no source is packaged at all. 5832 5833 .. note:: 5834 5835 Much of the above package splitting can be overridden via 5836 use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable. 5837 5838 You can find out more about debugging using GDB by reading the 5839 ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section 5840 in the Yocto Project Development Tasks Manual. 5841 5842 :term:`PACKAGE_EXCLUDE` 5843 Lists packages that should not be installed into an image. For 5844 example:: 5845 5846 PACKAGE_EXCLUDE = "package_name package_name package_name ..." 5847 5848 You can set this variable globally in your ``local.conf`` file or you 5849 can attach it to a specific image recipe by using the recipe name 5850 override:: 5851 5852 PACKAGE_EXCLUDE:pn-target_image = "package_name" 5853 5854 If you choose to not install a package using this variable and some 5855 other package is dependent on it (i.e. listed in a recipe's 5856 :term:`RDEPENDS` variable), the OpenEmbedded build 5857 system generates a fatal installation error. Because the build system 5858 halts the process with a fatal error, you can use the variable with 5859 an iterative development process to remove specific components from a 5860 system. 5861 5862 This variable is supported only when using the IPK and RPM 5863 packaging backends. DEB is not supported. 5864 5865 See the :term:`NO_RECOMMENDATIONS` and the 5866 :term:`BAD_RECOMMENDATIONS` variables for 5867 related information. 5868 5869 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` 5870 Prevents specific packages from being installed when you are 5871 installing complementary packages. 5872 5873 You might find that you want to prevent installing certain packages 5874 when you are installing complementary packages. For example, if you 5875 are using :term:`IMAGE_FEATURES` to install 5876 ``dev-pkgs``, you might not want to install all packages from a 5877 particular multilib. If you find yourself in this situation, you can 5878 use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular 5879 expressions to match the packages you want to exclude. 5880 5881 :term:`PACKAGE_EXTRA_ARCHS` 5882 Specifies the list of architectures compatible with the device CPU. 5883 This variable is useful when you build for several different devices 5884 that use miscellaneous processors such as XScale and ARM926-EJS. 5885 5886 :term:`PACKAGE_FEED_ARCHS` 5887 Optionally specifies the package architectures used as part of the 5888 package feed URIs during the build. When used, the 5889 :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed 5890 URI, which is constructed using the 5891 :term:`PACKAGE_FEED_URIS` and 5892 :term:`PACKAGE_FEED_BASE_PATHS` 5893 variables. 5894 5895 .. note:: 5896 5897 You can use the :term:`PACKAGE_FEED_ARCHS` 5898 variable to allow specific package architectures. If you do 5899 not need to allow specific architectures, which is a common 5900 case, you can omit this variable. Omitting the variable results in 5901 all available architectures for the current machine being included 5902 into remote package feeds. 5903 5904 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 5905 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 5906 defined in your ``local.conf`` file:: 5907 5908 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 5909 https://example.com/packagerepos/updates" 5910 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 5911 PACKAGE_FEED_ARCHS = "all core2-64" 5912 5913 Given these settings, the resulting package feeds are as follows: 5914 5915 .. code-block:: none 5916 5917 https://example.com/packagerepos/release/rpm/all 5918 https://example.com/packagerepos/release/rpm/core2-64 5919 https://example.com/packagerepos/release/rpm-dev/all 5920 https://example.com/packagerepos/release/rpm-dev/core2-64 5921 https://example.com/packagerepos/updates/rpm/all 5922 https://example.com/packagerepos/updates/rpm/core2-64 5923 https://example.com/packagerepos/updates/rpm-dev/all 5924 https://example.com/packagerepos/updates/rpm-dev/core2-64 5925 5926 :term:`PACKAGE_FEED_BASE_PATHS` 5927 Specifies the base path used when constructing package feed URIs. The 5928 :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a 5929 package feed URI used by the OpenEmbedded build system. The base path 5930 lies between the :term:`PACKAGE_FEED_URIS` 5931 and :term:`PACKAGE_FEED_ARCHS` variables. 5932 5933 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 5934 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 5935 defined in your ``local.conf`` file:: 5936 5937 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 5938 https://example.com/packagerepos/updates" 5939 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 5940 PACKAGE_FEED_ARCHS = "all core2-64" 5941 5942 Given these settings, the resulting package feeds are as follows: 5943 5944 .. code-block:: none 5945 5946 https://example.com/packagerepos/release/rpm/all 5947 https://example.com/packagerepos/release/rpm/core2-64 5948 https://example.com/packagerepos/release/rpm-dev/all 5949 https://example.com/packagerepos/release/rpm-dev/core2-64 5950 https://example.com/packagerepos/updates/rpm/all 5951 https://example.com/packagerepos/updates/rpm/core2-64 5952 https://example.com/packagerepos/updates/rpm-dev/all 5953 https://example.com/packagerepos/updates/rpm-dev/core2-64 5954 5955 :term:`PACKAGE_FEED_URIS` 5956 Specifies the front portion of the package feed URI used by the 5957 OpenEmbedded build system. Each final package feed URI is comprised 5958 of :term:`PACKAGE_FEED_URIS`, 5959 :term:`PACKAGE_FEED_BASE_PATHS`, and 5960 :term:`PACKAGE_FEED_ARCHS` variables. 5961 5962 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 5963 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 5964 defined in your ``local.conf`` file:: 5965 5966 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 5967 https://example.com/packagerepos/updates" 5968 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 5969 PACKAGE_FEED_ARCHS = "all core2-64" 5970 5971 Given these settings, the resulting package feeds are as follows: 5972 5973 .. code-block:: none 5974 5975 https://example.com/packagerepos/release/rpm/all 5976 https://example.com/packagerepos/release/rpm/core2-64 5977 https://example.com/packagerepos/release/rpm-dev/all 5978 https://example.com/packagerepos/release/rpm-dev/core2-64 5979 https://example.com/packagerepos/updates/rpm/all 5980 https://example.com/packagerepos/updates/rpm/core2-64 5981 https://example.com/packagerepos/updates/rpm-dev/all 5982 https://example.com/packagerepos/updates/rpm-dev/core2-64 5983 5984 :term:`PACKAGE_INSTALL` 5985 The final list of packages passed to the package manager for 5986 installation into the image. 5987 5988 Because the package manager controls actual installation of all 5989 packages, the list of packages passed using :term:`PACKAGE_INSTALL` is 5990 not the final list of packages that are actually installed. This 5991 variable is internal to the image construction code. Consequently, in 5992 general, you should use the 5993 :term:`IMAGE_INSTALL` variable to specify 5994 packages for installation. The exception to this is when working with 5995 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 5996 image. When working with an initial RAM filesystem (:term:`Initramfs`) image, 5997 use the :term:`PACKAGE_INSTALL` variable. For information on creating an 5998 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 5999 in the Yocto Project Development Tasks Manual. 6000 6001 :term:`PACKAGE_INSTALL_ATTEMPTONLY` 6002 Specifies a list of packages the OpenEmbedded build system attempts 6003 to install when creating an image. If a listed package fails to 6004 install, the build system does not generate an error. This variable 6005 is generally not user-defined. 6006 6007 :term:`PACKAGE_PREPROCESS_FUNCS` 6008 Specifies a list of functions run to pre-process the 6009 :term:`PKGD` directory prior to splitting the files out 6010 to individual packages. 6011 6012 :term:`PACKAGE_WRITE_DEPS` 6013 Specifies a list of dependencies for post-installation and 6014 pre-installation scripts on native/cross tools. If your 6015 post-installation or pre-installation script can execute at root filesystem 6016 creation time rather than on the target but depends on a native tool 6017 in order to execute, you need to list the tools in 6018 :term:`PACKAGE_WRITE_DEPS`. 6019 6020 For information on running post-installation scripts, see the 6021 ":ref:`dev-manual/new-recipe:post-installation scripts`" 6022 section in the Yocto Project Development Tasks Manual. 6023 6024 :term:`PACKAGECONFIG` 6025 This variable provides a means of enabling or disabling features of a 6026 recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in 6027 recipes when you specify features and then arguments that define 6028 feature behaviors. Here is the basic block structure (broken over 6029 multiple lines for readability):: 6030 6031 PACKAGECONFIG ??= "f1 f2 f3 ..." 6032 PACKAGECONFIG[f1] = "\ 6033 --with-f1, \ 6034 --without-f1, \ 6035 build-deps-for-f1, \ 6036 runtime-deps-for-f1, \ 6037 runtime-recommends-for-f1, \ 6038 packageconfig-conflicts-for-f1" 6039 PACKAGECONFIG[f2] = "\ 6040 ... and so on and so on ... 6041 6042 The :term:`PACKAGECONFIG` variable itself specifies a space-separated 6043 list of the features to enable. Following the features, you can 6044 determine the behavior of each feature by providing up to six 6045 order-dependent arguments, which are separated by commas. You can 6046 omit any argument you like but must retain the separating commas. The 6047 order is important and specifies the following: 6048 6049 #. Extra arguments that should be added to the configure script 6050 argument list (:term:`EXTRA_OECONF` or 6051 :term:`PACKAGECONFIG_CONFARGS`) if 6052 the feature is enabled. 6053 6054 #. Extra arguments that should be added to :term:`EXTRA_OECONF` or 6055 :term:`PACKAGECONFIG_CONFARGS` if the feature is disabled. 6056 6057 #. Additional build dependencies (:term:`DEPENDS`) 6058 that should be added if the feature is enabled. 6059 6060 #. Additional runtime dependencies (:term:`RDEPENDS`) 6061 that should be added if the feature is enabled. 6062 6063 #. Additional runtime recommendations 6064 (:term:`RRECOMMENDS`) that should be added if 6065 the feature is enabled. 6066 6067 #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG` 6068 settings for this feature. 6069 6070 Consider the following :term:`PACKAGECONFIG` block taken from the 6071 ``librsvg`` recipe. In this example the feature is ``gtk``, which has 6072 three arguments that determine the feature's behavior:: 6073 6074 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" 6075 6076 The 6077 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is 6078 enabled. In this case, ``--with-gtk3`` is added to the configure 6079 script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the 6080 other hand, if the feature is disabled say through a ``.bbappend`` 6081 file in another layer, then the second argument ``--without-gtk3`` is 6082 added to the configure script instead. 6083 6084 The basic :term:`PACKAGECONFIG` structure previously described holds true 6085 regardless of whether you are creating a block or changing a block. 6086 When creating a block, use the structure inside your recipe. 6087 6088 If you want to change an existing :term:`PACKAGECONFIG` block, you can do 6089 so one of two ways: 6090 6091 - *Append file:* Create an append file named 6092 ``recipename.bbappend`` in your layer and override the value of 6093 :term:`PACKAGECONFIG`. You can either completely override the 6094 variable:: 6095 6096 PACKAGECONFIG = "f4 f5" 6097 6098 Or, you can just append the variable:: 6099 6100 PACKAGECONFIG:append = " f4" 6101 6102 - *Configuration file:* This method is identical to changing the 6103 block through an append file except you edit your ``local.conf`` 6104 or ``mydistro.conf`` file. As with append files previously 6105 described, you can either completely override the variable:: 6106 6107 PACKAGECONFIG:pn-recipename = "f4 f5" 6108 6109 Or, you can just amend the variable:: 6110 6111 PACKAGECONFIG:append:pn-recipename = " f4" 6112 6113 :term:`PACKAGECONFIG_CONFARGS` 6114 A space-separated list of configuration options generated from the 6115 :term:`PACKAGECONFIG` setting. 6116 6117 Classes such as :ref:`ref-classes-autotools` and :ref:`ref-classes-cmake` 6118 use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options 6119 to ``configure`` and ``cmake``, respectively. If you are using 6120 :term:`PACKAGECONFIG` but not a class that handles the 6121 :ref:`ref-tasks-configure` task, then you need to use 6122 :term:`PACKAGECONFIG_CONFARGS` appropriately. 6123 6124 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` 6125 For recipes inheriting the :ref:`ref-classes-packagegroup` class, setting 6126 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the 6127 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) 6128 should not be automatically created by the ``packagegroup`` recipe, 6129 which is the default behavior. 6130 6131 :term:`PACKAGES` 6132 The list of packages the recipe creates. The default value is the 6133 following:: 6134 6135 ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} 6136 6137 During packaging, the :ref:`ref-tasks-package` task 6138 goes through :term:`PACKAGES` and uses the :term:`FILES` 6139 variable corresponding to each package to assign files to the 6140 package. If a file matches the :term:`FILES` variable for more than one 6141 package in :term:`PACKAGES`, it will be assigned to the earliest 6142 (leftmost) package. 6143 6144 Packages in the variable's list that are empty (i.e. where none of 6145 the patterns in ``FILES:``\ pkg match any files installed by the 6146 :ref:`ref-tasks-install` task) are not generated, 6147 unless generation is forced through the 6148 :term:`ALLOW_EMPTY` variable. 6149 6150 :term:`PACKAGES_DYNAMIC` 6151 A promise that your recipe satisfies runtime dependencies for 6152 optional modules that are found in other recipes. 6153 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it 6154 only states that they should be satisfied. For example, if a hard, 6155 runtime dependency (:term:`RDEPENDS`) of another 6156 package is satisfied at build time through the :term:`PACKAGES_DYNAMIC` 6157 variable, but a package with the module name is never actually 6158 produced, then the other package will be broken. Thus, if you attempt 6159 to include that package in an image, you will get a dependency 6160 failure from the packaging system during the 6161 :ref:`ref-tasks-rootfs` task. 6162 6163 Typically, if there is a chance that such a situation can occur and 6164 the package that is not created is valid without the dependency being 6165 satisfied, then you should use :term:`RRECOMMENDS` 6166 (a soft runtime dependency) instead of :term:`RDEPENDS`. 6167 6168 For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when 6169 you are splitting packages, see the 6170 ":ref:`dev-manual/packages:handling optional module packaging`" 6171 section in the Yocto Project Development Tasks Manual. 6172 6173 :term:`PACKAGESPLITFUNCS` 6174 Specifies a list of functions run to perform additional splitting of 6175 files into individual packages. Recipes can either prepend to this 6176 variable or prepend to the ``populate_packages`` function in order to 6177 perform additional package splitting. In either case, the function 6178 should set :term:`PACKAGES`, 6179 :term:`FILES`, :term:`RDEPENDS` and 6180 other packaging variables appropriately in order to perform the 6181 desired splitting. 6182 6183 :term:`PARALLEL_MAKE` 6184 6185 Extra options passed to the build tool command (``make``, 6186 ``ninja`` or more specific build engines, like the Go language one) 6187 during the :ref:`ref-tasks-compile` task, to specify parallel compilation 6188 on the local build host. This variable is usually in the form "-j x", 6189 where x represents the maximum number of parallel threads such engines 6190 can run. 6191 6192 .. note:: 6193 6194 For software compiled by ``make``, in order for :term:`PARALLEL_MAKE` 6195 to be effective, ``make`` must be called with 6196 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 6197 way to ensure this is to use the ``oe_runmake`` function. 6198 6199 By default, the OpenEmbedded build system automatically sets this 6200 variable to be equal to the number of cores the build system uses. 6201 6202 .. note:: 6203 6204 If the software being built experiences dependency issues during 6205 the :ref:`ref-tasks-compile` task that result in race conditions, you can clear 6206 the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For 6207 information on addressing race conditions, see the 6208 ":ref:`dev-manual/debugging:debugging parallel make races`" 6209 section in the Yocto Project Development Tasks Manual. 6210 6211 For single socket systems (i.e. one CPU), you should not have to 6212 override this variable to gain optimal parallelism during builds. 6213 However, if you have very large systems that employ multiple physical 6214 CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is 6215 not set higher than "-j 20". 6216 6217 For more information on speeding up builds, see the 6218 ":ref:`dev-manual/speeding-up-build:speeding up a build`" 6219 section in the Yocto Project Development Tasks Manual. 6220 6221 :term:`PARALLEL_MAKEINST` 6222 Extra options passed to the build tool install command 6223 (``make install``, ``ninja install`` or more specific ones) 6224 during the :ref:`ref-tasks-install` task in order to specify 6225 parallel installation. This variable defaults to the value of 6226 :term:`PARALLEL_MAKE`. 6227 6228 .. note:: 6229 6230 For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST` 6231 to be effective, ``make`` must be called with 6232 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 6233 way to ensure this is to use the ``oe_runmake`` function. 6234 6235 If the software being built experiences dependency issues during 6236 the :ref:`ref-tasks-install` task that result in race conditions, you can 6237 clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a 6238 workaround. For information on addressing race conditions, see the 6239 ":ref:`dev-manual/debugging:debugging parallel make races`" 6240 section in the Yocto Project Development Tasks Manual. 6241 6242 :term:`PATCHRESOLVE` 6243 Determines the action to take when a patch fails. You can set this 6244 variable to one of two values: "noop" and "user". 6245 6246 The default value of "noop" causes the build to simply fail when the 6247 OpenEmbedded build system cannot successfully apply a patch. Setting 6248 the value to "user" causes the build system to launch a shell and 6249 places you in the right location so that you can manually resolve the 6250 conflicts. 6251 6252 Set this variable in your ``local.conf`` file. 6253 6254 :term:`PATCHTOOL` 6255 Specifies the utility used to apply patches for a recipe during the 6256 :ref:`ref-tasks-patch` task. You can specify one of 6257 three utilities: "patch", "quilt", or "git". The default utility used 6258 is "quilt" except for the quilt-native recipe itself. Because the 6259 quilt tool is not available at the time quilt-native is being 6260 patched, it uses "patch". 6261 6262 If you wish to use an alternative patching tool, set the variable in 6263 the recipe using one of the following:: 6264 6265 PATCHTOOL = "patch" 6266 PATCHTOOL = "quilt" 6267 PATCHTOOL = "git" 6268 6269 :term:`PE` 6270 The epoch of the recipe. By default, this variable is unset. The 6271 variable is used to make upgrades possible when the versioning scheme 6272 changes in some backwards incompatible way. 6273 6274 :term:`PE` is the default value of the :term:`PKGE` variable. 6275 6276 :term:`PEP517_WHEEL_PATH` 6277 When used by recipes that inherit the :ref:`ref-classes-python_pep517` 6278 class, denotes the path to ``dist/`` (short for distribution) where the 6279 binary archive ``wheel`` is built. 6280 6281 :term:`PERSISTENT_DIR` 6282 See :term:`bitbake:PERSISTENT_DIR` in the BitBake manual. 6283 6284 :term:`PF` 6285 Specifies the recipe or package name and includes all version and 6286 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and 6287 ``bash-4.2-r1/``). This variable is comprised of the following: 6288 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} 6289 6290 :term:`PIXBUF_PACKAGES` 6291 When inheriting the :ref:`ref-classes-pixbufcache` 6292 class, this variable identifies packages that contain the pixbuf 6293 loaders used with ``gdk-pixbuf``. By default, the 6294 :ref:`ref-classes-pixbufcache` class assumes that 6295 the loaders are in the recipe's main package (i.e. 6296 ``${``\ :term:`PN`\ ``}``). Use this variable if the 6297 loaders you need are in a package other than that main package. 6298 6299 :term:`PKG` 6300 The name of the resulting package created by the OpenEmbedded build 6301 system. 6302 6303 .. note:: 6304 6305 When using the :term:`PKG` variable, you must use a package name override. 6306 6307 For example, when the :ref:`ref-classes-debian` class renames the output 6308 package, it does so by setting ``PKG:packagename``. 6309 6310 :term:`PKG_CONFIG_PATH` 6311 The path to ``pkg-config`` files for the current build context. 6312 ``pkg-config`` reads this variable from the environment. 6313 6314 :term:`PKGD` 6315 Points to the destination directory for files to be packaged before 6316 they are split into individual packages. This directory defaults to 6317 the following:: 6318 6319 ${WORKDIR}/package 6320 6321 Do not change this default. 6322 6323 :term:`PKGDATA_DIR` 6324 Points to a shared, global-state directory that holds data generated 6325 during the packaging process. During the packaging process, the 6326 :ref:`ref-tasks-packagedata` task packages data 6327 for each recipe and installs it into this temporary, shared area. 6328 This directory defaults to the following, which you should not 6329 change:: 6330 6331 ${STAGING_DIR_HOST}/pkgdata 6332 6333 For examples of how this data is used, see the 6334 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6335 section in the Yocto Project Overview and Concepts Manual and the 6336 ":ref:`dev-manual/debugging:viewing package information with \`\`oe-pkgdata-util\`\``" 6337 section in the Yocto Project Development Tasks Manual. For more 6338 information on the shared, global-state directory, see 6339 :term:`STAGING_DIR_HOST`. 6340 6341 :term:`PKGDEST` 6342 Points to the parent directory for files to be packaged after they 6343 have been split into individual packages. This directory defaults to 6344 the following:: 6345 6346 ${WORKDIR}/packages-split 6347 6348 Under this directory, the build system creates directories for each 6349 package specified in :term:`PACKAGES`. Do not change 6350 this default. 6351 6352 :term:`PKGDESTWORK` 6353 Points to a temporary work area where the 6354 :ref:`ref-tasks-package` task saves package metadata. 6355 The :term:`PKGDESTWORK` location defaults to the following:: 6356 6357 ${WORKDIR}/pkgdata 6358 6359 Do not change this default. 6360 6361 The :ref:`ref-tasks-packagedata` task copies the 6362 package metadata from :term:`PKGDESTWORK` to 6363 :term:`PKGDATA_DIR` to make it available globally. 6364 6365 :term:`PKGE` 6366 The epoch of the package(s) built by the recipe. By default, :term:`PKGE` 6367 is set to :term:`PE`. 6368 6369 :term:`PKGR` 6370 The revision of the package(s) built by the recipe. By default, 6371 :term:`PKGR` is set to :term:`PR`. 6372 6373 :term:`PKGV` 6374 The version of the package(s) built by the recipe. By default, 6375 :term:`PKGV` is set to :term:`PV`. 6376 6377 :term:`PN` 6378 This variable can have two separate functions depending on the 6379 context: a recipe name or a resulting package name. 6380 6381 :term:`PN` refers to a recipe name in the context of a file used by the 6382 OpenEmbedded build system as input to create a package. The name is 6383 normally extracted from the recipe file name. For example, if the 6384 recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN` 6385 will be "expat". 6386 6387 The variable refers to a package name in the context of a file 6388 created or produced by the OpenEmbedded build system. 6389 6390 If applicable, the :term:`PN` variable also contains any special suffix 6391 or prefix. For example, using ``bash`` to build packages for the 6392 native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build 6393 packages for the target and for Multilib, :term:`PN` would be ``bash`` 6394 and ``lib64-bash``, respectively. 6395 6396 :term:`POPULATE_SDK_POST_HOST_COMMAND` 6397 Specifies a list of functions to call once the OpenEmbedded build 6398 system has created the host part of the SDK. You can specify 6399 functions separated by semicolons:: 6400 6401 POPULATE_SDK_POST_HOST_COMMAND += "function; ... " 6402 6403 If you need to pass the SDK path to a command within a function, you 6404 can use ``${SDK_DIR}``, which points to the parent directory used by 6405 the OpenEmbedded build system when creating SDK output. See the 6406 :term:`SDK_DIR` variable for more information. 6407 6408 :term:`POPULATE_SDK_POST_TARGET_COMMAND` 6409 Specifies a list of functions to call once the OpenEmbedded build 6410 system has created the target part of the SDK. You can specify 6411 functions separated by semicolons:: 6412 6413 POPULATE_SDK_POST_TARGET_COMMAND += "function; ... " 6414 6415 If you need to pass the SDK path to a command within a function, you 6416 can use ``${SDK_DIR}``, which points to the parent directory used by 6417 the OpenEmbedded build system when creating SDK output. See the 6418 :term:`SDK_DIR` variable for more information. 6419 6420 :term:`PR` 6421 The revision of the recipe. The default value for this variable is 6422 "r0". Subsequent revisions of the recipe conventionally have the 6423 values "r1", "r2", and so forth. When :term:`PV` increases, 6424 :term:`PR` is conventionally reset to "r0". 6425 6426 .. note:: 6427 6428 The OpenEmbedded build system does not need the aid of :term:`PR` 6429 to know when to rebuild a recipe. The build system uses the task 6430 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the 6431 :ref:`stamp <structure-build-tmp-stamps>` and 6432 :ref:`overview-manual/concepts:shared state cache` 6433 mechanisms. 6434 6435 The :term:`PR` variable primarily becomes significant when a package 6436 manager dynamically installs packages on an already built image. In 6437 this case, :term:`PR`, which is the default value of 6438 :term:`PKGR`, helps the package manager distinguish which 6439 package is the most recent one in cases where many packages have the 6440 same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with 6441 the same :term:`PV` usually means that the packages all install the same 6442 upstream version, but with later (:term:`PR`) version packages including 6443 packaging fixes. 6444 6445 .. note:: 6446 6447 :term:`PR` does not need to be increased for changes that do not change the 6448 package contents or metadata. 6449 6450 Because manually managing :term:`PR` can be cumbersome and error-prone, 6451 an automated solution exists. See the 6452 ":ref:`dev-manual/packages:working with a pr service`" section 6453 in the Yocto Project Development Tasks Manual for more information. 6454 6455 :term:`PREFERRED_PROVIDER` 6456 If multiple recipes provide the same item, this variable determines 6457 which recipe is preferred and thus provides the item (i.e. the 6458 preferred provider). You should always suffix this variable with the 6459 name of the provided item. And, you should define the variable using 6460 the preferred recipe's name (:term:`PN`). Here is a common 6461 example:: 6462 6463 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 6464 6465 In the previous example, multiple recipes are providing "virtual/kernel". 6466 The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of 6467 the recipe you prefer to provide "virtual/kernel". 6468 6469 Following are more examples:: 6470 6471 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" 6472 PREFERRED_PROVIDER_virtual/libgl ?= "mesa" 6473 6474 For more 6475 information, see the ":ref:`dev-manual/new-recipe:using virtual providers`" 6476 section in the Yocto Project Development Tasks Manual. 6477 6478 .. note:: 6479 6480 If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any 6481 recipe that :term:`PROVIDES` that item but is not selected (defined) 6482 by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually 6483 desirable since this mechanism is designed to select between mutually 6484 exclusive alternative providers. 6485 6486 :term:`PREFERRED_PROVIDERS` 6487 See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual. 6488 6489 :term:`PREFERRED_VERSION` 6490 If there are multiple versions of a recipe available, this variable 6491 determines which version should be given preference. You must always 6492 suffix the variable with the :term:`PN` you want to select (`python` in 6493 the first example below), and you should specify the :term:`PV` 6494 accordingly (`3.4.0` in the example). 6495 6496 The :term:`PREFERRED_VERSION` variable supports limited wildcard use 6497 through the "``%``" character. You can use the character to match any 6498 number of characters, which can be useful when specifying versions 6499 that contain long revision numbers that potentially change. Here are 6500 two examples:: 6501 6502 PREFERRED_VERSION_python = "3.4.0" 6503 PREFERRED_VERSION_linux-yocto = "5.0%" 6504 6505 .. note:: 6506 6507 The use of the "%" character is limited in that it only works at the end of the 6508 string. You cannot use the wildcard character in any other 6509 location of the string. 6510 6511 The specified version is matched against :term:`PV`, which 6512 does not necessarily match the version part of the recipe's filename. 6513 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` 6514 where ``foo_git.bb`` contains the following assignment:: 6515 6516 PV = "1.1+git${SRCPV}" 6517 6518 In this case, the correct way to select 6519 ``foo_git.bb`` is by using an assignment such as the following:: 6520 6521 PREFERRED_VERSION_foo = "1.1+git%" 6522 6523 Compare that previous example 6524 against the following incorrect example, which does not work:: 6525 6526 PREFERRED_VERSION_foo = "git" 6527 6528 Sometimes the :term:`PREFERRED_VERSION` variable can be set by 6529 configuration files in a way that is hard to change. You can use 6530 :term:`OVERRIDES` to set a machine-specific 6531 override. Here is an example:: 6532 6533 PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%" 6534 6535 Although not recommended, worst case, you can also use the 6536 "forcevariable" override, which is the strongest override possible. 6537 Here is an example:: 6538 6539 PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%" 6540 6541 .. note:: 6542 6543 The ``:forcevariable`` override is not handled specially. This override 6544 only works because the default value of :term:`OVERRIDES` includes "forcevariable". 6545 6546 If a recipe with the specified version is not available, a warning 6547 message will be shown. See :term:`REQUIRED_VERSION` if you want this 6548 to be an error instead. 6549 6550 :term:`PREMIRRORS` 6551 Specifies additional paths from which the OpenEmbedded build system 6552 gets source code. When the build system searches for source code, it 6553 first tries the local download directory. If that location fails, the 6554 build system tries locations defined by :term:`PREMIRRORS`, the upstream 6555 source, and then locations specified by 6556 :term:`MIRRORS` in that order. 6557 6558 Assuming your distribution (:term:`DISTRO`) is "poky", 6559 the default value for :term:`PREMIRRORS` is defined in the 6560 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. 6561 6562 Typically, you could add a specific server for the build system to 6563 attempt before any others by adding something like the following to 6564 the ``local.conf`` configuration file in the 6565 :term:`Build Directory`:: 6566 6567 PREMIRRORS:prepend = "\ 6568 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6569 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6570 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6571 https://.*/.* &YOCTO_DL_URL;/mirror/sources/" 6572 6573 These changes cause the 6574 build system to intercept Git, FTP, HTTP, and HTTPS requests and 6575 direct them to the ``http://`` sources mirror. You can use 6576 ``file://`` URLs to point to local directories or network shares as 6577 well. 6578 6579 :term:`PRIORITY` 6580 Indicates the importance of a package. 6581 6582 :term:`PRIORITY` is considered to be part of the distribution policy 6583 because the importance of any given recipe depends on the purpose for 6584 which the distribution is being produced. Thus, :term:`PRIORITY` is not 6585 normally set within recipes. 6586 6587 You can set :term:`PRIORITY` to "required", "standard", "extra", and 6588 "optional", which is the default. 6589 6590 :term:`PRIVATE_LIBS` 6591 Specifies libraries installed within a recipe that should be ignored 6592 by the OpenEmbedded build system's shared library resolver. This 6593 variable is typically used when software being built by a recipe has 6594 its own private versions of a library normally provided by another 6595 recipe. In this case, you would not want the package containing the 6596 private libraries to be set as a dependency on other unrelated 6597 packages that should instead depend on the package providing the 6598 standard version of the library. 6599 6600 Libraries specified in this variable should be specified by their 6601 file name. For example, from the Firefox recipe in meta-browser:: 6602 6603 PRIVATE_LIBS = "libmozjs.so \ 6604 libxpcom.so \ 6605 libnspr4.so \ 6606 libxul.so \ 6607 libmozalloc.so \ 6608 libplc4.so \ 6609 libplds4.so" 6610 6611 For more information, see the 6612 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6613 section in the Yocto Project Overview and Concepts Manual. 6614 6615 :term:`PROVIDES` 6616 A list of aliases by which a particular recipe can be known. By 6617 default, a recipe's own :term:`PN` is implicitly already in its 6618 :term:`PROVIDES` list and therefore does not need to mention that it 6619 provides itself. If a recipe uses :term:`PROVIDES`, the additional 6620 aliases are synonyms for the recipe and can be useful for satisfying 6621 dependencies of other recipes during the build as specified by 6622 :term:`DEPENDS`. 6623 6624 Consider the following example :term:`PROVIDES` statement from the recipe 6625 file ``eudev_3.2.9.bb``:: 6626 6627 PROVIDES += "udev" 6628 6629 The :term:`PROVIDES` statement 6630 results in the "eudev" recipe also being available as simply "udev". 6631 6632 .. note:: 6633 6634 A recipe's own recipe name (:term:`PN`) is always implicitly prepended 6635 to :term:`PROVIDES`, so while using "+=" in the above example may not be 6636 strictly necessary it is recommended to avoid confusion. 6637 6638 In addition to providing recipes under alternate names, the 6639 :term:`PROVIDES` mechanism is also used to implement virtual targets. A 6640 virtual target is a name that corresponds to some particular 6641 functionality (e.g. a Linux kernel). Recipes that provide the 6642 functionality in question list the virtual target in :term:`PROVIDES`. 6643 Recipes that depend on the functionality in question can include the 6644 virtual target in :term:`DEPENDS` to leave the choice of provider open. 6645 6646 Conventionally, virtual targets have names on the form 6647 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part 6648 of the name and has no syntactical significance. 6649 6650 The :term:`PREFERRED_PROVIDER` variable is 6651 used to select which particular recipe provides a virtual target. 6652 6653 .. note:: 6654 6655 A corresponding mechanism for virtual runtime dependencies 6656 (packages) exists. However, the mechanism does not depend on any 6657 special functionality beyond ordinary variable assignments. For 6658 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of 6659 the component that manages the ``/dev`` directory. 6660 6661 Setting the "preferred provider" for runtime dependencies is as 6662 simple as using the following assignment in a configuration file:: 6663 6664 VIRTUAL-RUNTIME_dev_manager = "udev" 6665 6666 6667 :term:`PRSERV_HOST` 6668 The network based :term:`PR` service host and port. 6669 6670 The ``conf/templates/default/local.conf.sample.extended`` configuration 6671 file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST` 6672 variable is set:: 6673 6674 PRSERV_HOST = "localhost:0" 6675 6676 You must 6677 set the variable if you want to automatically start a local :ref:`PR 6678 service <dev-manual/packages:working with a pr service>`. You can 6679 set :term:`PRSERV_HOST` to other values to use a remote PR service. 6680 6681 6682 :term:`PSEUDO_IGNORE_PATHS` 6683 A comma-separated (without spaces) list of path prefixes that should be ignored 6684 by pseudo when monitoring and recording file operations, in order to avoid 6685 problems with files being written to outside of the pseudo context and 6686 reduce pseudo's overhead. A path is ignored if it matches any prefix in the list 6687 and can include partial directory (or file) names. 6688 6689 6690 :term:`PTEST_ENABLED` 6691 Specifies whether or not :ref:`Package 6692 Test <dev-manual/packages:testing packages with ptest>` (ptest) 6693 functionality is enabled when building a recipe. You should not set 6694 this variable directly. Enabling and disabling building Package Tests 6695 at build time should be done by adding "ptest" to (or removing it 6696 from) :term:`DISTRO_FEATURES`. 6697 6698 :term:`PV` 6699 The version of the recipe. The version is normally extracted from the 6700 recipe filename. For example, if the recipe is named 6701 ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1". 6702 :term:`PV` is generally not overridden within a recipe unless it is 6703 building an unstable (i.e. development) version from a source code 6704 repository (e.g. Git or Subversion). 6705 6706 :term:`PV` is the default value of the :term:`PKGV` variable. 6707 6708 :term:`PYPI_PACKAGE` 6709 When inheriting the :ref:`ref-classes-pypi` class, specifies the 6710 `PyPI <https://pypi.org/>`__ package name to be built. The default value 6711 is set based upon :term:`BPN` (stripping any "python-" or "python3-" 6712 prefix off if present), however for some packages it will need to be set 6713 explicitly if that will not match the package name (e.g. where the 6714 package name has a prefix, underscores, uppercase letters etc.) 6715 6716 :term:`PYTHON_ABI` 6717 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 6718 class, denotes the Application Binary Interface (ABI) currently in use 6719 for Python. By default, the ABI is "m". You do not have to set this 6720 variable as the OpenEmbedded build system sets it for you. 6721 6722 The OpenEmbedded build system uses the ABI to construct directory 6723 names used when installing the Python headers and libraries in 6724 sysroot (e.g. ``.../python3.3m/...``). 6725 6726 :term:`PYTHON_PN` 6727 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 6728 class, specifies the major Python version being built. For Python 3.x, 6729 :term:`PYTHON_PN` would be "python3". You do not have to set this 6730 variable as the OpenEmbedded build system automatically sets it for you. 6731 6732 The variable allows recipes to use common infrastructure such as the 6733 following:: 6734 6735 DEPENDS += "${PYTHON_PN}-native" 6736 6737 In the previous example, 6738 the version of the dependency is :term:`PYTHON_PN`. 6739 6740 :term:`QA_EMPTY_DIRS` 6741 Specifies a list of directories that are expected to be empty when 6742 packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or 6743 :term:`WARN_QA` these will be checked and an error or warning 6744 (respectively) will be produced. 6745 6746 The default :term:`QA_EMPTY_DIRS` value is set in 6747 :ref:`insane.bbclass <ref-classes-insane>`. 6748 6749 :term:`QA_EMPTY_DIRS_RECOMMENDATION` 6750 Specifies a recommendation for why a directory must be empty, 6751 which will be included in the error message if a specific directory 6752 is found to contain files. Must be overridden with the directory 6753 path to match on. 6754 6755 If no recommendation is specified for a directory, then the default 6756 "but it is expected to be empty" will be used. 6757 6758 An example message shows if files were present in '/dev':: 6759 6760 QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime" 6761 6762 :term:`RANLIB` 6763 The minimal command and arguments to run ``ranlib``. 6764 6765 :term:`RCONFLICTS` 6766 The list of packages that conflict with packages. Note that packages 6767 will not be installed if conflicting packages are not first removed. 6768 6769 Like all package-controlling variables, you must always use them in 6770 conjunction with a package name override. Here is an example:: 6771 6772 RCONFLICTS:${PN} = "another_conflicting_package_name" 6773 6774 BitBake, which the OpenEmbedded build system uses, supports 6775 specifying versioned dependencies. Although the syntax varies 6776 depending on the packaging format, BitBake hides these differences 6777 from you. Here is the general syntax to specify versions with the 6778 :term:`RCONFLICTS` variable:: 6779 6780 RCONFLICTS:${PN} = "package (operator version)" 6781 6782 For ``operator``, you can specify the following: 6783 6784 - = 6785 - < 6786 - > 6787 - <= 6788 - >= 6789 6790 For example, the following sets up a dependency on version 1.2 or 6791 greater of the package ``foo``:: 6792 6793 RCONFLICTS:${PN} = "foo (>= 1.2)" 6794 6795 :term:`RDEPENDS` 6796 Lists runtime dependencies of a package. These dependencies are other 6797 packages that must be installed in order for the package to function 6798 correctly. As an example, the following assignment declares that the 6799 package ``foo`` needs the packages ``bar`` and ``baz`` to be 6800 installed:: 6801 6802 RDEPENDS:foo = "bar baz" 6803 6804 The most common types of package 6805 runtime dependencies are automatically detected and added. Therefore, 6806 most recipes do not need to set :term:`RDEPENDS`. For more information, 6807 see the 6808 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6809 section in the Yocto Project Overview and Concepts Manual. 6810 6811 The practical effect of the above :term:`RDEPENDS` assignment is that 6812 ``bar`` and ``baz`` will be declared as dependencies inside the 6813 package ``foo`` when it is written out by one of the 6814 :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks. 6815 Exactly how this is done depends on which package format is used, 6816 which is determined by 6817 :term:`PACKAGE_CLASSES`. When the 6818 corresponding package manager installs the package, it will know to 6819 also install the packages on which it depends. 6820 6821 To ensure that the packages ``bar`` and ``baz`` get built, the 6822 previous :term:`RDEPENDS` assignment also causes a task dependency to be 6823 added. This dependency is from the recipe's 6824 :ref:`ref-tasks-build` (not to be confused with 6825 :ref:`ref-tasks-compile`) task to the 6826 :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and 6827 ``baz``. 6828 6829 The names of the packages you list within :term:`RDEPENDS` must be the 6830 names of other packages --- they cannot be recipe names. Although 6831 package names and recipe names usually match, the important point 6832 here is that you are providing package names within the :term:`RDEPENDS` 6833 variable. For an example of the default list of packages created from 6834 a recipe, see the :term:`PACKAGES` variable. 6835 6836 Because the :term:`RDEPENDS` variable applies to packages being built, 6837 you should always use the variable in a form with an attached package 6838 name (remember that a single recipe can build multiple packages). For 6839 example, suppose you are building a development package that depends 6840 on the ``perl`` package. In this case, you would use the following 6841 :term:`RDEPENDS` statement:: 6842 6843 RDEPENDS:${PN}-dev += "perl" 6844 6845 In the example, 6846 the development package depends on the ``perl`` package. Thus, the 6847 :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of 6848 the variable. 6849 6850 .. note:: 6851 6852 ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` 6853 by default. This default is set in the BitBake configuration file 6854 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove 6855 ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator 6856 rather than the "=" operator. 6857 6858 The package names you use with :term:`RDEPENDS` must appear as they would 6859 in the :term:`PACKAGES` variable. The :term:`PKG` variable 6860 allows a different name to be used for the final package (e.g. the 6861 :ref:`ref-classes-debian` class uses this to rename 6862 packages), but this final package name cannot be used with 6863 :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be 6864 independent of the package format used. 6865 6866 BitBake, which the OpenEmbedded build system uses, supports 6867 specifying versioned dependencies. Although the syntax varies 6868 depending on the packaging format, BitBake hides these differences 6869 from you. Here is the general syntax to specify versions with the 6870 :term:`RDEPENDS` variable:: 6871 6872 RDEPENDS:${PN} = "package (operator version)" 6873 6874 For ``operator``, you can specify the following: 6875 6876 - = 6877 - < 6878 - > 6879 - <= 6880 - >= 6881 6882 For version, provide the version number. 6883 6884 .. note:: 6885 6886 You can use :term:`EXTENDPKGV` to provide a full package version 6887 specification. 6888 6889 For example, the following sets up a dependency on version 1.2 or 6890 greater of the package ``foo``:: 6891 6892 RDEPENDS:${PN} = "foo (>= 1.2)" 6893 6894 For information on build-time dependencies, see the :term:`DEPENDS` 6895 variable. You can also see the 6896 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and 6897 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the 6898 BitBake User Manual for additional information on tasks and dependencies. 6899 6900 :term:`RECIPE_NO_UPDATE_REASON` 6901 If a recipe should not be replaced by a more recent upstream version, 6902 putting the reason why in this variable in a recipe allows 6903 ``devtool check-upgrade-status`` command to display it, as explained 6904 in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`" 6905 section. 6906 6907 :term:`REPODIR` 6908 See :term:`bitbake:REPODIR` in the BitBake manual. 6909 6910 :term:`REQUIRED_DISTRO_FEATURES` 6911 When inheriting the :ref:`ref-classes-features_check` 6912 class, this variable identifies distribution features that must exist 6913 in the current configuration in order for the OpenEmbedded build 6914 system to build the recipe. In other words, if the 6915 :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not 6916 appear in :term:`DISTRO_FEATURES` within the current configuration, then 6917 the recipe will be skipped, and if the build system attempts to build 6918 the recipe then an error will be triggered. 6919 6920 :term:`REQUIRED_VERSION` 6921 If there are multiple versions of a recipe available, this variable 6922 determines which version should be given preference. 6923 :term:`REQUIRED_VERSION` works in exactly the same manner as 6924 :term:`PREFERRED_VERSION`, except that if the specified version is not 6925 available then an error message is shown and the build fails 6926 immediately. 6927 6928 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set 6929 for the same recipe, the :term:`REQUIRED_VERSION` value applies. 6930 6931 :term:`RM_WORK_EXCLUDE` 6932 With :ref:`ref-classes-rm-work` enabled, this variable 6933 specifies a list of recipes whose work directories should not be removed. 6934 See the ":ref:`ref-classes-rm-work`" section for more details. 6935 6936 :term:`ROOT_HOME` 6937 Defines the root home directory. By default, this directory is set as 6938 follows in the BitBake configuration file:: 6939 6940 ROOT_HOME ??= "/home/root" 6941 6942 .. note:: 6943 6944 This default value is likely used because some embedded solutions 6945 prefer to have a read-only root filesystem and prefer to keep 6946 writeable data in one place. 6947 6948 You can override the default by setting the variable in any layer or 6949 in the ``local.conf`` file. Because the default is set using a "weak" 6950 assignment (i.e. "??="), you can use either of the following forms to 6951 define your override:: 6952 6953 ROOT_HOME = "/root" 6954 ROOT_HOME ?= "/root" 6955 6956 These 6957 override examples use ``/root``, which is probably the most commonly 6958 used override. 6959 6960 :term:`ROOTFS` 6961 Indicates a filesystem image to include as the root filesystem. 6962 6963 The :term:`ROOTFS` variable is an optional variable used with the 6964 :ref:`ref-classes-image-live` class. 6965 6966 :term:`ROOTFS_POSTINSTALL_COMMAND` 6967 Specifies a list of functions to call after the OpenEmbedded build 6968 system has installed packages. You can specify functions separated by 6969 semicolons:: 6970 6971 ROOTFS_POSTINSTALL_COMMAND += "function; ... " 6972 6973 If you need to pass the root filesystem path to a command within a 6974 function, you can use ``${IMAGE_ROOTFS}``, which points to the 6975 directory that becomes the root filesystem image. See the 6976 :term:`IMAGE_ROOTFS` variable for more 6977 information. 6978 6979 :term:`ROOTFS_POSTPROCESS_COMMAND` 6980 Specifies a list of functions to call once the OpenEmbedded build 6981 system has created the root filesystem. You can specify functions 6982 separated by semicolons:: 6983 6984 ROOTFS_POSTPROCESS_COMMAND += "function; ... " 6985 6986 If you need to pass the root filesystem path to a command within a 6987 function, you can use ``${IMAGE_ROOTFS}``, which points to the 6988 directory that becomes the root filesystem image. See the 6989 :term:`IMAGE_ROOTFS` variable for more 6990 information. 6991 6992 :term:`ROOTFS_POSTUNINSTALL_COMMAND` 6993 Specifies a list of functions to call after the OpenEmbedded build 6994 system has removed unnecessary packages. When runtime package 6995 management is disabled in the image, several packages are removed 6996 including ``base-passwd``, ``shadow``, and ``update-alternatives``. 6997 You can specify functions separated by semicolons:: 6998 6999 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " 7000 7001 If you need to pass the root filesystem path to a command within a 7002 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7003 directory that becomes the root filesystem image. See the 7004 :term:`IMAGE_ROOTFS` variable for more 7005 information. 7006 7007 :term:`ROOTFS_PREPROCESS_COMMAND` 7008 Specifies a list of functions to call before the OpenEmbedded build 7009 system has created the root filesystem. You can specify functions 7010 separated by semicolons:: 7011 7012 ROOTFS_PREPROCESS_COMMAND += "function; ... " 7013 7014 If you need to pass the root filesystem path to a command within a 7015 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7016 directory that becomes the root filesystem image. See the 7017 :term:`IMAGE_ROOTFS` variable for more 7018 information. 7019 7020 :term:`RPROVIDES` 7021 A list of package name aliases that a package also provides. These 7022 aliases are useful for satisfying runtime dependencies of other 7023 packages both during the build and on the target (as specified by 7024 :term:`RDEPENDS`). 7025 7026 .. note:: 7027 7028 A package's own name is implicitly already in its :term:`RPROVIDES` list. 7029 7030 As with all package-controlling variables, you must always use the 7031 variable in conjunction with a package name override. Here is an 7032 example:: 7033 7034 RPROVIDES:${PN} = "widget-abi-2" 7035 7036 :term:`RRECOMMENDS` 7037 A list of packages that extends the usability of a package being 7038 built. The package being built does not depend on this list of 7039 packages in order to successfully build, but rather uses them for 7040 extended usability. To specify runtime dependencies for packages, see 7041 the :term:`RDEPENDS` variable. 7042 7043 The package manager will automatically install the :term:`RRECOMMENDS` 7044 list of packages when installing the built package. However, you can 7045 prevent listed packages from being installed by using the 7046 :term:`BAD_RECOMMENDATIONS`, 7047 :term:`NO_RECOMMENDATIONS`, and 7048 :term:`PACKAGE_EXCLUDE` variables. 7049 7050 Packages specified in :term:`RRECOMMENDS` need not actually be produced. 7051 However, there must be a recipe providing each package, either 7052 through the :term:`PACKAGES` or 7053 :term:`PACKAGES_DYNAMIC` variables or the 7054 :term:`RPROVIDES` variable, or an error will occur 7055 during the build. If such a recipe does exist and the package is not 7056 produced, the build continues without error. 7057 7058 Because the :term:`RRECOMMENDS` variable applies to packages being built, 7059 you should always attach an override to the variable to specify the 7060 particular package whose usability is being extended. For example, 7061 suppose you are building a development package that is extended to 7062 support wireless functionality. In this case, you would use the 7063 following:: 7064 7065 RRECOMMENDS:${PN}-dev += "wireless_package_name" 7066 7067 In the 7068 example, the package name (``${PN}-dev``) must appear as it would in 7069 the :term:`PACKAGES` namespace before any renaming of the output package 7070 by classes such as :ref:`ref-classes-debian`. 7071 7072 BitBake, which the OpenEmbedded build system uses, supports 7073 specifying versioned recommends. Although the syntax varies depending 7074 on the packaging format, BitBake hides these differences from you. 7075 Here is the general syntax to specify versions with the 7076 :term:`RRECOMMENDS` variable:: 7077 7078 RRECOMMENDS:${PN} = "package (operator version)" 7079 7080 For ``operator``, you can specify the following: 7081 7082 - = 7083 - < 7084 - > 7085 - <= 7086 - >= 7087 7088 For example, the following sets up a recommend on version 1.2 or 7089 greater of the package ``foo``:: 7090 7091 RRECOMMENDS:${PN} = "foo (>= 1.2)" 7092 7093 :term:`RREPLACES` 7094 A list of packages replaced by a package. The package manager uses 7095 this variable to determine which package should be installed to 7096 replace other package(s) during an upgrade. In order to also have the 7097 other package(s) removed at the same time, you must add the name of 7098 the other package to the :term:`RCONFLICTS` variable. 7099 7100 As with all package-controlling variables, you must use this variable 7101 in conjunction with a package name override. Here is an example:: 7102 7103 RREPLACES:${PN} = "other_package_being_replaced" 7104 7105 BitBake, which the OpenEmbedded build system uses, supports 7106 specifying versioned replacements. Although the syntax varies 7107 depending on the packaging format, BitBake hides these differences 7108 from you. Here is the general syntax to specify versions with the 7109 :term:`RREPLACES` variable:: 7110 7111 RREPLACES:${PN} = "package (operator version)" 7112 7113 For ``operator``, you can specify the following: 7114 7115 - = 7116 - < 7117 - > 7118 - <= 7119 - >= 7120 7121 For example, the following sets up a replacement using version 1.2 7122 or greater of the package ``foo``:: 7123 7124 RREPLACES:${PN} = "foo (>= 1.2)" 7125 7126 :term:`RSUGGESTS` 7127 A list of additional packages that you can suggest for installation 7128 by the package manager at the time a package is installed. Not all 7129 package managers support this functionality. 7130 7131 As with all package-controlling variables, you must always use this 7132 variable in conjunction with a package name override. Here is an 7133 example:: 7134 7135 RSUGGESTS:${PN} = "useful_package another_package" 7136 7137 :term:`RUST_CHANNEL` 7138 Specifies which version of Rust to build - "stable", "beta" or "nightly". 7139 The default value is "stable". Set this at your own risk, as values other 7140 than "stable" are not guaranteed to work at a given time. 7141 7142 :term:`S` 7143 The location in the :term:`Build Directory` where 7144 unpacked recipe source code resides. By default, this directory is 7145 ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, 7146 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe 7147 version. If the source tarball extracts the code to a directory named 7148 anything other than ``${BPN}-${PV}``, or if the source code is 7149 fetched from an SCM such as Git or Subversion, then you must set 7150 :term:`S` in the recipe so that the OpenEmbedded build system knows where 7151 to find the unpacked source. 7152 7153 As an example, assume a :term:`Source Directory` 7154 top-level folder named ``poky`` and a default :term:`Build Directory` at 7155 ``poky/build``. In this case, the work directory the build system 7156 uses to keep the unpacked recipe for ``db`` is the following:: 7157 7158 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 7159 7160 The unpacked source code resides in the ``db-5.1.19`` folder. 7161 7162 This next example assumes a Git repository. By default, Git 7163 repositories are cloned to ``${WORKDIR}/git`` during 7164 :ref:`ref-tasks-fetch`. Since this path is different 7165 from the default value of :term:`S`, you must set it specifically so the 7166 source can be located:: 7167 7168 SRC_URI = "git://path/to/repo.git;branch=main" 7169 S = "${WORKDIR}/git" 7170 7171 :term:`SANITY_REQUIRED_UTILITIES` 7172 Specifies a list of command-line utilities that should be checked for 7173 during the initial sanity checking process when running BitBake. If 7174 any of the utilities are not installed on the build host, then 7175 BitBake immediately exits with an error. 7176 7177 :term:`SANITY_TESTED_DISTROS` 7178 A list of the host distribution identifiers that the build system has 7179 been tested against. Identifiers consist of the host distributor ID 7180 followed by the release, as reported by the ``lsb_release`` tool or 7181 as read from ``/etc/lsb-release``. Separate the list items with 7182 explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is 7183 not empty and the current value of 7184 :term:`NATIVELSBSTRING` does not appear in the 7185 list, then the build system reports a warning that indicates the 7186 current host distribution has not been tested as a build host. 7187 7188 :term:`SDK_ARCH` 7189 The target architecture for the SDK. Typically, you do not directly 7190 set this variable. Instead, use :term:`SDKMACHINE`. 7191 7192 :term:`SDK_ARCHIVE_TYPE` 7193 Specifies the type of archive to create for the SDK. Valid values: 7194 7195 - ``tar.xz`` (default) 7196 - ``zip`` 7197 7198 Only one archive type can be specified. 7199 7200 :term:`SDK_BUILDINFO_FILE` 7201 When using the :ref:`ref-classes-image-buildinfo` class, 7202 specifies the file in the SDK to write the build information into. The 7203 default value is "``/buildinfo``". 7204 7205 :term:`SDK_CUSTOM_TEMPLATECONF` 7206 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to 7207 "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory` 7208 (:term:`TOPDIR`) then this will be copied into the SDK. 7209 7210 :term:`SDK_DEPLOY` 7211 The directory set up and used by the 7212 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the 7213 SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>` 7214 class defines :term:`SDK_DEPLOY` as follows:: 7215 7216 SDK_DEPLOY = "${TMPDIR}/deploy/sdk" 7217 7218 :term:`SDK_DIR` 7219 The parent directory used by the OpenEmbedded build system when 7220 creating SDK output. The 7221 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines 7222 the variable as follows:: 7223 7224 SDK_DIR = "${WORKDIR}/sdk" 7225 7226 .. note:: 7227 7228 The :term:`SDK_DIR` directory is a temporary directory as it is part of 7229 :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`. 7230 7231 :term:`SDK_EXT_TYPE` 7232 Controls whether or not shared state artifacts are copied into the 7233 extensible SDK. The default value of "full" copies all of the 7234 required shared state artifacts into the extensible SDK. The value 7235 "minimal" leaves these artifacts out of the SDK. 7236 7237 .. note:: 7238 7239 If you set the variable to "minimal", you need to ensure 7240 :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the 7241 artifacts to be fetched as needed. 7242 7243 :term:`SDK_HOST_MANIFEST` 7244 The manifest file for the host part of the SDK. This file lists all 7245 the installed packages that make up the host part of the SDK. The 7246 file contains package information on a line-per-package basis as 7247 follows:: 7248 7249 packagename packagearch version 7250 7251 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7252 defines the manifest file as follows:: 7253 7254 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" 7255 7256 The location is derived using the :term:`SDK_DEPLOY` and 7257 :term:`TOOLCHAIN_OUTPUTNAME` variables. 7258 7259 :term:`SDK_INCLUDE_PKGDATA` 7260 When set to "1", specifies to include the packagedata for all recipes 7261 in the "world" target in the extensible SDK. Including this data 7262 allows the ``devtool search`` command to find these recipes in search 7263 results, as well as allows the ``devtool add`` command to map 7264 dependencies more effectively. 7265 7266 .. note:: 7267 7268 Enabling the :term:`SDK_INCLUDE_PKGDATA` 7269 variable significantly increases build time because all of world 7270 needs to be built. Enabling the variable also slightly increases 7271 the size of the extensible SDK. 7272 7273 :term:`SDK_INCLUDE_TOOLCHAIN` 7274 When set to "1", specifies to include the toolchain in the extensible 7275 SDK. Including the toolchain is useful particularly when 7276 :term:`SDK_EXT_TYPE` is set to "minimal" to keep 7277 the SDK reasonably small but you still want to provide a usable 7278 toolchain. For example, suppose you want to use the toolchain from an 7279 IDE or from other tools and you do not want to perform additional 7280 steps to install the toolchain. 7281 7282 The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if 7283 :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if 7284 :term:`SDK_EXT_TYPE` is set to "full". 7285 7286 :term:`SDK_NAME` 7287 The base name for SDK output files. The name is derived from the 7288 :term:`DISTRO`, :term:`TCLIBC`, 7289 :term:`SDK_ARCH`, 7290 :term:`IMAGE_BASENAME`, and 7291 :term:`TUNE_PKGARCH` variables:: 7292 7293 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" 7294 7295 :term:`SDK_OS` 7296 Specifies the operating system for which the SDK will be built. The 7297 default value is the value of :term:`BUILD_OS`. 7298 7299 :term:`SDK_OUTPUT` 7300 The location used by the OpenEmbedded build system when creating SDK 7301 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 7302 class defines the variable as follows:: 7303 7304 SDK_DIR = "${WORKDIR}/sdk" 7305 SDK_OUTPUT = "${SDK_DIR}/image" 7306 SDK_DEPLOY = "${DEPLOY_DIR}/sdk" 7307 7308 .. note:: 7309 7310 The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of 7311 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is 7312 :term:`SDK_DEPLOY`. 7313 7314 :term:`SDK_PACKAGE_ARCHS` 7315 Specifies a list of architectures compatible with the SDK machine. 7316 This variable is set automatically and should not normally be 7317 hand-edited. Entries are separated using spaces and listed in order 7318 of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any 7319 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". 7320 7321 :term:`SDK_POSTPROCESS_COMMAND` 7322 Specifies a list of functions to call once the OpenEmbedded build 7323 system creates the SDK. You can specify functions separated by 7324 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " 7325 7326 If you need to pass an SDK path to a command within a function, you 7327 can use ``${SDK_DIR}``, which points to the parent directory used by 7328 the OpenEmbedded build system when creating SDK output. See the 7329 :term:`SDK_DIR` variable for more information. 7330 7331 :term:`SDK_PREFIX` 7332 The toolchain binary prefix used for 7333 :ref:`ref-classes-nativesdk` recipes. The 7334 OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the 7335 :term:`TARGET_PREFIX` when building 7336 ``nativesdk`` recipes. The default value is "${SDK_SYS}-". 7337 7338 :term:`SDK_RECRDEP_TASKS` 7339 A list of shared state tasks added to the extensible SDK. By default, 7340 the following tasks are added: 7341 7342 - :ref:`ref-tasks-populate_lic` 7343 - :ref:`ref-tasks-package_qa` 7344 - :ref:`ref-tasks-populate_sysroot` 7345 - :ref:`ref-tasks-deploy` 7346 7347 Despite the default value of "" for the 7348 :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added 7349 to the SDK. To specify tasks beyond these four, you need to use the 7350 :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional 7351 tasks that are needed in order to build 7352 :term:`SDK_TARGETS`). 7353 7354 :term:`SDK_SYS` 7355 Specifies the system, including the architecture and the operating 7356 system, for which the SDK will be built. 7357 7358 The OpenEmbedded build system automatically sets this variable based 7359 on :term:`SDK_ARCH`, 7360 :term:`SDK_VENDOR`, and 7361 :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS` 7362 variable yourself. 7363 7364 :term:`SDK_TARGET_MANIFEST` 7365 The manifest file for the target part of the SDK. This file lists all 7366 the installed packages that make up the target part of the SDK. The 7367 file contains package information on a line-per-package basis as 7368 follows:: 7369 7370 packagename packagearch version 7371 7372 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7373 defines the manifest file as follows:: 7374 7375 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" 7376 7377 The location is derived using the :term:`SDK_DEPLOY` and 7378 :term:`TOOLCHAIN_OUTPUTNAME` variables. 7379 7380 :term:`SDK_TARGETS` 7381 A list of targets to install from shared state as part of the 7382 standard or extensible SDK installation. The default value is "${PN}" 7383 (i.e. the image from which the SDK is built). 7384 7385 The :term:`SDK_TARGETS` variable is an internal variable and typically 7386 would not be changed. 7387 7388 :term:`SDK_TITLE` 7389 The title to be printed when running the SDK installer. By default, 7390 this title is based on the :term:`DISTRO_NAME` or 7391 :term:`DISTRO` variable and is set in the 7392 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7393 follows:: 7394 7395 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" 7396 7397 For the default distribution "poky", 7398 :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)". 7399 7400 For information on how to change this default title, see the 7401 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" 7402 section in the Yocto Project Application Development and the 7403 Extensible Software Development Kit (eSDK) manual. 7404 7405 :term:`SDK_TOOLCHAIN_LANGS` 7406 Specifies programming languages to support in the SDK, as a 7407 space-separated list. Currently supported items are ``rust`` and ``go``. 7408 7409 :term:`SDK_UPDATE_URL` 7410 An optional URL for an update server for the extensible SDK. If set, 7411 the value is used as the default update server when running 7412 ``devtool sdk-update`` within the extensible SDK. 7413 7414 :term:`SDK_VENDOR` 7415 Specifies the name of the SDK vendor. 7416 7417 :term:`SDK_VERSION` 7418 Specifies the version of the SDK. The Poky distribution configuration file 7419 (``/meta-poky/conf/distro/poky.conf``) sets the default 7420 :term:`SDK_VERSION` as follows:: 7421 7422 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}" 7423 7424 For additional information, see the 7425 :term:`DISTRO_VERSION` and 7426 :term:`METADATA_REVISION` variables. 7427 7428 :term:`SDK_ZIP_OPTIONS` 7429 Specifies extra options to pass to the ``zip`` command when zipping the SDK 7430 (i.e. when :term:`SDK_ARCHIVE_TYPE` is set to "zip"). The default value is 7431 "-y". 7432 7433 :term:`SDKEXTPATH` 7434 The default installation directory for the Extensible SDK. By 7435 default, this directory is based on the :term:`DISTRO` 7436 variable and is set in the 7437 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7438 follows:: 7439 7440 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" 7441 7442 For the 7443 default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk". 7444 7445 For information on how to change this default directory, see the 7446 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" 7447 section in the Yocto Project Application Development and the 7448 Extensible Software Development Kit (eSDK) manual. 7449 7450 :term:`SDKIMAGE_FEATURES` 7451 Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to 7452 the SDK generated from an image using the following command:: 7453 7454 $ bitbake -c populate_sdk imagename 7455 7456 :term:`SDKMACHINE` 7457 The machine for which the SDK is built. In other words, the SDK is built 7458 such that it runs on the target you specify with the :term:`SDKMACHINE` 7459 value. The value points to a corresponding ``.conf`` file under 7460 ``conf/machine-sdk/`` in the enabled layers, for example ``aarch64``, 7461 ``i586``, ``i686``, ``ppc64``, ``ppc64le``, and ``x86_64`` are 7462 :oe_git:`available in OpenEmbedded-Core </openembedded-core/tree/meta/conf/machine-sdk>`. 7463 7464 The variable defaults to :term:`BUILD_ARCH` so that SDKs are built for the 7465 architecture of the build machine. 7466 7467 .. note:: 7468 7469 You cannot set the :term:`SDKMACHINE` 7470 variable in your distribution configuration file. If you do, the 7471 configuration will not take effect. 7472 7473 :term:`SDKPATH` 7474 Defines the path offered to the user for installation of the SDK that 7475 is generated by the OpenEmbedded build system. The path appears as 7476 the default location for installing the SDK when you run the SDK's 7477 installation script. You can override the offered path when you run 7478 the script. 7479 7480 :term:`SDKTARGETSYSROOT` 7481 The full path to the sysroot used for cross-compilation within an SDK 7482 as it will be when installed into the default 7483 :term:`SDKPATH`. 7484 7485 :term:`SECTION` 7486 The section in which packages should be categorized. Package 7487 management utilities can make use of this variable. 7488 7489 :term:`SELECTED_OPTIMIZATION` 7490 Specifies the optimization flags passed to the C compiler when 7491 building for the target. The flags are passed through the default 7492 value of the :term:`TARGET_CFLAGS` variable. 7493 7494 The :term:`SELECTED_OPTIMIZATION` variable takes the value of 7495 :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which 7496 case the value of :term:`DEBUG_OPTIMIZATION` is used. 7497 7498 :term:`SERIAL_CONSOLES` 7499 Defines a serial console (TTY) to enable using 7500 :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the 7501 baud rate followed by the TTY device name separated by a semicolon. 7502 Use spaces to separate multiple devices:: 7503 7504 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" 7505 7506 :term:`SERIAL_CONSOLES_CHECK` 7507 Specifies serial consoles, which must be listed in 7508 :term:`SERIAL_CONSOLES`, to check against 7509 ``/proc/console`` before enabling them using getty. This variable 7510 allows aliasing in the format: <device>:<alias>. If a device was 7511 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in 7512 ``/proc/console``, you would do the following:: 7513 7514 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" 7515 7516 This variable is currently only supported with SysVinit (i.e. not 7517 with systemd). Note that :term:`SERIAL_CONSOLES_CHECK` also requires 7518 ``/etc/inittab`` to be writable when used with SysVinit. This makes it 7519 incompatible with customizations such as the following:: 7520 7521 EXTRA_IMAGE_FEATURES += "read-only-rootfs" 7522 7523 :term:`SETUPTOOLS_BUILD_ARGS` 7524 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7525 class, this variable can be used to specify additional arguments to be 7526 passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task. 7527 7528 :term:`SETUPTOOLS_INSTALL_ARGS` 7529 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7530 class, this variable can be used to specify additional arguments to be 7531 passed to ``setup.py install`` in the ``setuptools3_do_install()`` task. 7532 7533 :term:`SETUPTOOLS_SETUP_PATH` 7534 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7535 class, this variable should be used to specify the directory in which 7536 the ``setup.py`` file is located if it is not at the root of the source 7537 tree (as specified by :term:`S`). For example, in a recipe where the 7538 sources are fetched from a Git repository and ``setup.py`` is in a 7539 ``python/pythonmodule`` subdirectory, you would have this:: 7540 7541 S = "${WORKDIR}/git" 7542 SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule" 7543 7544 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` 7545 A list of recipe dependencies that should not be used to determine 7546 signatures of tasks from one recipe when they depend on tasks from 7547 another recipe. For example:: 7548 7549 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" 7550 7551 In the previous example, ``intone`` depends on ``mplayer2``. 7552 7553 You can use the special token ``"*"`` on the left-hand side of the 7554 dependency to match all recipes except the one on the right-hand 7555 side. Here is an example:: 7556 7557 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" 7558 7559 In the previous example, all recipes except ``quilt-native`` ignore 7560 task signatures from the ``quilt-native`` recipe when determining 7561 their task signatures. 7562 7563 Use of this variable is one mechanism to remove dependencies that 7564 affect task signatures and thus force rebuilds when a recipe changes. 7565 7566 .. note:: 7567 7568 If you add an inappropriate dependency for a recipe relationship, 7569 the software might break during runtime if the interface of the 7570 second recipe was changed after the first recipe had been built. 7571 7572 :term:`SIGGEN_EXCLUDERECIPES_ABISAFE` 7573 A list of recipes that are completely stable and will never change. 7574 The ABI for the recipes in the list are presented by output from the 7575 tasks run to build the recipe. Use of this variable is one way to 7576 remove dependencies from one recipe on another that affect task 7577 signatures and thus force rebuilds when the recipe changes. 7578 7579 .. note:: 7580 7581 If you add an inappropriate variable to this list, the software 7582 might break at runtime if the interface of the recipe was changed 7583 after the other had been built. 7584 7585 :term:`SITEINFO_BITS` 7586 Specifies the number of bits for the target system CPU. The value 7587 should be either "32" or "64". 7588 7589 :term:`SITEINFO_ENDIANNESS` 7590 Specifies the endian byte order of the target system. The value 7591 should be either "le" for little-endian or "be" for big-endian. 7592 7593 :term:`SKIP_FILEDEPS` 7594 Enables removal of all files from the "Provides" section of an RPM 7595 package. Removal of these files is required for packages containing 7596 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. 7597 7598 To enable file removal, set the variable to "1" in your 7599 ``conf/local.conf`` configuration file in your: 7600 :term:`Build Directory`:: 7601 7602 SKIP_FILEDEPS = "1" 7603 7604 :term:`SKIP_RECIPE` 7605 Used to prevent the OpenEmbedded build system from building a given 7606 recipe. Specify the :term:`PN` value as a variable flag (``varflag``) 7607 and provide a reason, which will be reported when attempting to 7608 build the recipe. 7609 7610 To prevent a recipe from being built, use the :term:`SKIP_RECIPE` 7611 variable in your ``local.conf`` file or distribution configuration. 7612 Here is an example which prevents ``myrecipe`` from being built:: 7613 7614 SKIP_RECIPE[myrecipe] = "Not supported by our organization." 7615 7616 :term:`SOC_FAMILY` 7617 A colon-separated list grouping together machines based upon the same 7618 family of SoC (System On Chip). You typically set this variable in a 7619 common ``.inc`` file that you include in the configuration files of all 7620 the machines. 7621 7622 .. note:: 7623 7624 You must include ``conf/machine/include/soc-family.inc`` for this 7625 variable to appear in :term:`MACHINEOVERRIDES`. 7626 7627 :term:`SOLIBS` 7628 Defines the suffix for shared libraries used on the target platform. 7629 By default, this suffix is ".so.*" for all Linux-based systems and is 7630 defined in the ``meta/conf/bitbake.conf`` configuration file. 7631 7632 You will see this variable referenced in the default values of 7633 ``FILES:${PN}``. 7634 7635 :term:`SOLIBSDEV` 7636 Defines the suffix for the development symbolic link (symlink) for 7637 shared libraries on the target platform. By default, this suffix is 7638 ".so" for Linux-based systems and is defined in the 7639 ``meta/conf/bitbake.conf`` configuration file. 7640 7641 You will see this variable referenced in the default values of 7642 ``FILES:${PN}-dev``. 7643 7644 :term:`SOURCE_DATE_EPOCH` 7645 This defines a date expressed in number of seconds since 7646 the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by 7647 multiple build systems to force a timestamp in built binaries. 7648 Many upstream projects already support this variable. 7649 7650 You will find more details in the `official specifications 7651 <https://reproducible-builds.org/specs/source-date-epoch/>`__. 7652 7653 A value for each recipe is computed from the sources by 7654 :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`. 7655 7656 If a recipe wishes to override the default behavior, it should set its 7657 own :term:`SOURCE_DATE_EPOCH` value:: 7658 7659 SOURCE_DATE_EPOCH = "1613559011" 7660 7661 :term:`SOURCE_MIRROR_FETCH` 7662 When you are fetching files to create a mirror of sources (i.e. 7663 creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in 7664 your ``local.conf`` configuration file ensures the source for all 7665 recipes are fetched regardless of whether or not a recipe is 7666 compatible with the configuration. A recipe is considered 7667 incompatible with the currently configured machine when either or 7668 both the :term:`COMPATIBLE_MACHINE` 7669 variable and :term:`COMPATIBLE_HOST` variables 7670 specify compatibility with a machine other than that of the current 7671 machine or host. 7672 7673 .. note:: 7674 7675 Do not set the :term:`SOURCE_MIRROR_FETCH` 7676 variable unless you are creating a source mirror. In other words, 7677 do not set the variable during a normal build. 7678 7679 :term:`SOURCE_MIRROR_URL` 7680 Defines your own :term:`PREMIRRORS` from which to 7681 first fetch source before attempting to fetch from the upstream 7682 specified in :term:`SRC_URI`. 7683 7684 To use this variable, you must globally inherit the 7685 :ref:`ref-classes-own-mirrors` class and then provide 7686 the URL to your mirrors. Here is the general syntax:: 7687 7688 INHERIT += "own-mirrors" 7689 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" 7690 7691 .. note:: 7692 7693 You can specify only a single URL in :term:`SOURCE_MIRROR_URL`. 7694 7695 :term:`SPDX_ARCHIVE_PACKAGED` 7696 This option allows to add to :term:`SPDX` output compressed archives 7697 of the files in the generated target packages. 7698 7699 Such archives are available in 7700 ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst`` 7701 under the :term:`Build Directory`. 7702 7703 Enable this option as follows:: 7704 7705 SPDX_ARCHIVE_PACKAGED = "1" 7706 7707 According to our tests on release 4.1 "langdale", building 7708 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this 7709 option multiplied the size of the ``tmp/deploy/spdx`` directory by a 7710 factor of 13 (+1.6 GiB for this image), compared to just using the 7711 :ref:`ref-classes-create-spdx` class with no option. 7712 7713 Note that this option doesn't increase the size of :term:`SPDX` 7714 files in ``tmp/deploy/images/MACHINE``. 7715 7716 :term:`SPDX_ARCHIVE_SOURCES` 7717 This option allows to add to :term:`SPDX` output compressed archives 7718 of the sources for packages installed on the target. It currently 7719 only works when :term:`SPDX_INCLUDE_SOURCES` is set. 7720 7721 This is one way of fulfilling "source code access" license 7722 requirements. 7723 7724 Such source archives are available in 7725 ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst`` 7726 under the :term:`Build Directory`. 7727 7728 Enable this option as follows:: 7729 7730 SPDX_INCLUDE_SOURCES = "1" 7731 SPDX_ARCHIVE_SOURCES = "1" 7732 7733 According to our tests on release 4.1 "langdale", building 7734 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling 7735 these options multiplied the size of the ``tmp/deploy/spdx`` 7736 directory by a factor of 11 (+1.4 GiB for this image), 7737 compared to just using the :ref:`ref-classes-create-spdx` 7738 class with no option. 7739 7740 Note that using this option only marginally increases the size 7741 of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/`` 7742 (+ 0.07\% with the tested image), compared to just enabling 7743 :term:`SPDX_INCLUDE_SOURCES`. 7744 7745 :term:`SPDX_CUSTOM_ANNOTATION_VARS` 7746 This option allows to associate `SPDX annotations 7747 <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe, 7748 using the values of variables in the recipe:: 7749 7750 ANNOTATION1 = "First annotation for recipe" 7751 ANNOTATION2 = "Second annotation for recipe" 7752 SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2" 7753 7754 This will add a new block to the recipe ``.sdpx.json`` output:: 7755 7756 "annotations": [ 7757 { 7758 "annotationDate": "2023-04-18T08:32:12Z", 7759 "annotationType": "OTHER", 7760 "annotator": "Tool: oe-spdx-creator - 1.0", 7761 "comment": "ANNOTATION1=First annotation for recipe" 7762 }, 7763 { 7764 "annotationDate": "2023-04-18T08:32:12Z", 7765 "annotationType": "OTHER", 7766 "annotator": "Tool: oe-spdx-creator - 1.0", 7767 "comment": "ANNOTATION2=Second annotation for recipe" 7768 } 7769 ], 7770 7771 :term:`SPDX_INCLUDE_SOURCES` 7772 This option allows to add a description of the source files used to build 7773 the host tools and the target packages, to the ``spdx.json`` files in 7774 ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`. 7775 As a consequence, the ``spdx.json`` files under the ``by-namespace`` and 7776 ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also 7777 modified to include references to such source file descriptions. 7778 7779 Enable this option as follows:: 7780 7781 SPDX_INCLUDE_SOURCES = "1" 7782 7783 According to our tests on release 4.1 "langdale", building 7784 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling 7785 this option multiplied the total size of the ``tmp/deploy/spdx`` 7786 directory by a factor of 3 (+291 MiB for this image), 7787 and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in 7788 ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this 7789 image), compared to just using the :ref:`ref-classes-create-spdx` class 7790 with no option. 7791 7792 :term:`SPDX_PRETTY` 7793 This option makes the SPDX output more human-readable, using 7794 identation and newlines, instead of the default output in a 7795 single line:: 7796 7797 SPDX_PRETTY = "1" 7798 7799 The generated SPDX files are approximately 20% bigger, but 7800 this option is recommended if you want to inspect the SPDX 7801 output files with a text editor. 7802 7803 :term:`SPDXLICENSEMAP` 7804 Maps commonly used license names to their SPDX counterparts found in 7805 ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` 7806 mappings, see the ``meta/conf/licenses.conf`` file. 7807 7808 For additional information, see the :term:`LICENSE` 7809 variable. 7810 7811 :term:`SPECIAL_PKGSUFFIX` 7812 A list of prefixes for :term:`PN` used by the OpenEmbedded 7813 build system to create variants of recipes or packages. The list 7814 specifies the prefixes to strip off during certain circumstances such 7815 as the generation of the :term:`BPN` variable. 7816 7817 :term:`SPL_BINARY` 7818 The file type for the Secondary Program Loader (SPL). Some devices 7819 use an SPL from which to boot (e.g. the BeagleBone development 7820 board). For such cases, you can declare the file type of the SPL 7821 binary in the ``u-boot.inc`` include file, which is used in the 7822 U-Boot recipe. 7823 7824 The SPL file type is set to "null" by default in the ``u-boot.inc`` 7825 file as follows:: 7826 7827 # Some versions of u-boot build an SPL (Second Program Loader) image that 7828 # should be packaged along with the u-boot binary as well as placed in the 7829 # deploy directory. For those versions they can set the following variables 7830 # to allow packaging the SPL. 7831 SPL_BINARY ?= "" 7832 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}" 7833 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" 7834 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" 7835 7836 The :term:`SPL_BINARY` variable helps form 7837 various ``SPL_*`` variables used by the OpenEmbedded build system. 7838 7839 See the BeagleBone machine configuration example in the 7840 ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" 7841 section in the Yocto Project Board Support Package Developer's Guide 7842 for additional information. 7843 7844 :term:`SPL_MKIMAGE_DTCOPTS` 7845 Options for the device tree compiler passed to ``mkimage -D`` feature 7846 while creating a FIT image with the :ref:`ref-classes-uboot-sign` 7847 class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the 7848 :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option 7849 to ``mkimage``. 7850 7851 The default value is set to "" by the :ref:`ref-classes-uboot-config` 7852 class. 7853 7854 :term:`SPL_SIGN_ENABLE` 7855 Enable signing of the U-Boot FIT image. The default value is "0". 7856 This variable is used by the :ref:`ref-classes-uboot-sign` class. 7857 7858 :term:`SPL_SIGN_KEYDIR` 7859 Location of the directory containing the RSA key and certificate used for 7860 signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign` 7861 class. 7862 7863 :term:`SPL_SIGN_KEYNAME` 7864 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class 7865 for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR` 7866 directory. If we have for example a ``dev.key`` key and a ``dev.crt`` 7867 certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will 7868 have to set :term:`SPL_SIGN_KEYNAME` to ``dev``. 7869 7870 :term:`SPLASH` 7871 This variable, used by the :ref:`ref-classes-image` class, allows 7872 to choose splashscreen applications. Set it to the names of packages 7873 for such applications to use. This variable is set by default to 7874 ``psplash``. 7875 7876 :term:`SPLASH_IMAGES` 7877 This variable, used by the ``psplash`` recipe, allows to customize 7878 the default splashscreen image. 7879 7880 Specified images in PNG format are converted to ``.h`` files by the recipe, 7881 and are included in the ``psplash`` binary, so you won't find them in 7882 the root filesystem. 7883 7884 To make such a change, it is recommended to customize the 7885 ``psplash`` recipe in a custom layer. Here is an example structure for 7886 an ``ACME`` board:: 7887 7888 meta-acme/recipes-core/psplash 7889 ├── files 7890 │ └── logo-acme.png 7891 └── psplash_%.bbappend 7892 7893 And here are the contents of the ``psplash_%.bbappend`` file in 7894 this example:: 7895 7896 SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default" 7897 FILESEXTRAPATHS:prepend := "${THISDIR}/files:" 7898 7899 You could even add specific configuration options for ``psplash``, 7900 for example:: 7901 7902 EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen" 7903 7904 For information on append files, see the 7905 ":ref:`dev-manual/layers:appending other layers metadata with your layer`" 7906 section. 7907 7908 :term:`SRCREV_FORMAT` 7909 See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual. 7910 7911 :term:`SRC_URI` 7912 7913 See the BitBake manual for the initial description for this variable: 7914 :term:`bitbake:SRC_URI`. 7915 7916 The following features are added by OpenEmbedded and the Yocto Project. 7917 7918 There are standard and recipe-specific options. Here are standard ones: 7919 7920 - ``apply`` --- whether to apply the patch or not. The default 7921 action is to apply the patch. 7922 7923 - ``striplevel`` --- which striplevel to use when applying the 7924 patch. The default level is 1. 7925 7926 - ``patchdir`` --- specifies the directory in which the patch should 7927 be applied. The default is ``${``\ :term:`S`\ ``}``. 7928 7929 Here are options specific to recipes building code from a revision 7930 control system: 7931 7932 - ``mindate`` --- apply the patch only if 7933 :term:`SRCDATE` is equal to or greater than 7934 ``mindate``. 7935 7936 - ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later 7937 than ``maxdate``. 7938 7939 - ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or 7940 greater than ``minrev``. 7941 7942 - ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later 7943 than ``maxrev``. 7944 7945 - ``rev`` --- apply the patch only if :term:`SRCREV` is equal to 7946 ``rev``. 7947 7948 - ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to 7949 ``rev``. 7950 7951 .. note:: 7952 7953 If you want the build system to pick up files specified through 7954 a :term:`SRC_URI` statement from your append file, you need to be 7955 sure to extend the :term:`FILESPATH` variable by also using the 7956 :term:`FILESEXTRAPATHS` variable from within your append file. 7957 7958 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` 7959 By default, the OpenEmbedded build system automatically detects 7960 whether :term:`SRC_URI` contains files that are machine-specific. If so, 7961 the build system automatically changes :term:`PACKAGE_ARCH`. Setting this 7962 variable to "0" disables this behavior. 7963 7964 :term:`SRCDATE` 7965 The date of the source code used to build the package. This variable 7966 applies only if the source was fetched from a Source Code Manager 7967 (SCM). 7968 7969 :term:`SRCPV` 7970 Returns the version string of the current package. This string is 7971 used to help define the value of :term:`PV`. 7972 7973 The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf`` 7974 configuration file in the :term:`Source Directory` as 7975 follows:: 7976 7977 SRCPV = "${@bb.fetch2.get_srcrev(d)}" 7978 7979 Recipes that need to define :term:`PV` do so with the help of the 7980 :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``) 7981 located in ``meta/recipes-connectivity`` in the Source Directory 7982 defines :term:`PV` as follows:: 7983 7984 PV = "0.12-git${SRCPV}" 7985 7986 :term:`SRCREV` 7987 The revision of the source code used to build the package. This 7988 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note 7989 that if you want to build a fixed revision and you want to avoid 7990 performing a query on the remote repository every time BitBake parses 7991 your recipe, you should specify a :term:`SRCREV` that is a full revision 7992 identifier (e.g. the full SHA hash in git) and not just a tag. 7993 7994 .. note:: 7995 7996 For information on limitations when inheriting the latest revision 7997 of software using :term:`SRCREV`, see the :term:`AUTOREV` variable 7998 description and the 7999 ":ref:`dev-manual/packages:automatically incrementing a package version number`" 8000 section, which is in the Yocto Project Development Tasks Manual. 8001 8002 :term:`SRCTREECOVEREDTASKS` 8003 A list of tasks that are typically not relevant (and therefore skipped) 8004 when building using the :ref:`ref-classes-externalsrc` 8005 class. The default value as set in that class file is the set of tasks 8006 that are rarely needed when using external source:: 8007 8008 SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch" 8009 8010 The notable exception is when processing external kernel source as 8011 defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for 8012 aesthetics):: 8013 8014 SRCTREECOVEREDTASKS += "\ 8015 do_validate_branches \ 8016 do_kernel_configcheck \ 8017 do_kernel_checkout \ 8018 do_fetch \ 8019 do_unpack \ 8020 do_patch \ 8021 " 8022 8023 See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` 8024 variables for more information. 8025 8026 :term:`SSTATE_DIR` 8027 The directory for the shared state cache. 8028 8029 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` 8030 This variable allows to specify indirect dependencies to exclude 8031 from sysroots, for example to avoid the situations when a dependency on 8032 any ``-native`` recipe will pull in all dependencies of that recipe 8033 in the recipe sysroot. This behaviour might not always be wanted, 8034 for example when that ``-native`` recipe depends on build tools 8035 that are not relevant for the current recipe. 8036 8037 This way, irrelevant dependencies are ignored, which could have 8038 prevented the reuse of prebuilt artifacts stored in the Shared 8039 State Cache. 8040 8041 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` is evaluated as two regular 8042 expressions of recipe and dependency to ignore. An example 8043 is the rule in :oe_git:`meta/conf/layer.conf </openembedded-core/tree/meta/conf/layer.conf>`:: 8044 8045 # Nothing needs to depend on libc-initial 8046 # base-passwd/shadow-sysroot don't need their dependencies 8047 SSTATE_EXCLUDEDEPS_SYSROOT += "\ 8048 .*->.*-initial.* \ 8049 .*(base-passwd|shadow-sysroot)->.* \ 8050 " 8051 8052 The ``->`` substring represents the dependency between 8053 the two regular expressions. 8054 8055 :term:`SSTATE_MIRROR_ALLOW_NETWORK` 8056 If set to "1", allows fetches from mirrors that are specified in 8057 :term:`SSTATE_MIRRORS` to work even when 8058 fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to 8059 "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if 8060 you have set :term:`SSTATE_MIRRORS` to point to an internal server for 8061 your shared state cache, but you want to disable any other fetching 8062 from the network. 8063 8064 :term:`SSTATE_MIRRORS` 8065 Configures the OpenEmbedded build system to search other mirror 8066 locations for prebuilt cache data objects before building out the 8067 data. This variable works like fetcher :term:`MIRRORS` 8068 and :term:`PREMIRRORS` and points to the cache 8069 locations to check for the shared state (sstate) objects. 8070 8071 You can specify a filesystem directory or a remote URL such as HTTP 8072 or FTP. The locations you specify need to contain the shared state 8073 cache (sstate-cache) results from previous builds. The sstate-cache 8074 you point to can also be from builds on other machines. 8075 8076 When pointing to sstate build artifacts on another machine that uses 8077 a different GCC version for native builds, you must configure 8078 :term:`SSTATE_MIRRORS` with a regular expression that maps local search 8079 paths to server paths. The paths need to take into account 8080 :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class. 8081 For example, the following maps the local search path ``universal-4.9`` 8082 to the server-provided path server_url_sstate_path:: 8083 8084 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) https://server_url_sstate_path/universal-4.8/\1" 8085 8086 If a mirror uses the same structure as 8087 :term:`SSTATE_DIR`, you need to add "PATH" at the 8088 end as shown in the examples below. The build system substitutes the 8089 correct path within the directory structure:: 8090 8091 SSTATE_MIRRORS ?= "\ 8092 file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \ 8093 file://.* file:///some-local-dir/sstate/PATH" 8094 8095 :term:`SSTATE_SCAN_FILES` 8096 Controls the list of files the OpenEmbedded build system scans for 8097 hardcoded installation paths. The variable uses a space-separated 8098 list of filenames (not paths) with standard wildcard characters 8099 allowed. 8100 8101 During a build, the OpenEmbedded build system creates a shared state 8102 (sstate) object during the first stage of preparing the sysroots. 8103 That object is scanned for hardcoded paths for original installation 8104 locations. The list of files that are scanned for paths is controlled 8105 by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files 8106 they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather 8107 than the variable being comprehensively set. The 8108 :ref:`ref-classes-sstate` class specifies the default list of files. 8109 8110 For details on the process, see the :ref:`ref-classes-staging` class. 8111 8112 :term:`STAGING_BASE_LIBDIR_NATIVE` 8113 Specifies the path to the ``/lib`` subdirectory of the sysroot 8114 directory for the build host. 8115 8116 :term:`STAGING_BASELIBDIR` 8117 Specifies the path to the ``/lib`` subdirectory of the sysroot 8118 directory for the target for which the current recipe is being built 8119 (:term:`STAGING_DIR_HOST`). 8120 8121 :term:`STAGING_BINDIR` 8122 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 8123 directory for the target for which the current recipe is being built 8124 (:term:`STAGING_DIR_HOST`). 8125 8126 :term:`STAGING_BINDIR_CROSS` 8127 Specifies the path to the directory containing binary configuration 8128 scripts. These scripts provide configuration information for other 8129 software that wants to make use of libraries or include files 8130 provided by the software associated with the script. 8131 8132 .. note:: 8133 8134 This style of build configuration has been largely replaced by 8135 ``pkg-config``. Consequently, if ``pkg-config`` is supported by the 8136 library to which you are linking, it is recommended you use 8137 ``pkg-config`` instead of a provided configuration script. 8138 8139 :term:`STAGING_BINDIR_NATIVE` 8140 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 8141 directory for the build host. 8142 8143 :term:`STAGING_DATADIR` 8144 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 8145 directory for the target for which the current recipe is being built 8146 (:term:`STAGING_DIR_HOST`). 8147 8148 :term:`STAGING_DATADIR_NATIVE` 8149 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 8150 directory for the build host. 8151 8152 :term:`STAGING_DIR` 8153 Helps construct the ``recipe-sysroots`` directory, which is used 8154 during packaging. 8155 8156 For information on how staging for recipe-specific sysroots occurs, 8157 see the :ref:`ref-tasks-populate_sysroot` 8158 task, the ":ref:`sdk-manual/extensible:sharing files between recipes`" 8159 section in the Yocto Project Development Tasks Manual, the 8160 ":ref:`overview-manual/concepts:configuration, compilation, and staging`" 8161 section in the Yocto Project Overview and Concepts Manual, and the 8162 :term:`SYSROOT_DIRS` variable. 8163 8164 .. note:: 8165 8166 Recipes should never write files directly under the :term:`STAGING_DIR` 8167 directory because the OpenEmbedded build system manages the 8168 directory automatically. Instead, files should be installed to 8169 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` 8170 task and then the OpenEmbedded build system will stage a subset of 8171 those files into the sysroot. 8172 8173 :term:`STAGING_DIR_HOST` 8174 Specifies the path to the sysroot directory for the system on which 8175 the component is built to run (the system that hosts the component). 8176 For most recipes, this sysroot is the one in which that recipe's 8177 :ref:`ref-tasks-populate_sysroot` task copies 8178 files. Exceptions include ``-native`` recipes, where the 8179 :ref:`ref-tasks-populate_sysroot` task instead uses 8180 :term:`STAGING_DIR_NATIVE`. Depending on 8181 the type of recipe and the build target, :term:`STAGING_DIR_HOST` can 8182 have the following values: 8183 8184 - For recipes building for the target machine, the value is 8185 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}". 8186 8187 - For native recipes building for the build host, the value is empty 8188 given the assumption that when building for the build host, the 8189 build host's own directories should be used. 8190 8191 .. note:: 8192 8193 ``-native`` recipes are not installed into host paths like such 8194 as ``/usr``. Rather, these recipes are installed into 8195 :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes, 8196 standard build environment variables such as 8197 :term:`CPPFLAGS` and 8198 :term:`CFLAGS` are set up so that both host paths 8199 and :term:`STAGING_DIR_NATIVE` are searched for libraries and 8200 headers using, for example, GCC's ``-isystem`` option. 8201 8202 Thus, the emphasis is that the ``STAGING_DIR*`` variables 8203 should be viewed as input variables by tasks such as 8204 :ref:`ref-tasks-configure`, 8205 :ref:`ref-tasks-compile`, and 8206 :ref:`ref-tasks-install`. Having the real system 8207 root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense 8208 for ``-native`` recipes, as they make use of host headers and 8209 libraries. 8210 8211 :term:`STAGING_DIR_NATIVE` 8212 Specifies the path to the sysroot directory used when building 8213 components that run on the build host itself. 8214 8215 :term:`STAGING_DIR_TARGET` 8216 Specifies the path to the sysroot used for the system for which the 8217 component generates code. For components that do not generate code, 8218 which is the majority, :term:`STAGING_DIR_TARGET` is set to match 8219 :term:`STAGING_DIR_HOST`. 8220 8221 Some recipes build binaries that can run on the target system but those 8222 binaries in turn generate code for another different system (e.g. 8223 :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU, 8224 the primary system is referred to as the "HOST" and the secondary, or 8225 different, system is referred to as the "TARGET". Thus, the binaries 8226 run on the "HOST" system and generate binaries for the "TARGET" 8227 system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used 8228 for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the 8229 sysroot used for the "TARGET" system. 8230 8231 :term:`STAGING_ETCDIR_NATIVE` 8232 Specifies the path to the ``/etc`` subdirectory of the sysroot 8233 directory for the build host. 8234 8235 :term:`STAGING_EXECPREFIXDIR` 8236 Specifies the path to the ``/usr`` subdirectory of the sysroot 8237 directory for the target for which the current recipe is being built 8238 (:term:`STAGING_DIR_HOST`). 8239 8240 :term:`STAGING_INCDIR` 8241 Specifies the path to the ``/usr/include`` subdirectory of the 8242 sysroot directory for the target for which the current recipe being 8243 built (:term:`STAGING_DIR_HOST`). 8244 8245 :term:`STAGING_INCDIR_NATIVE` 8246 Specifies the path to the ``/usr/include`` subdirectory of the 8247 sysroot directory for the build host. 8248 8249 :term:`STAGING_KERNEL_BUILDDIR` 8250 Points to the directory containing the kernel build artifacts. 8251 Recipes building software that needs to access kernel build artifacts 8252 (e.g. ``systemtap-uprobes``) can look in the directory specified with 8253 the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts 8254 after the kernel has been built. 8255 8256 :term:`STAGING_KERNEL_DIR` 8257 The directory with kernel headers that are required to build 8258 out-of-tree modules. 8259 8260 :term:`STAGING_LIBDIR` 8261 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 8262 directory for the target for which the current recipe is being built 8263 (:term:`STAGING_DIR_HOST`). 8264 8265 :term:`STAGING_LIBDIR_NATIVE` 8266 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 8267 directory for the build host. 8268 8269 :term:`STAMP` 8270 Specifies the base path used to create recipe stamp files. The path 8271 to an actual stamp file is constructed by evaluating this string and 8272 then appending additional information. Currently, the default 8273 assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf`` 8274 file is:: 8275 8276 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" 8277 8278 For information on how BitBake uses stamp files to determine if a 8279 task should be rerun, see the 8280 ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`" 8281 section in the Yocto Project Overview and Concepts Manual. 8282 8283 See :term:`STAMPS_DIR`, 8284 :term:`MULTIMACH_TARGET_SYS`, 8285 :term:`PN`, :term:`EXTENDPE`, 8286 :term:`PV`, and :term:`PR` for related variable 8287 information. 8288 8289 :term:`STAMPCLEAN` 8290 See :term:`bitbake:STAMPCLEAN` in the BitBake manual. 8291 8292 :term:`STAMPS_DIR` 8293 Specifies the base directory in which the OpenEmbedded build system 8294 places stamps. The default directory is ``${TMPDIR}/stamps``. 8295 8296 :term:`STRIP` 8297 The minimal command and arguments to run ``strip``, which is used to 8298 strip symbols. 8299 8300 :term:`SUMMARY` 8301 The short (72 characters or less) summary of the binary package for 8302 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, 8303 :term:`SUMMARY` is used to define the 8304 :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is 8305 not set in the recipe. 8306 8307 :term:`SVNDIR` 8308 The directory in which files checked out of a Subversion system are 8309 stored. 8310 8311 :term:`SYSLINUX_DEFAULT_CONSOLE` 8312 Specifies the kernel boot default console. If you want to use a 8313 console other than the default, set this variable in your recipe as 8314 follows where "X" is the console number you want to use:: 8315 8316 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" 8317 8318 The :ref:`ref-classes-syslinux` class initially sets 8319 this variable to null but then checks for a value later. 8320 8321 :term:`SYSLINUX_OPTS` 8322 Lists additional options to add to the syslinux file. You need to set 8323 this variable in your recipe. If you want to list multiple options, 8324 separate the options with a semicolon character (``;``). 8325 8326 The :ref:`ref-classes-syslinux` class uses this variable 8327 to create a set of options. 8328 8329 :term:`SYSLINUX_SERIAL` 8330 Specifies the alternate serial port or turns it off. To turn off 8331 serial, set this variable to an empty string in your recipe. The 8332 variable's default value is set in the 8333 :ref:`ref-classes-syslinux` class as follows:: 8334 8335 SYSLINUX_SERIAL ?= "0 115200" 8336 8337 The class checks for and uses the variable as needed. 8338 8339 :term:`SYSLINUX_SERIAL_TTY` 8340 Specifies the alternate console=tty... kernel boot argument. The 8341 variable's default value is set in the :ref:`ref-classes-syslinux` 8342 class as follows:: 8343 8344 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" 8345 8346 The class checks for and uses the variable as needed. 8347 8348 :term:`SYSLINUX_SPLASH` 8349 An ``.LSS`` file used as the background for the VGA boot menu when 8350 you use the boot menu. You need to set this variable in your recipe. 8351 8352 The :ref:`ref-classes-syslinux` class checks for this 8353 variable and if found, the OpenEmbedded build system installs the 8354 splash screen. 8355 8356 :term:`SYSROOT_DESTDIR` 8357 Points to the temporary directory under the work directory (default 8358 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``") 8359 where the files populated into the sysroot are assembled during the 8360 :ref:`ref-tasks-populate_sysroot` task. 8361 8362 :term:`SYSROOT_DIRS` 8363 Directories that are staged into the sysroot by the 8364 :ref:`ref-tasks-populate_sysroot` task. By 8365 default, the following directories are staged:: 8366 8367 SYSROOT_DIRS = " \ 8368 ${includedir} \ 8369 ${libdir} \ 8370 ${base_libdir} \ 8371 ${nonarch_base_libdir} \ 8372 ${datadir} \ 8373 /sysroot-only \ 8374 " 8375 8376 :term:`SYSROOT_DIRS_IGNORE` 8377 Directories that are not staged into the sysroot by the 8378 :ref:`ref-tasks-populate_sysroot` task. You 8379 can use this variable to exclude certain subdirectories of 8380 directories listed in :term:`SYSROOT_DIRS` from 8381 staging. By default, the following directories are not staged:: 8382 8383 SYSROOT_DIRS_IGNORE = " \ 8384 ${mandir} \ 8385 ${docdir} \ 8386 ${infodir} \ 8387 ${datadir}/X11/locale \ 8388 ${datadir}/applications \ 8389 ${datadir}/bash-completion \ 8390 ${datadir}/fonts \ 8391 ${datadir}/gtk-doc/html \ 8392 ${datadir}/installed-tests \ 8393 ${datadir}/locale \ 8394 ${datadir}/pixmaps \ 8395 ${datadir}/terminfo \ 8396 ${libdir}/${BPN}/ptest \ 8397 " 8398 8399 :term:`SYSROOT_DIRS_NATIVE` 8400 Extra directories staged into the sysroot by the 8401 :ref:`ref-tasks-populate_sysroot` task for 8402 ``-native`` recipes, in addition to those specified in 8403 :term:`SYSROOT_DIRS`. By default, the following 8404 extra directories are staged:: 8405 8406 SYSROOT_DIRS_NATIVE = " \ 8407 ${bindir} \ 8408 ${sbindir} \ 8409 ${base_bindir} \ 8410 ${base_sbindir} \ 8411 ${libexecdir} \ 8412 ${sysconfdir} \ 8413 ${localstatedir} \ 8414 " 8415 8416 .. note:: 8417 8418 Programs built by ``-native`` recipes run directly from the sysroot 8419 (:term:`STAGING_DIR_NATIVE`), which is why additional directories 8420 containing program executables and supporting files need to be staged. 8421 8422 :term:`SYSROOT_PREPROCESS_FUNCS` 8423 A list of functions to execute after files are staged into the 8424 sysroot. These functions are usually used to apply additional 8425 processing on the staged files, or to stage additional files. 8426 8427 :term:`SYSTEMD_AUTO_ENABLE` 8428 When inheriting the :ref:`ref-classes-systemd` class, 8429 this variable specifies whether the specified service in 8430 :term:`SYSTEMD_SERVICE` should start 8431 automatically or not. By default, the service is enabled to 8432 automatically start at boot time. The default setting is in the 8433 :ref:`ref-classes-systemd` class as follows:: 8434 8435 SYSTEMD_AUTO_ENABLE ??= "enable" 8436 8437 You can disable the service by setting the variable to "disable". 8438 8439 :term:`SYSTEMD_BOOT_CFG` 8440 When :term:`EFI_PROVIDER` is set to 8441 "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the 8442 configuration file that should be used. By default, the 8443 :ref:`ref-classes-systemd-boot` class sets the 8444 :term:`SYSTEMD_BOOT_CFG` as follows:: 8445 8446 SYSTEMD_BOOT_CFG ?= "${S}/loader.conf" 8447 8448 For information on Systemd-boot, see the `Systemd-boot 8449 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8450 8451 :term:`SYSTEMD_BOOT_ENTRIES` 8452 When :term:`EFI_PROVIDER` is set to 8453 "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a 8454 list of entry files (``*.conf``) to install that contain one boot 8455 entry per file. By default, the :ref:`ref-classes-systemd-boot` class 8456 sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows:: 8457 8458 SYSTEMD_BOOT_ENTRIES ?= "" 8459 8460 For information on Systemd-boot, see the `Systemd-boot 8461 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8462 8463 :term:`SYSTEMD_BOOT_TIMEOUT` 8464 When :term:`EFI_PROVIDER` is set to 8465 "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the 8466 boot menu timeout in seconds. By default, the 8467 :ref:`ref-classes-systemd-boot` class sets the 8468 :term:`SYSTEMD_BOOT_TIMEOUT` as follows:: 8469 8470 SYSTEMD_BOOT_TIMEOUT ?= "10" 8471 8472 For information on Systemd-boot, see the `Systemd-boot 8473 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8474 8475 :term:`SYSTEMD_DEFAULT_TARGET` 8476 8477 This variable allows to set the default unit that systemd starts at bootup. 8478 Usually, this is either ``multi-user.target`` or ``graphical.target``. 8479 This works by creating a ``default.target`` symbolic link to the chosen systemd 8480 target file. 8481 8482 See `systemd's documentation 8483 <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__ 8484 for details. 8485 8486 For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb 8487 </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>` 8488 recipe:: 8489 8490 SYSTEMD_DEFAULT_TARGET = "graphical.target" 8491 8492 :term:`SYSTEMD_PACKAGES` 8493 When inheriting the :ref:`ref-classes-systemd` class, 8494 this variable locates the systemd unit files when they are not found 8495 in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES` 8496 variable is set such that the systemd unit files are assumed to 8497 reside in the recipes main package:: 8498 8499 SYSTEMD_PACKAGES ?= "${PN}" 8500 8501 If these unit files are not in this recipe's main package, you need 8502 to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which 8503 the build system can find the systemd unit files. 8504 8505 :term:`SYSTEMD_SERVICE` 8506 When inheriting the :ref:`ref-classes-systemd` class, 8507 this variable specifies the systemd service name for a package. 8508 8509 Multiple services can be specified, each one separated by a space. 8510 8511 When you specify this file in your recipe, use a package name 8512 override to indicate the package to which the value applies. Here is 8513 an example from the connman recipe:: 8514 8515 SYSTEMD_SERVICE:${PN} = "connman.service" 8516 8517 The package overrides that can be specified are directly related to the value of 8518 :term:`SYSTEMD_PACKAGES`. Overrides not included in :term:`SYSTEMD_PACKAGES` 8519 will be silently ignored. 8520 8521 :term:`SYSVINIT_ENABLED_GETTYS` 8522 When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, 8523 specifies a space-separated list of the virtual terminals that should 8524 run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming 8525 :term:`USE_VT` is not set to "0". 8526 8527 The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only 8528 run a getty on the first virtual terminal). 8529 8530 :term:`T` 8531 This variable points to a directory were BitBake places temporary 8532 files, which consist mostly of task logs and scripts, when building a 8533 particular recipe. The variable is typically set as follows:: 8534 8535 T = "${WORKDIR}/temp" 8536 8537 The :term:`WORKDIR` is the directory into which 8538 BitBake unpacks and builds the recipe. The default ``bitbake.conf`` 8539 file sets this variable. 8540 8541 The :term:`T` variable is not to be confused with the 8542 :term:`TMPDIR` variable, which points to the root of 8543 the directory tree where BitBake places the output of an entire 8544 build. 8545 8546 :term:`TARGET_ARCH` 8547 The target machine's architecture. The OpenEmbedded build system 8548 supports many architectures. Here is an example list of architectures 8549 supported. This list is by no means complete as the architecture is 8550 configurable: 8551 8552 - arm 8553 - i586 8554 - x86_64 8555 - powerpc 8556 - powerpc64 8557 - mips 8558 - mipsel 8559 8560 For additional information on machine architectures, see the 8561 :term:`TUNE_ARCH` variable. 8562 8563 :term:`TARGET_AS_ARCH` 8564 Specifies architecture-specific assembler flags for the target 8565 system. :term:`TARGET_AS_ARCH` is initialized from 8566 :term:`TUNE_ASARGS` by default in the BitBake 8567 configuration file (``meta/conf/bitbake.conf``):: 8568 8569 TARGET_AS_ARCH = "${TUNE_ASARGS}" 8570 8571 :term:`TARGET_CC_ARCH` 8572 Specifies architecture-specific C compiler flags for the target 8573 system. :term:`TARGET_CC_ARCH` is initialized from 8574 :term:`TUNE_CCARGS` by default. 8575 8576 .. note:: 8577 8578 It is a common workaround to append :term:`LDFLAGS` to 8579 :term:`TARGET_CC_ARCH` in recipes that build software for the target that 8580 would not otherwise respect the exported :term:`LDFLAGS` variable. 8581 8582 :term:`TARGET_CC_KERNEL_ARCH` 8583 This is a specific kernel compiler flag for a CPU or Application 8584 Binary Interface (ABI) tune. The flag is used rarely and only for 8585 cases where a userspace :term:`TUNE_CCARGS` is not 8586 compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH` 8587 variable allows the kernel (and associated modules) to use a 8588 different configuration. See the 8589 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the 8590 :term:`Source Directory` for an example. 8591 8592 :term:`TARGET_CFLAGS` 8593 Specifies the flags to pass to the C compiler when building for the 8594 target. When building in the target context, 8595 :term:`CFLAGS` is set to the value of this variable by 8596 default. 8597 8598 Additionally, the SDK's environment setup script sets the :term:`CFLAGS` 8599 variable in the environment to the :term:`TARGET_CFLAGS` value so that 8600 executables built using the SDK also have the flags applied. 8601 8602 :term:`TARGET_CPPFLAGS` 8603 Specifies the flags to pass to the C pre-processor (i.e. to both the 8604 C and the C++ compilers) when building for the target. When building 8605 in the target context, :term:`CPPFLAGS` is set to the 8606 value of this variable by default. 8607 8608 Additionally, the SDK's environment setup script sets the 8609 :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS` 8610 value so that executables built using the SDK also have the flags 8611 applied. 8612 8613 :term:`TARGET_CXXFLAGS` 8614 Specifies the flags to pass to the C++ compiler when building for the 8615 target. When building in the target context, 8616 :term:`CXXFLAGS` is set to the value of this variable 8617 by default. 8618 8619 Additionally, the SDK's environment setup script sets the 8620 :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS` 8621 value so that executables built using the SDK also have the flags 8622 applied. 8623 8624 :term:`TARGET_FPU` 8625 Specifies the method for handling FPU code. For FPU-less targets, 8626 which include most ARM CPUs, the variable must be set to "soft". If 8627 not, the kernel emulation gets used, which results in a performance 8628 penalty. 8629 8630 :term:`TARGET_LD_ARCH` 8631 Specifies architecture-specific linker flags for the target system. 8632 :term:`TARGET_LD_ARCH` is initialized from 8633 :term:`TUNE_LDARGS` by default in the BitBake 8634 configuration file (``meta/conf/bitbake.conf``):: 8635 8636 TARGET_LD_ARCH = "${TUNE_LDARGS}" 8637 8638 :term:`TARGET_LDFLAGS` 8639 Specifies the flags to pass to the linker when building for the 8640 target. When building in the target context, 8641 :term:`LDFLAGS` is set to the value of this variable 8642 by default. 8643 8644 Additionally, the SDK's environment setup script sets the 8645 :term:`LDFLAGS` variable in the environment to the 8646 :term:`TARGET_LDFLAGS` value so that executables built using the SDK also 8647 have the flags applied. 8648 8649 :term:`TARGET_OS` 8650 Specifies the target's operating system. The variable can be set to 8651 "linux" for glibc-based systems (GNU C Library) and to "linux-musl" 8652 for musl libc. For ARM/EABI targets, the possible values are 8653 "linux-gnueabi" and "linux-musleabi". 8654 8655 :term:`TARGET_PREFIX` 8656 Specifies the prefix used for the toolchain binary target tools. 8657 8658 Depending on the type of recipe and the build target, 8659 :term:`TARGET_PREFIX` is set as follows: 8660 8661 - For recipes building for the target machine, the value is 8662 "${:term:`TARGET_SYS`}-". 8663 8664 - For native recipes, the build system sets the variable to the 8665 value of :term:`BUILD_PREFIX`. 8666 8667 - For native SDK recipes (:ref:`ref-classes-nativesdk`), 8668 the build system sets the variable to the value of :term:`SDK_PREFIX`. 8669 8670 :term:`TARGET_SYS` 8671 Specifies the system, including the architecture and the operating 8672 system, for which the build is occurring in the context of the 8673 current recipe. 8674 8675 The OpenEmbedded build system automatically sets this variable based 8676 on :term:`TARGET_ARCH`, 8677 :term:`TARGET_VENDOR`, and 8678 :term:`TARGET_OS` variables. 8679 8680 .. note:: 8681 8682 You do not need to set the :term:`TARGET_SYS` variable yourself. 8683 8684 Consider these two examples: 8685 8686 - Given a native recipe on a 32-bit, x86 machine running Linux, the 8687 value is "i686-linux". 8688 8689 - Given a recipe being built for a little-endian, MIPS target 8690 running Linux, the value might be "mipsel-linux". 8691 8692 :term:`TARGET_VENDOR` 8693 Specifies the name of the target vendor. 8694 8695 :term:`TCLIBC` 8696 Specifies the GNU standard C library (``libc``) variant to use during 8697 the build process. 8698 8699 You can select "glibc", "musl", "newlib", or "baremetal". 8700 8701 :term:`TCLIBCAPPEND` 8702 Specifies a suffix to be appended onto the :term:`TMPDIR` value. The 8703 suffix identifies the ``libc`` variant for building. When you are 8704 building for multiple variants with the same :term:`Build Directory`, 8705 this mechanism ensures that output for different ``libc`` variants is 8706 kept separate to avoid potential conflicts. 8707 8708 In the ``defaultsetup.conf`` file, the default value of 8709 :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky, 8710 which normally only support one ``libc`` variant, set 8711 :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting 8712 in no suffix being applied. 8713 8714 :term:`TCMODE` 8715 Specifies the toolchain selector. :term:`TCMODE` controls the 8716 characteristics of the generated packages and images by telling the 8717 OpenEmbedded build system which toolchain profile to use. By default, 8718 the OpenEmbedded build system builds its own internal toolchain. The 8719 variable's default value is "default", which uses that internal 8720 toolchain. 8721 8722 .. note:: 8723 8724 If :term:`TCMODE` is set to a value other than "default", then it is your 8725 responsibility to ensure that the toolchain is compatible with the 8726 default toolchain. Using older or newer versions of these 8727 components might cause build problems. See 8728 :doc:`Release Information </migration-guides/index>` for your 8729 version of the Yocto Project, to find the specific components with 8730 which the toolchain must be compatible. 8731 8732 The :term:`TCMODE` variable is similar to :term:`TCLIBC`, 8733 which controls the variant of the GNU standard C library (``libc``) 8734 used during the build process: ``glibc`` or ``musl``. 8735 8736 With additional layers, it is possible to use a pre-compiled external 8737 toolchain. One example is the Sourcery G++ Toolchain. The support for 8738 this toolchain resides in the separate Mentor Graphics 8739 ``meta-sourcery`` layer at 8740 https://github.com/MentorEmbedded/meta-sourcery/. 8741 8742 The layer's ``README`` file contains information on how to use the 8743 Sourcery G++ Toolchain as an external toolchain. You will have to 8744 add the layer to your ``bblayers.conf`` file and then set the 8745 :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to 8746 the location of the toolchain. 8747 8748 The fundamentals used for this example apply to any external 8749 toolchain. You can use ``meta-sourcery`` as a template for adding 8750 support for other external toolchains. 8751 8752 In addition to toolchain configuration, you will also need a 8753 corresponding toolchain recipe file. This recipe file needs to package 8754 up any pre-built objects in the toolchain such as ``libgcc``, 8755 ``libstdcc++``, any locales, and ``libc``. 8756 8757 :term:`TC_CXX_RUNTIME` 8758 Specifies the C/C++ STL and runtime variant to use during 8759 the build process. Default value is 'gnu' 8760 8761 You can select "gnu", "llvm", or "android". 8762 8763 :term:`TEMPLATECONF` 8764 Specifies the directory used by the build system to find templates 8765 from which to build the ``bblayers.conf`` and ``local.conf`` files. 8766 Use this variable if you wish to customize such files, and the default 8767 BitBake targets shown when sourcing the ``oe-init-build-env`` script. 8768 8769 For details, see the 8770 :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory` 8771 section in the Yocto Project Development Tasks manual. 8772 8773 .. note:: 8774 8775 You must set this variable in the external environment in order 8776 for it to work. 8777 8778 :term:`TEST_EXPORT_DIR` 8779 The location the OpenEmbedded build system uses to export tests when 8780 the :term:`TEST_EXPORT_ONLY` variable is set 8781 to "1". 8782 8783 The :term:`TEST_EXPORT_DIR` variable defaults to 8784 ``"${TMPDIR}/testimage/${PN}"``. 8785 8786 :term:`TEST_EXPORT_ONLY` 8787 Specifies to export the tests only. Set this variable to "1" if you 8788 do not want to run the tests but you want them to be exported in a 8789 manner that you to run them outside of the build system. 8790 8791 :term:`TEST_LOG_DIR` 8792 Holds the SSH log and the boot log for QEMU machines. The 8793 :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``. 8794 8795 .. note:: 8796 8797 Actual test results reside in the task log (``log.do_testimage``), 8798 which is in the ``${WORKDIR}/temp/`` directory. 8799 8800 :term:`TEST_POWERCONTROL_CMD` 8801 For automated hardware testing, specifies the command to use to 8802 control the power of the target machine under test. Typically, this 8803 command would point to a script that performs the appropriate action 8804 (e.g. interacting with a web-enabled power strip). The specified 8805 command should expect to receive as the last argument "off", "on" or 8806 "cycle" specifying to power off, on, or cycle (power off and then 8807 power on) the device, respectively. 8808 8809 :term:`TEST_POWERCONTROL_EXTRA_ARGS` 8810 For automated hardware testing, specifies additional arguments to 8811 pass through to the command specified in 8812 :term:`TEST_POWERCONTROL_CMD`. Setting 8813 :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you 8814 wish, for example, to separate the machine-specific and 8815 non-machine-specific parts of the arguments. 8816 8817 :term:`TEST_QEMUBOOT_TIMEOUT` 8818 The time in seconds allowed for an image to boot before automated 8819 runtime tests begin to run against an image. The default timeout 8820 period to allow the boot process to reach the login prompt is 500 8821 seconds. You can specify a different value in the ``local.conf`` 8822 file. 8823 8824 For more information on testing images, see the 8825 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" 8826 section in the Yocto Project Development Tasks Manual. 8827 8828 :term:`TEST_SERIALCONTROL_CMD` 8829 For automated hardware testing, specifies the command to use to 8830 connect to the serial console of the target machine under test. This 8831 command simply needs to connect to the serial console and forward 8832 that connection to standard input and output as any normal terminal 8833 program does. 8834 8835 For example, to use the Picocom terminal program on serial device 8836 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: 8837 8838 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" 8839 8840 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` 8841 For automated hardware testing, specifies additional arguments to 8842 pass through to the command specified in 8843 :term:`TEST_SERIALCONTROL_CMD`. Setting 8844 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you 8845 wish, for example, to separate the machine-specific and 8846 non-machine-specific parts of the command. 8847 8848 :term:`TEST_SERVER_IP` 8849 The IP address of the build machine (host machine). This IP address 8850 is usually automatically detected. However, if detection fails, this 8851 variable needs to be set to the IP address of the build machine (i.e. 8852 where the build is taking place). 8853 8854 .. note:: 8855 8856 The :term:`TEST_SERVER_IP` variable is only used for a small number of 8857 tests such as the "dnf" test suite, which needs to download packages 8858 from ``WORKDIR/oe-rootfs-repo``. 8859 8860 :term:`TEST_SUITES` 8861 An ordered list of tests (modules) to run against an image when 8862 performing automated runtime testing. 8863 8864 The OpenEmbedded build system provides a core set of tests that can 8865 be used against images. 8866 8867 .. note:: 8868 8869 Currently, there is only support for running these tests under 8870 QEMU. 8871 8872 Tests include ``ping``, ``ssh``, ``df`` among others. You can add 8873 your own tests to the list of tests by appending :term:`TEST_SUITES` as 8874 follows:: 8875 8876 TEST_SUITES:append = " mytest" 8877 8878 Alternatively, you can 8879 provide the "auto" option to have all applicable tests run against 8880 the image:: 8881 8882 TEST_SUITES:append = " auto" 8883 8884 Using this option causes the 8885 build system to automatically run tests that are applicable to the 8886 image. Tests that are not applicable are skipped. 8887 8888 The order in which tests are run is important. Tests that depend on 8889 another test must appear later in the list than the test on which 8890 they depend. For example, if you append the list of tests with two 8891 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on 8892 ``test_A``, then you must order the tests as follows:: 8893 8894 TEST_SUITES = "test_A test_B" 8895 8896 For more information on testing images, see the 8897 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" 8898 section in the Yocto Project Development Tasks Manual. 8899 8900 :term:`TEST_TARGET` 8901 Specifies the target controller to use when running tests against a 8902 test image. The default controller to use is "qemu":: 8903 8904 TEST_TARGET = "qemu" 8905 8906 A target controller is a class that defines how an image gets 8907 deployed on a target and how a target is started. A layer can extend 8908 the controllers by adding a module in the layer's 8909 ``/lib/oeqa/controllers`` directory and by inheriting the 8910 ``BaseTarget`` class, which is an abstract class that cannot be used 8911 as a value of :term:`TEST_TARGET`. 8912 8913 You can provide the following arguments with :term:`TEST_TARGET`: 8914 8915 - *"qemu":* Boots a QEMU image and runs the tests. See the 8916 ":ref:`dev-manual/runtime-testing:enabling runtime tests on qemu`" section 8917 in the Yocto Project Development Tasks Manual for more 8918 information. 8919 8920 - *"simpleremote":* Runs the tests on target hardware that is 8921 already up and running. The hardware can be on the network or it 8922 can be a device running an image on QEMU. You must also set 8923 :term:`TEST_TARGET_IP` when you use 8924 "simpleremote". 8925 8926 .. note:: 8927 8928 This argument is defined in 8929 ``meta/lib/oeqa/controllers/simpleremote.py``. 8930 8931 For information on running tests on hardware, see the 8932 ":ref:`dev-manual/runtime-testing:enabling runtime tests on hardware`" 8933 section in the Yocto Project Development Tasks Manual. 8934 8935 :term:`TEST_TARGET_IP` 8936 The IP address of your hardware under test. The :term:`TEST_TARGET_IP` 8937 variable has no effect when :term:`TEST_TARGET` is 8938 set to "qemu". 8939 8940 When you specify the IP address, you can also include a port. Here is 8941 an example:: 8942 8943 TEST_TARGET_IP = "192.168.1.4:2201" 8944 8945 Specifying a port is 8946 useful when SSH is started on a non-standard port or in cases when 8947 your hardware under test is behind a firewall or network that is not 8948 directly accessible from your host and you need to do port address 8949 translation. 8950 8951 :term:`TESTIMAGE_AUTO` 8952 Automatically runs the series of automated tests for images when an 8953 image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes 8954 any image that successfully builds to automatically boot under QEMU. 8955 Using the variable also adds in dependencies so that any SDK for 8956 which testing is requested is automatically built first. 8957 8958 These tests are written in Python making use of the ``unittest`` 8959 module, and the majority of them run commands on the target system 8960 over ``ssh``. You can set this variable to "1" in your ``local.conf`` 8961 file in the :term:`Build Directory` to have the 8962 OpenEmbedded build system automatically run these tests after an 8963 image successfully builds: 8964 8965 TESTIMAGE_AUTO = "1" 8966 8967 For more information 8968 on enabling, running, and writing these tests, see the 8969 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" 8970 section in the Yocto Project Development Tasks Manual and the 8971 ":ref:`ref-classes-testimage`" section. 8972 8973 :term:`THISDIR` 8974 The directory in which the file BitBake is currently parsing is 8975 located. Do not manually set this variable. 8976 8977 :term:`TIME` 8978 The time the build was started. Times appear using the hour, minute, 8979 and second (HMS) format (e.g. "140159" for one minute and fifty-nine 8980 seconds past 1400 hours). 8981 8982 :term:`TMPDIR` 8983 This variable is the base directory the OpenEmbedded build system 8984 uses for all build output and intermediate files (other than the 8985 shared state cache). By default, the :term:`TMPDIR` variable points to 8986 ``tmp`` within the :term:`Build Directory`. 8987 8988 If you want to establish this directory in a location other than the 8989 default, you can uncomment and edit the following statement in the 8990 ``conf/local.conf`` file in the :term:`Source Directory`:: 8991 8992 #TMPDIR = "${TOPDIR}/tmp" 8993 8994 An example use for this scenario is to set :term:`TMPDIR` to a local disk, 8995 which does not use NFS, while having the :term:`Build Directory` use NFS. 8996 8997 The filesystem used by :term:`TMPDIR` must have standard filesystem 8998 semantics (i.e. mixed-case files are unique, POSIX file locking, and 8999 persistent inodes). Due to various issues with NFS and bugs in some 9000 implementations, NFS does not meet this minimum requirement. 9001 Consequently, :term:`TMPDIR` cannot be on NFS. 9002 9003 :term:`TOOLCHAIN_HOST_TASK` 9004 This variable lists packages the OpenEmbedded build system uses when 9005 building an SDK, which contains a cross-development environment. The 9006 packages specified by this variable are part of the toolchain set 9007 that runs on the :term:`SDKMACHINE`, and each 9008 package should usually have the prefix ``nativesdk-``. For example, 9009 consider the following command when building an SDK:: 9010 9011 $ bitbake -c populate_sdk imagename 9012 9013 In this case, a default list of packages is 9014 set in this variable, but you can add additional packages to the 9015 list. See the 9016 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section 9017 in the Yocto Project Application Development and the Extensible 9018 Software Development Kit (eSDK) manual for more information. 9019 9020 For background information on cross-development toolchains in the 9021 Yocto Project development environment, see the 9022 ":ref:`sdk-manual/intro:the cross-development toolchain`" 9023 section in the Yocto Project Overview and Concepts Manual. For 9024 information on setting up a cross-development environment, see the 9025 :doc:`/sdk-manual/index` manual. 9026 9027 Note that this variable applies to building an SDK, not an eSDK, 9028 in which case the :term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be 9029 used instead. 9030 9031 :term:`TOOLCHAIN_HOST_TASK_ESDK` 9032 This variable allows to extend what is installed in the host 9033 portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK` 9034 applying to SDKs. 9035 9036 :term:`TOOLCHAIN_OUTPUTNAME` 9037 This variable defines the name used for the toolchain output. The 9038 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets 9039 the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:: 9040 9041 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" 9042 9043 See 9044 the :term:`SDK_NAME` and 9045 :term:`SDK_VERSION` variables for additional 9046 information. 9047 9048 :term:`TOOLCHAIN_TARGET_TASK` 9049 This variable lists packages the OpenEmbedded build system uses when 9050 it creates the target part of an SDK (i.e. the part built for the 9051 target hardware), which includes libraries and headers. Use this 9052 variable to add individual packages to the part of the SDK that runs 9053 on the target. See the 9054 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section 9055 in the Yocto Project Application Development and the Extensible 9056 Software Development Kit (eSDK) manual for more information. 9057 9058 For background information on cross-development toolchains in the 9059 Yocto Project development environment, see the 9060 ":ref:`sdk-manual/intro:the cross-development toolchain`" 9061 section in the Yocto Project Overview and Concepts Manual. For 9062 information on setting up a cross-development environment, see the 9063 :doc:`/sdk-manual/index` manual. 9064 9065 :term:`TOPDIR` 9066 See :term:`bitbake:TOPDIR` in the BitBake manual. 9067 9068 :term:`TRANSLATED_TARGET_ARCH` 9069 A sanitized version of :term:`TARGET_ARCH`. This 9070 variable is used where the architecture is needed in a value where 9071 underscores are not allowed, for example within package filenames. In 9072 this case, dash characters replace any underscore characters used in 9073 :term:`TARGET_ARCH`. 9074 9075 Do not edit this variable. 9076 9077 :term:`TUNE_ARCH` 9078 The GNU canonical architecture for a specific architecture (i.e. 9079 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses 9080 this value to setup configuration. 9081 9082 :term:`TUNE_ARCH` definitions are specific to a given architecture. The 9083 definitions can be a single static definition, or can be dynamically 9084 adjusted. You can see details for a given CPU family by looking at 9085 the architecture's ``README`` file. For example, the 9086 ``meta/conf/machine/include/mips/README`` file in the 9087 :term:`Source Directory` provides information for 9088 :term:`TUNE_ARCH` specific to the ``mips`` architecture. 9089 9090 :term:`TUNE_ARCH` is tied closely to 9091 :term:`TARGET_ARCH`, which defines the target 9092 machine's architecture. The BitBake configuration file 9093 (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:: 9094 9095 TARGET_ARCH = "${TUNE_ARCH}" 9096 9097 The following list, which is by no means complete since architectures 9098 are configurable, shows supported machine architectures: 9099 9100 - arm 9101 - i586 9102 - x86_64 9103 - powerpc 9104 - powerpc64 9105 - mips 9106 - mipsel 9107 9108 :term:`TUNE_ASARGS` 9109 Specifies architecture-specific assembler flags for the target 9110 system. The set of flags is based on the selected tune features. 9111 :term:`TUNE_ASARGS` is set using the tune include files, which are 9112 typically under ``meta/conf/machine/include/`` and are influenced 9113 through :term:`TUNE_FEATURES`. For example, the 9114 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9115 for the x86 architecture as follows:: 9116 9117 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" 9118 9119 .. note:: 9120 9121 Board Support Packages (BSPs) select the tune. The selected tune, 9122 in turn, affects the tune variables themselves (i.e. the tune can 9123 supply its own set of flags). 9124 9125 :term:`TUNE_CCARGS` 9126 Specifies architecture-specific C compiler flags for the target 9127 system. The set of flags is based on the selected tune features. 9128 :term:`TUNE_CCARGS` is set using the tune include files, which are 9129 typically under ``meta/conf/machine/include/`` and are influenced 9130 through :term:`TUNE_FEATURES`. 9131 9132 .. note:: 9133 9134 Board Support Packages (BSPs) select the tune. The selected tune, 9135 in turn, affects the tune variables themselves (i.e. the tune can 9136 supply its own set of flags). 9137 9138 :term:`TUNE_FEATURES` 9139 Features used to "tune" a compiler for optimal use given a specific 9140 processor. The features are defined within the tune files and allow 9141 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on 9142 the features. 9143 9144 The OpenEmbedded build system verifies the features to be sure they 9145 are not conflicting and that they are supported. 9146 9147 The BitBake configuration file (``meta/conf/bitbake.conf``) defines 9148 :term:`TUNE_FEATURES` as follows:: 9149 9150 TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}" 9151 9152 See the :term:`DEFAULTTUNE` variable for more information. 9153 9154 :term:`TUNE_LDARGS` 9155 Specifies architecture-specific linker flags for the target system. 9156 The set of flags is based on the selected tune features. 9157 :term:`TUNE_LDARGS` is set using the tune include files, which are 9158 typically under ``meta/conf/machine/include/`` and are influenced 9159 through :term:`TUNE_FEATURES`. For example, the 9160 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9161 for the x86 architecture as follows:: 9162 9163 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" 9164 9165 .. note:: 9166 9167 Board Support Packages (BSPs) select the tune. The selected tune, 9168 in turn, affects the tune variables themselves (i.e. the tune can 9169 supply its own set of flags). 9170 9171 :term:`TUNE_PKGARCH` 9172 The package architecture understood by the packaging system to define 9173 the architecture, ABI, and tuning of output packages. The specific 9174 tune is defined using the "_tune" override as follows:: 9175 9176 TUNE_PKGARCH:tune-tune = "tune" 9177 9178 These tune-specific package architectures are defined in the machine 9179 include files. Here is an example of the "core2-32" tuning as used in 9180 the ``meta/conf/machine/include/x86/tune-core2.inc`` file:: 9181 9182 TUNE_PKGARCH:tune-core2-32 = "core2-32" 9183 9184 :term:`TUNECONFLICTS[feature]` 9185 Specifies CPU or Application Binary Interface (ABI) tuning features 9186 that conflict with feature. 9187 9188 Known tuning conflicts are specified in the machine include files in 9189 the :term:`Source Directory`. Here is an example from 9190 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file 9191 that lists the "o32" and "n64" features as conflicting with the "n32" 9192 feature:: 9193 9194 TUNECONFLICTS[n32] = "o32 n64" 9195 9196 :term:`TUNEVALID[feature]` 9197 Specifies a valid CPU or Application Binary Interface (ABI) tuning 9198 feature. The specified feature is stored as a flag. Valid features 9199 are specified in the machine include files (e.g. 9200 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example 9201 from that file:: 9202 9203 TUNEVALID[bigendian] = "Enable big-endian mode." 9204 9205 See the machine include files in the :term:`Source Directory` 9206 for these features. 9207 9208 :term:`UBOOT_CONFIG` 9209 Configures the :term:`UBOOT_MACHINE` and can 9210 also define :term:`IMAGE_FSTYPES` for individual 9211 cases. 9212 9213 Following is an example from the ``meta-fsl-arm`` layer. :: 9214 9215 UBOOT_CONFIG ??= "sd" 9216 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" 9217 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" 9218 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" 9219 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" 9220 9221 In this example, "sd" is selected as the configuration of the possible four for the 9222 :term:`UBOOT_MACHINE`. The "sd" configuration defines 9223 "mx6qsabreauto_config" as the value for :term:`UBOOT_MACHINE`, while the 9224 "sdcard" specifies the :term:`IMAGE_FSTYPES` to use for the U-Boot image. 9225 9226 For more information on how the :term:`UBOOT_CONFIG` is handled, see the 9227 :ref:`ref-classes-uboot-config` class. 9228 9229 :term:`UBOOT_DTB_LOADADDRESS` 9230 Specifies the load address for the dtb image used by U-Boot. During FIT 9231 image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in 9232 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be 9233 used in creating the dtb sections of Image Tree Source for the FIT image. 9234 9235 :term:`UBOOT_DTBO_LOADADDRESS` 9236 Specifies the load address for the dtbo image used by U-Boot. During FIT 9237 image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in 9238 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be 9239 used in creating the dtbo sections of Image Tree Source for the FIT image. 9240 9241 :term:`UBOOT_ENTRYPOINT` 9242 Specifies the entry point for the U-Boot image. During U-Boot image 9243 creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a 9244 command-line parameter to the ``uboot-mkimage`` utility. 9245 9246 To pass a 64 bit address for FIT image creation, you will need to set: 9247 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. 9248 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. 9249 9250 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9251 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, 9252 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9253 classes. 9254 9255 :term:`UBOOT_FIT_ADDRESS_CELLS` 9256 Specifies the value of the ``#address-cells`` value for the 9257 description of the U-Boot FIT image. 9258 9259 The default value is set to "1" by the :ref:`ref-classes-uboot-sign` 9260 class, which corresponds to 32 bit addresses. 9261 9262 For platforms that need to set 64 bit addresses in 9263 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to 9264 set this value to "2", as two 32 bit values (cells) will be needed 9265 to represent such addresses. 9266 9267 Here is an example setting "0x400000000" as a load address:: 9268 9269 UBOOT_FIT_ADDRESS_CELLS = "2" 9270 UBOOT_LOADADDRESS= "0x04 0x00000000" 9271 9272 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. 9273 9274 :term:`UBOOT_FIT_DESC` 9275 Specifies the description string encoded into a U-Boot fitImage. The default 9276 value is set by the :ref:`ref-classes-uboot-sign` class as follows:: 9277 9278 UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" 9279 9280 :term:`UBOOT_FIT_GENERATE_KEYS` 9281 Decides whether to generate the keys for signing the U-Boot fitImage if 9282 they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`. 9283 The default value is "0". 9284 9285 Enable this as follows:: 9286 9287 UBOOT_FIT_GENERATE_KEYS = "1" 9288 9289 This variable is used in the :ref:`ref-classes-uboot-sign` class. 9290 9291 :term:`UBOOT_FIT_HASH_ALG` 9292 Specifies the hash algorithm used in creating the U-Boot FIT Image. 9293 It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign` 9294 class. 9295 9296 :term:`UBOOT_FIT_KEY_GENRSA_ARGS` 9297 Arguments to ``openssl genrsa`` for generating a RSA private key for 9298 signing the U-Boot FIT image. The default value of this variable 9299 is set to "-F4" by the :ref:`ref-classes-uboot-sign` class. 9300 9301 :term:`UBOOT_FIT_KEY_REQ_ARGS` 9302 Arguments to ``openssl req`` for generating a certificate for signing 9303 the U-Boot FIT image. The default value is "-batch -new" by the 9304 :ref:`ref-classes-uboot-sign` class, "batch" for 9305 non interactive mode and "new" for generating new keys. 9306 9307 :term:`UBOOT_FIT_KEY_SIGN_PKCS` 9308 Format for the public key certificate used for signing the U-Boot FIT 9309 image. The default value is set to "x509" by the 9310 :ref:`ref-classes-uboot-sign` class. 9311 9312 :term:`UBOOT_FIT_SIGN_ALG` 9313 Specifies the signature algorithm used in creating the U-Boot FIT Image. 9314 This variable is set by default to "rsa2048" by the 9315 :ref:`ref-classes-uboot-sign` class. 9316 9317 :term:`UBOOT_FIT_SIGN_NUMBITS` 9318 Size of the private key used in signing the U-Boot FIT image, in number 9319 of bits. The default value for this variable is set to "2048" 9320 by the :ref:`ref-classes-uboot-sign` class. 9321 9322 :term:`UBOOT_FITIMAGE_ENABLE` 9323 This variable allows to generate a FIT image for U-Boot, which is one 9324 of the ways to implement a verified boot process. 9325 9326 Its default value is "0", so set it to "1" to enable this functionality:: 9327 9328 UBOOT_FITIMAGE_ENABLE = "1" 9329 9330 See the :ref:`ref-classes-uboot-sign` class for details. 9331 9332 :term:`UBOOT_LOADADDRESS` 9333 Specifies the load address for the U-Boot image. During U-Boot image 9334 creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a 9335 command-line parameter to the ``uboot-mkimage`` utility. 9336 9337 To pass a 64 bit address, you will also need to set: 9338 9339 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. 9340 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. 9341 9342 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9343 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, 9344 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9345 classes. 9346 9347 :term:`UBOOT_LOCALVERSION` 9348 Appends a string to the name of the local version of the U-Boot 9349 image. For example, assuming the version of the U-Boot image built 9350 was "2013.10", the full version string reported by U-Boot would be 9351 "2013.10-yocto" given the following statement:: 9352 9353 UBOOT_LOCALVERSION = "-yocto" 9354 9355 :term:`UBOOT_MACHINE` 9356 Specifies the value passed on the ``make`` command line when building 9357 a U-Boot image. The value indicates the target platform 9358 configuration. You typically set this variable from the machine 9359 configuration file (i.e. ``conf/machine/machine_name.conf``). 9360 9361 Please see the "Selection of Processor Architecture and Board Type" 9362 section in the U-Boot README for valid values for this variable. 9363 9364 :term:`UBOOT_MAKE_TARGET` 9365 Specifies the target called in the ``Makefile``. The default target 9366 is "all". 9367 9368 :term:`UBOOT_MKIMAGE` 9369 Specifies the name of the mkimage command as used by the 9370 :ref:`ref-classes-kernel-fitimage` class to assemble 9371 the FIT image. This can be used to substitute an alternative command, wrapper 9372 script or function if desired. The default is "uboot-mkimage". 9373 9374 :term:`UBOOT_MKIMAGE_DTCOPTS` 9375 Options for the device tree compiler passed to ``mkimage -D`` feature 9376 while creating a FIT image with the :ref:`ref-classes-kernel-fitimage` 9377 class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the 9378 :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option 9379 to ``mkimage``. 9380 9381 This variable is also used by the :ref:`ref-classes-uboot-sign` class. 9382 9383 :term:`UBOOT_MKIMAGE_KERNEL_TYPE` 9384 Specifies the type argument for the kernel as passed to ``uboot-mkimage``. 9385 The default value is "kernel". 9386 9387 :term:`UBOOT_MKIMAGE_SIGN` 9388 Specifies the name of the mkimage command as used by the 9389 :ref:`ref-classes-kernel-fitimage` class to sign 9390 the FIT image after it has been assembled (if enabled). This can be used 9391 to substitute an alternative command, wrapper script or function if 9392 desired. The default is "${:term:`UBOOT_MKIMAGE`}". 9393 9394 :term:`UBOOT_MKIMAGE_SIGN_ARGS` 9395 Optionally specifies additional arguments for the 9396 :ref:`ref-classes-kernel-fitimage` class to pass to the 9397 mkimage command when signing the FIT image. 9398 9399 :term:`UBOOT_RD_ENTRYPOINT` 9400 Specifies the entrypoint for the RAM disk image. During FIT image 9401 creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in 9402 :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be 9403 used in creating the Image Tree Source for the FIT image. 9404 9405 :term:`UBOOT_RD_LOADADDRESS` 9406 Specifies the load address for the RAM disk image. During FIT image 9407 creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in 9408 :ref:`ref-classes-kernel-fitimage` class to specify the load address to 9409 be used in creating the Image Tree Source for the FIT image. 9410 9411 :term:`UBOOT_SIGN_ENABLE` 9412 Enable signing of FIT image. The default value is "0". 9413 9414 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9415 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9416 classes. 9417 9418 :term:`UBOOT_SIGN_KEYDIR` 9419 Location of the directory containing the RSA key and certificate used for 9420 signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and 9421 :ref:`ref-classes-uboot-sign` classes. 9422 9423 :term:`UBOOT_SIGN_KEYNAME` 9424 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class 9425 for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR` 9426 directory. If we have for example a ``dev.key`` key and a ``dev.crt`` 9427 certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will 9428 have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``. 9429 9430 :term:`UBOOT_SUFFIX` 9431 Points to the generated U-Boot extension. For example, ``u-boot.sb`` 9432 has a ``.sb`` extension. 9433 9434 The default U-Boot extension is ``.bin`` 9435 9436 :term:`UBOOT_TARGET` 9437 Specifies the target used for building U-Boot. The target is passed 9438 directly as part of the "make" command (e.g. SPL and AIS). If you do 9439 not specifically set this variable, the OpenEmbedded build process 9440 passes and uses "all" for the target during the U-Boot building 9441 process. 9442 9443 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` 9444 Specifies a list of options that, if reported by the configure script 9445 as being invalid, should not generate a warning during the 9446 :ref:`ref-tasks-configure` task. Normally, invalid 9447 configure options are simply not passed to the configure script (e.g. 9448 should be removed from :term:`EXTRA_OECONF` or 9449 :term:`PACKAGECONFIG_CONFARGS`). 9450 However, there are common options that are passed to all 9451 configure scripts at a class level, but might not be valid for some 9452 configure scripts. Therefore warnings about these options are useless. 9453 For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`. 9454 9455 The configure arguments check that uses 9456 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the 9457 :ref:`ref-classes-insane` class and is only enabled if the 9458 recipe inherits the :ref:`ref-classes-autotools` class. 9459 9460 :term:`UPDATERCPN` 9461 For recipes inheriting the 9462 :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN` 9463 specifies the package that contains the initscript that is enabled. 9464 9465 The default value is "${PN}". Given that almost all recipes that 9466 install initscripts package them in the main package for the recipe, 9467 you rarely need to set this variable in individual recipes. 9468 9469 :term:`UPSTREAM_CHECK_COMMITS` 9470 You can perform a per-recipe check for what the latest upstream 9471 source code version is by calling ``devtool latest-version recipe``. If 9472 the recipe source code is provided from Git repositories, but 9473 releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS` 9474 to ``1`` in the recipe, and the OpenEmbedded build system 9475 will compare the latest commit with the one currently specified 9476 by the recipe (:term:`SRCREV`):: 9477 9478 UPSTREAM_CHECK_COMMITS = "1" 9479 9480 :term:`UPSTREAM_CHECK_GITTAGREGEX` 9481 You can perform a per-recipe check for what the latest upstream 9482 source code version is by calling ``devtool latest-version recipe``. If 9483 the recipe source code is provided from Git repositories, the 9484 OpenEmbedded build system determines the latest upstream version by 9485 picking the latest tag from the list of all repository tags. 9486 9487 You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a 9488 regular expression to filter only the relevant tags should the 9489 default filter not work correctly:: 9490 9491 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" 9492 9493 :term:`UPSTREAM_CHECK_REGEX` 9494 Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different 9495 regular expression instead of the default one when the package 9496 checking system is parsing the page found using 9497 :term:`UPSTREAM_CHECK_URI`:: 9498 9499 UPSTREAM_CHECK_REGEX = "package_regex" 9500 9501 :term:`UPSTREAM_CHECK_URI` 9502 You can perform a per-recipe check for what the latest upstream 9503 source code version is by calling ``devtool latest-version recipe``. If 9504 the source code is provided from tarballs, the latest version is 9505 determined by fetching the directory listing where the tarball is and 9506 attempting to find a later tarball. When this approach does not work, 9507 you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that 9508 contains the link to the latest tarball:: 9509 9510 UPSTREAM_CHECK_URI = "recipe_url" 9511 9512 :term:`UPSTREAM_VERSION_UNKNOWN` 9513 You can perform a per-recipe check for what the latest upstream 9514 source code version is by calling ``devtool latest-version recipe``. 9515 If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`, 9516 :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in 9517 the recipe allows to determine what the latest upstream version is, 9518 you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe 9519 to acknowledge that the check cannot be performed:: 9520 9521 UPSTREAM_VERSION_UNKNOWN = "1" 9522 9523 :term:`USE_DEVFS` 9524 Determines if ``devtmpfs`` is used for ``/dev`` population. The 9525 default value used for :term:`USE_DEVFS` is "1" when no value is 9526 specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a 9527 statically populated ``/dev`` directory. 9528 9529 See the ":ref:`dev-manual/device-manager:selecting a device manager`" section in 9530 the Yocto Project Development Tasks Manual for information on how to 9531 use this variable. 9532 9533 :term:`USE_VT` 9534 When using 9535 :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, 9536 determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>` 9537 on any virtual terminals in order to enable logging in through those 9538 terminals. 9539 9540 The default value used for :term:`USE_VT` is "1" when no default value is 9541 specifically set. Typically, you would set :term:`USE_VT` to "0" in the 9542 machine configuration file for machines that do not have a graphical 9543 display attached and therefore do not need virtual terminal 9544 functionality. 9545 9546 :term:`USER_CLASSES` 9547 A list of classes to globally inherit. These classes are used by the 9548 OpenEmbedded build system to enable extra features. 9549 9550 Classes inherited using :term:`USER_CLASSES` must be located in the 9551 ``classes-global/`` or ``classes/`` subdirectories. 9552 9553 The default list is set in your ``local.conf`` file:: 9554 9555 USER_CLASSES ?= "buildstats" 9556 9557 For more information, see 9558 ``meta-poky/conf/templates/default/local.conf.sample`` in the 9559 :term:`Source Directory`. 9560 9561 :term:`USERADD_ERROR_DYNAMIC` 9562 If set to ``error``, forces the OpenEmbedded build system to produce 9563 an error if the user identification (``uid``) and group 9564 identification (``gid``) values are not defined in any of the files 9565 listed in :term:`USERADD_UID_TABLES` and 9566 :term:`USERADD_GID_TABLES`. If set to 9567 ``warn``, a warning will be issued instead. 9568 9569 The default behavior for the build system is to dynamically apply 9570 ``uid`` and ``gid`` values. Consequently, the 9571 :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan 9572 on using statically assigned ``gid`` and ``uid`` values, you should 9573 set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` 9574 file as follows:: 9575 9576 USERADD_ERROR_DYNAMIC = "error" 9577 9578 Overriding the 9579 default behavior implies you are going to also take steps to set 9580 static ``uid`` and ``gid`` values through use of the 9581 :term:`USERADDEXTENSION`, 9582 :term:`USERADD_UID_TABLES`, and 9583 :term:`USERADD_GID_TABLES` variables. 9584 9585 .. note:: 9586 9587 There is a difference in behavior between setting 9588 :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``. 9589 When it is set to ``warn``, the build system will report a warning for 9590 every undefined ``uid`` and ``gid`` in any recipe. But when it is set 9591 to ``error``, it will only report errors for recipes that are actually 9592 built. 9593 This saves you from having to add static IDs for recipes that you 9594 know will never be built. 9595 9596 :term:`USERADD_GID_TABLES` 9597 Specifies a password file to use for obtaining static group 9598 identification (``gid``) values when the OpenEmbedded build system 9599 adds a group to the system during package installation. 9600 9601 When applying static group identification (``gid``) values, the 9602 OpenEmbedded build system looks in :term:`BBPATH` for a 9603 ``files/group`` file and then applies those ``uid`` values. Set the 9604 variable as follows in your ``local.conf`` file:: 9605 9606 9607 USERADD_GID_TABLES = "files/group" 9608 9609 .. note:: 9610 9611 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" 9612 causes the build system to use static ``gid`` values. 9613 9614 :term:`USERADD_PACKAGES` 9615 When inheriting the :ref:`ref-classes-useradd` class, 9616 this variable specifies the individual packages within the recipe 9617 that require users and/or groups to be added. 9618 9619 You must set this variable if the recipe inherits the class. For 9620 example, the following enables adding a user for the main package in 9621 a recipe:: 9622 9623 USERADD_PACKAGES = "${PN}" 9624 9625 .. note:: 9626 9627 It follows that if you are going to use the :term:`USERADD_PACKAGES` 9628 variable, you need to set one or more of the :term:`USERADD_PARAM`, 9629 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. 9630 9631 :term:`USERADD_PARAM` 9632 When inheriting the :ref:`ref-classes-useradd` class, 9633 this variable specifies for a package what parameters should pass to 9634 the ``useradd`` command if you add a user to the system when the 9635 package is installed. 9636 9637 Here is an example from the ``dbus`` recipe:: 9638 9639 USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \ 9640 --no-create-home --shell /bin/false \ 9641 --user-group messagebus" 9642 9643 For information on the 9644 standard Linux shell command ``useradd``, see 9645 https://linux.die.net/man/8/useradd. 9646 9647 :term:`USERADD_UID_TABLES` 9648 Specifies a password file to use for obtaining static user 9649 identification (``uid``) values when the OpenEmbedded build system 9650 adds a user to the system during package installation. 9651 9652 When applying static user identification (``uid``) values, the 9653 OpenEmbedded build system looks in :term:`BBPATH` for a 9654 ``files/passwd`` file and then applies those ``uid`` values. Set the 9655 variable as follows in your ``local.conf`` file:: 9656 9657 USERADD_UID_TABLES = "files/passwd" 9658 9659 .. note:: 9660 9661 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" 9662 causes the build system to use static ``uid`` values. 9663 9664 :term:`USERADDEXTENSION` 9665 When set to "useradd-staticids", causes the OpenEmbedded build system 9666 to base all user and group additions on a static ``passwd`` and 9667 ``group`` files found in :term:`BBPATH`. 9668 9669 To use static user identification (``uid``) and group identification 9670 (``gid``) values, set the variable as follows in your ``local.conf`` 9671 file: USERADDEXTENSION = "useradd-staticids" 9672 9673 .. note:: 9674 9675 Setting this variable to use static ``uid`` and ``gid`` 9676 values causes the OpenEmbedded build system to employ the 9677 :ref:`ref-classes-useradd` class. 9678 9679 If you use static ``uid`` and ``gid`` information, you must also 9680 specify the ``files/passwd`` and ``files/group`` files by setting the 9681 :term:`USERADD_UID_TABLES` and 9682 :term:`USERADD_GID_TABLES` variables. 9683 Additionally, you should also set the 9684 :term:`USERADD_ERROR_DYNAMIC` variable. 9685 9686 :term:`VOLATILE_LOG_DIR` 9687 Specifies the persistence of the target's ``/var/log`` directory, 9688 which is used to house postinstall target log files. 9689 9690 By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the 9691 file is not persistent. You can override this setting by setting the 9692 variable to "no" to make the log directory persistent. 9693 9694 :term:`VOLATILE_TMP_DIR` 9695 Specifies the persistence of the target's ``/tmp`` directory. 9696 9697 By default, :term:`VOLATILE_TMP_DIR` is set to "yes", in which case 9698 ``/tmp`` links to a directory which resides in RAM in a ``tmpfs`` 9699 filesystem. 9700 9701 If instead, you want the ``/tmp`` directory to be persistent, set the 9702 variable to "no" to make it a regular directory in the root filesystem. 9703 9704 This supports both sysvinit and systemd based systems. 9705 9706 :term:`WARN_QA` 9707 Specifies the quality assurance checks whose failures are reported as 9708 warnings by the OpenEmbedded build system. You set this variable in 9709 your distribution configuration file. For a list of the checks you 9710 can control with this variable, see the 9711 ":ref:`ref-classes-insane`" section. 9712 9713 :term:`WATCHDOG_TIMEOUT` 9714 Specifies the timeout in seconds used by the ``watchdog`` recipe and 9715 also by ``systemd`` during reboot. The default is 60 seconds. 9716 9717 :term:`WIRELESS_DAEMON` 9718 For ``connman`` and ``packagegroup-base``, specifies the wireless 9719 daemon to use. The default is "wpa-supplicant" (note that the value 9720 uses a dash and not an underscore). 9721 9722 :term:`WKS_FILE` 9723 Specifies the location of the Wic kickstart file that is used by the 9724 OpenEmbedded build system to create a partitioned image 9725 (``image.wic``). For information on how to create a partitioned 9726 image, see the 9727 ":ref:`dev-manual/wic:creating partitioned images using wic`" 9728 section in the Yocto Project Development Tasks Manual. For details on 9729 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. 9730 9731 :term:`WKS_FILE_DEPENDS` 9732 When placed in the recipe that builds your image, this variable lists 9733 build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only 9734 applicable when Wic images are active (i.e. when 9735 :term:`IMAGE_FSTYPES` contains entries related 9736 to Wic). If your recipe does not create Wic images, the variable has 9737 no effect. 9738 9739 The :term:`WKS_FILE_DEPENDS` variable is similar to the 9740 :term:`DEPENDS` variable. When you use the variable in 9741 your recipe that builds the Wic image, dependencies you list in the 9742 :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable. 9743 9744 With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to 9745 specify a list of additional dependencies (e.g. native tools, 9746 bootloaders, and so forth), that are required to build Wic images. 9747 Following is an example:: 9748 9749 WKS_FILE_DEPENDS = "some-native-tool" 9750 9751 In the 9752 previous example, some-native-tool would be replaced with an actual 9753 native tool on which the build would depend. 9754 9755 :term:`WKS_FILES` 9756 Specifies a list of candidate Wic kickstart files to be used by the 9757 OpenEmbedded build system to create a partitioned image. Only the 9758 first one that is found, from left to right, will be used. 9759 9760 This is only useful when there are multiple ``.wks`` files that can be 9761 used to produce an image. A typical case is when multiple layers are 9762 used for different hardware platforms, each supplying a different 9763 ``.wks`` file. In this case, you specify all possible ones through 9764 :term:`WKS_FILES`. 9765 9766 If only one ``.wks`` file is used, set :term:`WKS_FILE` instead. 9767 9768 :term:`WORKDIR` 9769 The pathname of the work directory in which the OpenEmbedded build 9770 system builds a recipe. This directory is located within the 9771 :term:`TMPDIR` directory structure and is specific to 9772 the recipe being built and the system for which it is being built. 9773 9774 The :term:`WORKDIR` directory is defined as follows:: 9775 9776 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} 9777 9778 The actual directory depends on several things: 9779 9780 - :term:`TMPDIR`: The top-level build output directory 9781 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier 9782 - :term:`PN`: The recipe name 9783 - :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which 9784 is usually the case for most recipes, then :term:`EXTENDPE` is blank. 9785 - :term:`PV`: The recipe version 9786 - :term:`PR`: The recipe revision 9787 9788 As an example, assume a Source Directory top-level folder name 9789 ``poky``, a default :term:`Build Directory` at ``poky/build``, and a 9790 ``qemux86-poky-linux`` machine target system. Furthermore, suppose 9791 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work 9792 directory the build system uses to build the package would be as 9793 follows:: 9794 9795 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 9796 9797 :term:`XSERVER` 9798 Specifies the packages that should be installed to provide an X 9799 server and drivers for the current machine, assuming your image 9800 directly includes ``packagegroup-core-x11-xserver`` or, perhaps 9801 indirectly, includes "x11-base" in 9802 :term:`IMAGE_FEATURES`. 9803 9804 The default value of :term:`XSERVER`, if not specified in the machine 9805 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". 9806 9807 :term:`XZ_THREADS` 9808 Specifies the number of parallel threads that should be used when 9809 using xz compression. 9810 9811 By default this scales with core count, but is never set less than 2 9812 to ensure that multi-threaded mode is always used so that the output 9813 file contents are deterministic. Builds will work with a value of 1 9814 but the output will differ compared to the output from the compression 9815 generated when more than one thread is used. 9816 9817 On systems where many tasks run in parallel, setting a limit to this 9818 can be helpful in controlling system resource usage. 9819 9820 :term:`XZ_MEMLIMIT` 9821 Specifies the maximum memory the xz compression should use as a percentage 9822 of system memory. If unconstrained the xz compressor can use large amounts of 9823 memory and become problematic with parallelism elsewhere in the build. 9824 "50%" has been found to be a good value. 9825 9826 :term:`ZSTD_THREADS` 9827 Specifies the number of parallel threads that should be used when 9828 using ZStandard compression. 9829 9830 By default this scales with core count, but is never set less than 2 9831 to ensure that multi-threaded mode is always used so that the output 9832 file contents are deterministic. Builds will work with a value of 1 9833 but the output will differ compared to the output from the compression 9834 generated when more than one thread is used. 9835 9836 On systems where many tasks run in parallel, setting a limit to this 9837 can be helpful in controlling system resource usage. 9838
