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