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 <FAKEROOT>` 12:term:`G <GCCPIE>` :term:`H <HGDIR>` :term:`I <ICECC_CLASS_DISABLE>` 13:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>` 14:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P` 15:term:`Q <QA_EMPTY_DIRS>` :term:`R <RANLIB>` :term:`S` :term:`T` 16:term:`U <UBOOT_BINARY>` :term:`V <VIRTUAL-RUNTIME>` 17:term:`W <WARN_QA>` :term:`X <XSERVER>` :term:`Z <ZSTD_THREADS>` 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:`AUTO_LIBNAME_PKGS` 196 When the :ref:`ref-classes-debian` class is inherited, 197 which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which 198 packages should be checked for libraries and renamed according to 199 Debian library package naming. 200 201 The default value is "${PACKAGES}", which causes the 202 :ref:`ref-classes-debian` class to act on all packages that are 203 explicitly generated by the recipe. 204 205 :term:`AUTOREV` 206 When :term:`SRCREV` is set to the value of this variable, it specifies to 207 use the latest source revision in the repository. Here is an example:: 208 209 SRCREV = "${AUTOREV}" 210 211 If you use the previous statement to retrieve the latest version of 212 software, you need to make sure :term:`PV` contains the ``+`` sign so 213 :term:`bitbake` includes source control information to :term:`PKGV` when 214 packaging the recipe. For example:: 215 216 PV = "6.10.y+git" 217 218 For more information see the 219 ":ref:`dev-manual/packages:automatically incrementing a package version number`" 220 section in the Yocto Project Development Tasks Manual. 221 222 :term:`AUTO_SYSLINUXMENU` 223 Enables creating an automatic menu for the syslinux bootloader. You 224 must set this variable in your recipe. The 225 :ref:`ref-classes-syslinux` class checks this variable. 226 227 :term:`AVAILTUNES` 228 The list of defined CPU and Application Binary Interface (ABI) 229 tunings (i.e. "tunes") available for use by the OpenEmbedded build 230 system. 231 232 The list simply presents the tunes that are available. Not all tunes 233 may be compatible with a particular machine configuration, or with 234 each other in a 235 :ref:`Multilib <dev-manual/libraries:combining multiple versions of library files into one image>` 236 configuration. 237 238 To add a tune to the list, be sure to append it with spaces using the 239 "+=" BitBake operator. Do not simply replace the list by using the 240 "=" operator. See the 241 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake 242 User Manual for more information. 243 244 :term:`AZ_SAS` 245 Azure Storage Shared Access Signature, when using the 246 :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` 247 This variable can be defined to be used by the fetcher to authenticate 248 and gain access to non-public artifacts:: 249 250 AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>"" 251 252 For more information see Microsoft's Azure Storage documentation at 253 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview 254 255 :term:`B` 256 The directory within the :term:`Build Directory` in which the 257 OpenEmbedded build system places generated objects during a recipe's 258 build process. By default, this directory is the same as the 259 :term:`S` directory, which is defined as:: 260 261 S = "${WORKDIR}/${BP}" 262 263 You can separate the (:term:`S`) directory and the directory pointed to 264 by the :term:`B` variable. Most Autotools-based recipes support 265 separating these directories. The build system defaults to using 266 separate directories for ``gcc`` and some kernel recipes. 267 268 :term:`BAD_RECOMMENDATIONS` 269 Lists "recommended-only" packages to not install. Recommended-only 270 packages are packages installed only through the 271 :term:`RRECOMMENDS` variable. You can prevent any 272 of these "recommended" packages from being installed by listing them 273 with the :term:`BAD_RECOMMENDATIONS` variable:: 274 275 BAD_RECOMMENDATIONS = "package_name package_name package_name ..." 276 277 You can set this variable globally in your ``local.conf`` file or you 278 can attach it to a specific image recipe by using the recipe name 279 override:: 280 281 BAD_RECOMMENDATIONS:pn-target_image = "package_name" 282 283 It is important to realize that if you choose to not install packages 284 using this variable and some other packages are dependent on them 285 (i.e. listed in a recipe's :term:`RDEPENDS` 286 variable), the OpenEmbedded build system ignores your request and 287 will install the packages to avoid dependency errors. 288 289 This variable is supported only when using the IPK and RPM 290 packaging backends. DEB is not supported. 291 292 See the :term:`NO_RECOMMENDATIONS` and the 293 :term:`PACKAGE_EXCLUDE` variables for related 294 information. 295 296 :term:`BAREBOX_BINARY` 297 When using the :ref:`ref-classes-barebox` class, this variable allows you 298 to specify a particular binary that should be deployed and installed. 299 300 The barebox build system can build multiple barebox binaries at once. 301 By default, all built binaries will be deployed and installed under their 302 original name. 303 304 Here is an example usage of this variable:: 305 306 BAREBOX_BINARY = "barebox-boundarydevices-imx6dl-nitrogen6x-1g.img" 307 308 :term:`BAREBOX_CONFIG` 309 When using the :ref:`ref-classes-barebox` class, this variable allows you 310 to specify the name of the barebox defconfig to build. 311 The name must be a defconfig file known to the barebox build environment. 312 This variable is mainly useful for generic use cases where a dedicated 313 configuration is not required. 314 The :ref:`ref-classes-barebox` class itself already sets it for some QEMU 315 machines:: 316 317 BAREBOX_CONFIG:qemuarm = "multi_v7_defconfig" 318 BAREBOX_CONFIG:qemuarm64 = "multi_v8_defconfig" 319 BAREBOX_CONFIG:qemux86-64 = "efi_defconfig" 320 321 Except for these, the default value of :term:`BAREBOX_CONFIG` is empty. 322 For more information on how to provide a barebox configuration, see the 323 :ref:`ref-classes-barebox` class. 324 325 :term:`BASE_LIB` 326 The library directory name for the CPU or Application Binary 327 Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib 328 context. See the ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`" 329 section in the Yocto Project Development Tasks Manual for information 330 on Multilib. 331 332 The :term:`BASE_LIB` variable is defined in the machine include files in 333 the :term:`Source Directory`. If Multilib is not 334 being used, the value defaults to "lib". 335 336 :term:`BASE_WORKDIR` 337 Points to the base of the work directory for all recipes. The default 338 value is "${TMPDIR}/work". 339 340 :term:`BB_ALLOWED_NETWORKS` 341 Specifies a space-delimited list of hosts that the fetcher is allowed 342 to use to obtain the required source code. Here are 343 considerations surrounding this variable: 344 345 - This host list is only used if :term:`BB_NO_NETWORK` is either not set 346 or set to "0". 347 348 - There is limited support for wildcard matching against the beginning of 349 host names. For example, the following setting matches 350 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``:: 351 352 BB_ALLOWED_NETWORKS = "*.gnu.org" 353 354 .. note:: 355 356 The use of the "``*``" character only works at the beginning of 357 a host name and it must be isolated from the remainder of the 358 host name. You cannot use the wildcard character in any other 359 location of the name or combined with the front part of the 360 name. 361 362 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` 363 is not. 364 365 - Mirrors not in the host list are skipped and logged in debug. 366 367 - Attempts to access networks not in the host list cause a failure. 368 369 Using :term:`BB_ALLOWED_NETWORKS` in conjunction with 370 :term:`PREMIRRORS` is very useful. Adding the host 371 you want to use to :term:`PREMIRRORS` results in the source code being 372 fetched from an allowed location and avoids raising an error when a 373 host that is not allowed is in a :term:`SRC_URI` 374 statement. This is because the fetcher does not attempt to use the 375 host listed in :term:`SRC_URI` after a successful fetch from the 376 :term:`PREMIRRORS` occurs. 377 378 :term:`BB_BASEHASH_IGNORE_VARS` 379 See :term:`bitbake:BB_BASEHASH_IGNORE_VARS` in the BitBake manual. 380 381 :term:`BB_CACHEDIR` 382 See :term:`bitbake:BB_CACHEDIR` in the BitBake manual. 383 384 :term:`BB_CHECK_SSL_CERTS` 385 See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual. 386 387 :term:`BB_CONSOLELOG` 388 See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual. 389 390 :term:`BB_CURRENTTASK` 391 See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual. 392 393 :term:`BB_DEFAULT_TASK` 394 See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual. 395 396 :term:`BB_DEFAULT_UMASK` 397 See :term:`bitbake:BB_DEFAULT_UMASK` in the BitBake manual. 398 399 :term:`BB_DISKMON_DIRS` 400 Monitors disk space and available inodes during the build and allows 401 you to control the build based on these parameters. 402 403 Disk space monitoring is disabled by default. To enable monitoring, 404 add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file 405 found in the :term:`Build Directory`. Use the 406 following form: 407 408 .. code-block:: none 409 410 BB_DISKMON_DIRS = "action,dir,threshold [...]" 411 412 where: 413 414 action is: 415 ABORT: Immediately stop the build when 416 a threshold is broken. 417 STOPTASKS: Stop the build after the currently 418 executing tasks have finished when 419 a threshold is broken. 420 WARN: Issue a warning but continue the 421 build when a threshold is broken. 422 Subsequent warnings are issued as 423 defined by the BB_DISKMON_WARNINTERVAL 424 variable, which must be defined in 425 the conf/local.conf file. 426 427 dir is: 428 Any directory you choose. You can specify one or 429 more directories to monitor by separating the 430 groupings with a space. If two directories are 431 on the same device, only the first directory 432 is monitored. 433 434 threshold is: 435 Either the minimum available disk space, 436 the minimum number of free inodes, or 437 both. You must specify at least one. To 438 omit one or the other, simply omit the value. 439 Specify the threshold using G, M, K for Gbytes, 440 Mbytes, and Kbytes, respectively. If you do 441 not specify G, M, or K, Kbytes is assumed by 442 default. Do not use GB, MB, or KB. 443 444 Here are some examples:: 445 446 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" 447 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" 448 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" 449 450 The first example works only if you also provide the 451 :term:`BB_DISKMON_WARNINTERVAL` 452 variable in the ``conf/local.conf``. This example causes the build 453 system to immediately stop when either the disk space in 454 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops 455 below 100 Kbytes. Because two directories are provided with the 456 variable, the build system also issue a warning when the disk space 457 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number 458 of free inodes drops below 100 Kbytes. Subsequent warnings are issued 459 during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL` 460 variable. 461 462 The second example stops the build after all currently executing 463 tasks complete when the minimum disk space in the ``${TMPDIR}`` 464 directory drops below 1 Gbyte. No disk monitoring occurs for the free 465 inodes in this case. 466 467 The final example immediately stops the build when the number of 468 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No 469 disk space monitoring for the directory itself occurs in this case. 470 471 :term:`BB_DISKMON_WARNINTERVAL` 472 Defines the disk space and free inode warning intervals. To set these 473 intervals, define the variable in your ``conf/local.conf`` file in 474 the :term:`Build Directory`. 475 476 If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you 477 must also use the :term:`BB_DISKMON_DIRS` 478 variable and define its action as "WARN". During the build, 479 subsequent warnings are issued each time disk space or number of free 480 inodes further reduces by the respective interval. 481 482 If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you 483 do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk 484 monitoring interval defaults to the following:: 485 486 BB_DISKMON_WARNINTERVAL = "50M,5K" 487 488 When specifying the variable in your configuration file, use the 489 following form: 490 491 .. code-block:: none 492 493 BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval" 494 495 where: 496 497 disk_space_interval is: 498 An interval of memory expressed in either 499 G, M, or K for Gbytes, Mbytes, or Kbytes, 500 respectively. You cannot use GB, MB, or KB. 501 502 disk_inode_interval is: 503 An interval of free inodes expressed in either 504 G, M, or K for Gbytes, Mbytes, or Kbytes, 505 respectively. You cannot use GB, MB, or KB. 506 507 Here is an example:: 508 509 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 510 BB_DISKMON_WARNINTERVAL = "50M,5K" 511 512 These variables cause the 513 OpenEmbedded build system to issue subsequent warnings each time the 514 available disk space further reduces by 50 Mbytes or the number of 515 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` 516 directory. Subsequent warnings based on the interval occur each time 517 a respective interval is reached beyond the initial warning (i.e. 1 518 Gbytes and 100 Kbytes). 519 520 :term:`BB_ENV_PASSTHROUGH` 521 See :term:`bitbake:BB_ENV_PASSTHROUGH` in the BitBake manual. 522 523 :term:`BB_ENV_PASSTHROUGH_ADDITIONS` 524 See :term:`bitbake:BB_ENV_PASSTHROUGH_ADDITIONS` in the BitBake manual. 525 526 :term:`BB_FETCH_PREMIRRORONLY` 527 See :term:`bitbake:BB_FETCH_PREMIRRORONLY` in the BitBake manual. 528 529 :term:`BB_FILENAME` 530 See :term:`bitbake:BB_FILENAME` in the BitBake manual. 531 532 :term:`BB_GENERATE_MIRROR_TARBALLS` 533 Causes tarballs of the source control repositories (e.g. Git 534 repositories), including metadata, to be placed in the 535 :term:`DL_DIR` directory. 536 537 For performance reasons, creating and placing tarballs of these 538 repositories is not the default action by the OpenEmbedded build 539 system:: 540 541 BB_GENERATE_MIRROR_TARBALLS = "1" 542 543 Set this variable in your 544 ``local.conf`` file in the :term:`Build Directory`. 545 546 Once you have the tarballs containing your source files, you can 547 clean up your :term:`DL_DIR` directory by deleting any Git or other 548 source control work directories. 549 550 :term:`BB_GENERATE_SHALLOW_TARBALLS` 551 See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual. 552 553 :term:`BB_GIT_SHALLOW` 554 See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual. 555 556 :term:`BB_GIT_SHALLOW_DEPTH` 557 See :term:`bitbake:BB_GIT_SHALLOW_DEPTH` in the BitBake manual. 558 559 :term:`BB_HASHCHECK_FUNCTION` 560 See :term:`bitbake:BB_HASHCHECK_FUNCTION` in the BitBake manual. 561 562 :term:`BB_HASHCONFIG_IGNORE_VARS` 563 See :term:`bitbake:BB_HASHCONFIG_IGNORE_VARS` in the BitBake manual. 564 565 :term:`BB_HASHSERVE` 566 See :term:`bitbake:BB_HASHSERVE` in the BitBake manual. 567 568 :term:`BB_HASHSERVE_UPSTREAM` 569 See :term:`bitbake:BB_HASHSERVE_UPSTREAM` in the BitBake manual. 570 571 :term:`BB_INVALIDCONF` 572 See :term:`bitbake:BB_INVALIDCONF` in the BitBake manual. 573 574 :term:`BB_LOADFACTOR_MAX` 575 The system load threshold above which BitBake will stop runnig extra 576 tasks. 577 578 :term:`BB_LOGCONFIG` 579 See :term:`bitbake:BB_LOGCONFIG` in the BitBake manual. 580 581 :term:`BB_LOGFMT` 582 See :term:`bitbake:BB_LOGFMT` in the BitBake manual. 583 584 :term:`BB_MULTI_PROVIDER_ALLOWED` 585 See :term:`bitbake:BB_MULTI_PROVIDER_ALLOWED` in the BitBake manual. 586 587 :term:`BB_NICE_LEVEL` 588 See :term:`bitbake:BB_NICE_LEVEL` in the BitBake manual. 589 590 :term:`BB_NO_NETWORK` 591 See :term:`bitbake:BB_NO_NETWORK` in the BitBake manual. 592 593 :term:`BB_NUMBER_PARSE_THREADS` 594 See :term:`bitbake:BB_NUMBER_PARSE_THREADS` in the BitBake manual. 595 596 :term:`BB_NUMBER_THREADS` 597 The maximum number of tasks BitBake should run in parallel at any one 598 time. The OpenEmbedded build system automatically configures this 599 variable to be equal to the number of cores on the build system. For 600 example, a system with a dual core processor that also uses 601 hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default 602 to "4". 603 604 For single socket systems (i.e. one CPU), you should not have to 605 override this variable to gain optimal parallelism during builds. 606 However, if you have very large systems that employ multiple physical 607 CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable 608 is not set higher than "20". 609 610 For more information on speeding up builds, see the 611 ":ref:`dev-manual/speeding-up-build:speeding up a build`" 612 section in the Yocto Project Development Tasks Manual. 613 614 On the other hand, if your goal is to limit the amount of system 615 resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS` 616 to a number lower than the number of CPU threads in your machine 617 won't be sufficient. That's because each package will still be built 618 and installed through a number of parallel jobs specified by the 619 :term:`PARALLEL_MAKE` variable, which is by default the number of CPU 620 threads in your system, and is not impacted by the 621 :term:`BB_NUMBER_THREADS` value. 622 623 So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set 624 :term:`PARALLEL_MAKE`, most of your system resources will be consumed 625 anyway. 626 627 Therefore, if you intend to reduce the load of your build system by 628 setting :term:`BB_NUMBER_THREADS` to a relatively low value compared 629 to the number of CPU threads on your system, you should also set 630 :term:`PARALLEL_MAKE` to a similarly low value. 631 632 An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage 633 of build system resources under control is to use the smarter 634 :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or 635 :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake 636 from starting new tasks as long as thresholds are exceeded. Anyway, 637 as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the 638 tasks already being run from using all CPU threads on the system 639 if :term:`PARALLEL_MAKE` is not set to a low value. 640 641 :term:`BB_ORIGENV` 642 See :term:`bitbake:BB_ORIGENV` in the BitBake manual. 643 644 :term:`BB_PRESERVE_ENV` 645 See :term:`bitbake:BB_PRESERVE_ENV` in the BitBake manual. 646 647 :term:`BB_PRESSURE_MAX_CPU` 648 See :term:`bitbake:BB_PRESSURE_MAX_CPU` in the BitBake manual. 649 650 :term:`BB_PRESSURE_MAX_IO` 651 See :term:`bitbake:BB_PRESSURE_MAX_IO` in the BitBake manual. 652 653 :term:`BB_PRESSURE_MAX_MEMORY` 654 See :term:`bitbake:BB_PRESSURE_MAX_MEMORY` in the BitBake manual. 655 656 :term:`BB_RUNFMT` 657 See :term:`bitbake:BB_RUNFMT` in the BitBake manual. 658 659 :term:`BB_RUNTASK` 660 See :term:`bitbake:BB_RUNTASK` in the BitBake manual. 661 662 :term:`BB_SCHEDULER` 663 See :term:`bitbake:BB_SCHEDULER` in the BitBake manual. 664 665 :term:`BB_SCHEDULERS` 666 See :term:`bitbake:BB_SCHEDULERS` in the BitBake manual. 667 668 :term:`BB_SERVER_TIMEOUT` 669 Specifies the time (in seconds) after which to unload the BitBake 670 server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how 671 long the BitBake server stays resident between invocations. 672 673 For example, the following statement in your ``local.conf`` file 674 instructs the server to be unloaded after 20 seconds of inactivity:: 675 676 BB_SERVER_TIMEOUT = "20" 677 678 If you want the server to never be unloaded, 679 set :term:`BB_SERVER_TIMEOUT` to "-1". 680 681 :term:`BB_SETSCENE_DEPVALID` 682 See :term:`bitbake:BB_SETSCENE_DEPVALID` in the BitBake manual. 683 684 :term:`BB_SIGNATURE_EXCLUDE_FLAGS` 685 See :term:`bitbake:BB_SIGNATURE_EXCLUDE_FLAGS` in the BitBake manual. 686 687 :term:`BB_SIGNATURE_HANDLER` 688 See :term:`bitbake:BB_SIGNATURE_HANDLER` in the BitBake manual. 689 690 :term:`BB_SRCREV_POLICY` 691 See :term:`bitbake:BB_SRCREV_POLICY` in the BitBake manual. 692 693 :term:`BB_STRICT_CHECKSUM` 694 See :term:`bitbake:BB_STRICT_CHECKSUM` in the BitBake manual. 695 696 :term:`BB_TASK_IONICE_LEVEL` 697 See :term:`bitbake:BB_TASK_IONICE_LEVEL` in the BitBake manual. 698 699 :term:`BB_TASK_NICE_LEVEL` 700 See :term:`bitbake:BB_TASK_NICE_LEVEL` in the BitBake manual. 701 702 :term:`BB_TASKHASH` 703 See :term:`bitbake:BB_TASKHASH` in the BitBake manual. 704 705 :term:`BB_VERBOSE_LOGS` 706 See :term:`bitbake:BB_VERBOSE_LOGS` in the BitBake manual. 707 708 :term:`BB_WORKERCONTEXT` 709 See :term:`bitbake:BB_WORKERCONTEXT` in the BitBake manual. 710 711 :term:`BBCLASSEXTEND` 712 Allows you to extend a recipe so that it builds variants of the 713 software. There are common variants for recipes as "natives" like 714 ``quilt-native``, which is a copy of Quilt built to run on the build 715 system; "crosses" such as ``gcc-cross``, which is a compiler built to 716 run on the build machine but produces binaries that run on the target 717 :term:`MACHINE`; ":ref:`ref-classes-nativesdk`", which 718 targets the SDK machine instead of :term:`MACHINE`; and "mulitlibs" in 719 the form "``multilib:``\ multilib_name". 720 721 To build a different variant of the recipe with a minimal amount of 722 code, it usually is as simple as adding the following to your recipe:: 723 724 BBCLASSEXTEND =+ "native nativesdk" 725 BBCLASSEXTEND =+ "multilib:multilib_name" 726 727 .. note:: 728 729 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe 730 variants by rewriting variable values and applying overrides such 731 as ``:class-native``. For example, to generate a native version of 732 a recipe, a :term:`DEPENDS` on "foo" is rewritten 733 to a :term:`DEPENDS` on "foo-native". 734 735 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. 736 Parsing once adds some limitations. For example, it is not 737 possible to include a different file depending on the variant, 738 since ``include`` statements are processed when the recipe is 739 parsed. 740 741 :term:`BBDEBUG` 742 See :term:`bitbake:BBDEBUG` in the BitBake manual. 743 744 :term:`BBFILE_COLLECTIONS` 745 Lists the names of configured layers. These names are used to find 746 the other ``BBFILE_*`` variables. Typically, each layer will append 747 its name to this variable in its ``conf/layer.conf`` file. 748 749 :term:`BBFILE_PATTERN` 750 Variable that expands to match files from 751 :term:`BBFILES` in a particular layer. This variable 752 is used in the ``conf/layer.conf`` file and must be suffixed with the 753 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). 754 755 :term:`BBFILE_PRIORITY` 756 Assigns the priority for recipe files in each layer. 757 758 This variable is useful in situations where the same recipe appears 759 in more than one layer. Setting this variable allows you to 760 prioritize a layer against other layers that contain the same recipe 761 --- effectively letting you control the precedence for the multiple 762 layers. The precedence established through this variable stands 763 regardless of a recipe's version (:term:`PV` variable). For 764 example, a layer that has a recipe with a higher :term:`PV` value but for 765 which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still 766 has a lower precedence. 767 768 A larger value for the :term:`BBFILE_PRIORITY` variable results in a 769 higher precedence. For example, the value 6 has a higher precedence 770 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable 771 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable 772 for more information. The default priority, if unspecified for a 773 layer with no dependencies, is the lowest defined priority + 1 (or 1 774 if no priorities are defined). 775 776 .. tip:: 777 778 You can use the command ``bitbake-layers show-layers`` 779 to list all configured layers along with their priorities. 780 781 :term:`BBFILES` 782 A space-separated list of recipe files BitBake uses to build 783 software. 784 785 When specifying recipe files, you can pattern match using Python's 786 `glob <https://docs.python.org/3/library/glob.html>`__ syntax. 787 For details on the syntax, see the documentation by following the 788 previous link. 789 790 :term:`BBFILES_DYNAMIC` 791 Activates content when identified layers are present. You identify 792 the layers by the collections that the layers define. 793 794 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files 795 whose corresponding ``.bb`` file is in a layer that attempts to 796 modify other layers through ``.bbappend`` but does not want to 797 introduce a hard dependency on those other layers. 798 799 Use the following form for :term:`BBFILES_DYNAMIC`: 800 ``collection_name:filename_pattern``. 801 802 The following example identifies two collection names and two 803 filename patterns:: 804 805 BBFILES_DYNAMIC += " \ 806 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ 807 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ 808 " 809 810 This next example shows an error message that occurs because invalid 811 entries are found, which cause parsing to fail: 812 813 .. code-block:: none 814 815 ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not: 816 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend 817 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend 818 819 :term:`BBINCLUDED` 820 See :term:`bitbake:BBINCLUDED` in the BitBake manual. 821 822 :term:`BBINCLUDELOGS` 823 Variable that controls how BitBake displays logs on build failure. 824 825 :term:`BBINCLUDELOGS_LINES` 826 If :term:`BBINCLUDELOGS` is set, specifies the 827 maximum number of lines from the task log file to print when 828 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, 829 the entire log is printed. 830 831 :term:`BBLAYERS` 832 Lists the layers to enable during the build. This variable is defined 833 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. 834 Here is an example:: 835 836 BBLAYERS = " \ 837 /home/scottrif/poky/meta \ 838 /home/scottrif/poky/meta-poky \ 839 /home/scottrif/poky/meta-yocto-bsp \ 840 /home/scottrif/poky/meta-mykernel \ 841 " 842 843 This example enables four layers, one of which is a custom, 844 user-defined layer named ``meta-mykernel``. 845 846 :term:`BBLAYERS_FETCH_DIR` 847 See :term:`bitbake:BBLAYERS_FETCH_DIR` in the BitBake manual. 848 849 :term:`BBMASK` 850 Prevents BitBake from processing recipes and recipe append files. 851 852 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and 853 ``.bbappend`` files. BitBake ignores any recipe or recipe append 854 files that match any of the expressions. It is as if BitBake does not 855 see them at all. Consequently, matching files are not parsed or 856 otherwise used by BitBake. 857 858 The values you provide are passed to Python's regular expression 859 compiler. Consequently, the syntax follows Python's Regular 860 Expression (re) syntax. The expressions are compared against the full 861 paths to the files. For complete syntax information, see Python's 862 documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax. 863 864 The following example uses a complete regular expression to tell 865 BitBake to ignore all recipe and recipe append files in the 866 ``meta-ti/recipes-misc/`` directory:: 867 868 BBMASK = "meta-ti/recipes-misc/" 869 870 If you want to mask out multiple directories or recipes, you can 871 specify multiple regular expression fragments. This next example 872 masks out multiple directories and individual recipes:: 873 874 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" 875 BBMASK += "/meta-oe/recipes-support/" 876 BBMASK += "/meta-foo/.*/openldap" 877 BBMASK += "opencv.*\.bbappend" 878 BBMASK += "lzma" 879 880 .. note:: 881 882 When specifying a directory name, use the trailing slash character 883 to ensure you match just that directory name. 884 885 :term:`BBMULTICONFIG` 886 Specifies each additional separate configuration when you are 887 building targets with multiple configurations. Use this variable in 888 your ``conf/local.conf`` configuration file. Specify a 889 multiconfigname for each configuration file you are using. For 890 example, the following line specifies three configuration files:: 891 892 BBMULTICONFIG = "configA configB configC" 893 894 Each configuration file you use must reside in a ``multiconfig`` 895 subdirectory of a configuration directory within a layer, or 896 within the :term:`Build Directory` (e.g. 897 ``build_directory/conf/multiconfig/configA.conf`` or 898 ``mylayer/conf/multiconfig/configB.conf``). 899 900 For information on how to use :term:`BBMULTICONFIG` in an environment 901 that supports building targets with multiple configurations, see the 902 ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" 903 section in the Yocto Project Development Tasks Manual. 904 905 :term:`BBPATH` 906 See :term:`bitbake:BBPATH` in the BitBake manual. 907 908 :term:`BBSERVER` 909 If defined in the BitBake environment, :term:`BBSERVER` points to the 910 BitBake remote server. 911 912 Use the following format to export the variable to the BitBake 913 environment:: 914 915 export BBSERVER=localhost:$port 916 917 By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`. 918 Consequently, :term:`BBSERVER` is excluded from checksum and dependency 919 data. 920 921 :term:`BBTARGETS` 922 See :term:`bitbake:BBTARGETS` in the BitBake manual. 923 924 :term:`BINCONFIG` 925 When inheriting the :ref:`ref-classes-binconfig-disabled` class, this 926 variable specifies binary configuration scripts to disable in favor of 927 using ``pkg-config`` to query the information. The 928 :ref:`ref-classes-binconfig-disabled` class will modify the specified 929 scripts to return an error so that calls to them can be easily found 930 and replaced. 931 932 To add multiple scripts, separate them by spaces. Here is an example 933 from the ``libpng`` recipe:: 934 935 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" 936 937 :term:`BINCONFIG_GLOB` 938 When inheriting the :ref:`ref-classes-binconfig` class, 939 this variable specifies a wildcard for configuration scripts that 940 need editing. The scripts are edited to correct any paths that have 941 been set up during compilation so that they are correct for use when 942 installed into the sysroot and called by the build processes of other 943 recipes. 944 945 .. note:: 946 947 The :term:`BINCONFIG_GLOB` variable uses 948 `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, 949 which is recognition and expansion of wildcards during pattern 950 matching. Shell globbing is very similar to 951 `fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__ 952 and `glob <https://docs.python.org/3/library/glob.html>`__. 953 954 For more information on how this variable works, see 955 ``meta/classes-recipe/binconfig.bbclass`` in the :term:`Source Directory`. 956 You can also find general 957 information on the class in the 958 ":ref:`ref-classes-binconfig`" section. 959 960 :term:`BITBAKE_UI` 961 See :term:`bitbake:BITBAKE_UI` in the BitBake manual. 962 963 :term:`BP` 964 The base recipe name and version but without any special recipe name 965 suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is 966 comprised of the following:: 967 968 ${BPN}-${PV} 969 970 :term:`BPN` 971 This variable is a version of the :term:`PN` variable with 972 common prefixes and suffixes removed, such as ``nativesdk-``, 973 ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``. 974 The exact lists of prefixes and suffixes removed are specified by the 975 :term:`MLPREFIX` and 976 :term:`SPECIAL_PKGSUFFIX` variables, 977 respectively. 978 979 :term:`BUGTRACKER` 980 Specifies a URL for an upstream bug tracking website for a recipe. 981 The OpenEmbedded build system does not use this variable. Rather, the 982 variable is a useful pointer in case a bug in the software being 983 built needs to be manually reported. 984 985 :term:`BUILD_ARCH` 986 Specifies the architecture of the build host (e.g. ``i686``). The 987 OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the 988 machine name reported by the ``uname`` command. 989 990 :term:`BUILD_AS_ARCH` 991 Specifies the architecture-specific assembler flags for the build 992 host. By default, the value of :term:`BUILD_AS_ARCH` is empty. 993 994 :term:`BUILD_CC_ARCH` 995 Specifies the architecture-specific C compiler flags for the build 996 host. By default, the value of :term:`BUILD_CC_ARCH` is empty. 997 998 :term:`BUILD_CCLD` 999 Specifies the linker command to be used for the build host when the C 1000 compiler is being used as the linker. By default, :term:`BUILD_CCLD` 1001 points to GCC and passes as arguments the value of 1002 :term:`BUILD_CC_ARCH`, assuming 1003 :term:`BUILD_CC_ARCH` is set. 1004 1005 :term:`BUILD_CFLAGS` 1006 Specifies the flags to pass to the C compiler when building for the 1007 build host. When building in the ``-native`` context, 1008 :term:`CFLAGS` is set to the value of this variable by 1009 default. 1010 1011 :term:`BUILD_CPPFLAGS` 1012 Specifies the flags to pass to the C preprocessor (i.e. to both the C 1013 and the C++ compilers) when building for the build host. When 1014 building in the ``-native`` context, :term:`CPPFLAGS` 1015 is set to the value of this variable by default. 1016 1017 :term:`BUILD_CXXFLAGS` 1018 Specifies the flags to pass to the C++ compiler when building for the 1019 build host. When building in the ``-native`` context, 1020 :term:`CXXFLAGS` is set to the value of this variable 1021 by default. 1022 1023 :term:`BUILD_FC` 1024 Specifies the Fortran compiler command for the build host. By 1025 default, :term:`BUILD_FC` points to Gfortran and passes as arguments the 1026 value of :term:`BUILD_CC_ARCH`, assuming 1027 :term:`BUILD_CC_ARCH` is set. 1028 1029 :term:`BUILD_LD` 1030 Specifies the linker command for the build host. By default, 1031 :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments 1032 the value of :term:`BUILD_LD_ARCH`, assuming 1033 :term:`BUILD_LD_ARCH` is set. 1034 1035 :term:`BUILD_LD_ARCH` 1036 Specifies architecture-specific linker flags for the build host. By 1037 default, the value of :term:`BUILD_LD_ARCH` is empty. 1038 1039 :term:`BUILD_LDFLAGS` 1040 Specifies the flags to pass to the linker when building for the build 1041 host. When building in the ``-native`` context, 1042 :term:`LDFLAGS` is set to the value of this variable 1043 by default. 1044 1045 :term:`BUILD_OPTIMIZATION` 1046 Specifies the optimization flags passed to the C compiler when 1047 building for the build host or the SDK. The flags are passed through 1048 the :term:`BUILD_CFLAGS` and 1049 :term:`BUILDSDK_CFLAGS` default values. 1050 1051 The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2 1052 -pipe". 1053 1054 :term:`BUILD_OS` 1055 Specifies the operating system in use on the build host (e.g. 1056 "linux"). The OpenEmbedded build system sets the value of 1057 :term:`BUILD_OS` from the OS reported by the ``uname`` command --- the 1058 first word, converted to lower-case characters. 1059 1060 :term:`BUILD_PREFIX` 1061 The toolchain binary prefix used for native recipes. The OpenEmbedded 1062 build system uses the :term:`BUILD_PREFIX` value to set the 1063 :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes. 1064 1065 :term:`BUILD_STRIP` 1066 Specifies the command to be used to strip debugging symbols from 1067 binaries produced for the build host. By default, :term:`BUILD_STRIP` 1068 points to 1069 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. 1070 1071 :term:`BUILD_SYS` 1072 Specifies the system, including the architecture and the operating 1073 system, to use when building for the build host (i.e. when building 1074 :ref:`ref-classes-native` recipes). 1075 1076 The OpenEmbedded build system automatically sets this variable based 1077 on :term:`BUILD_ARCH`, 1078 :term:`BUILD_VENDOR`, and 1079 :term:`BUILD_OS`. You do not need to set the 1080 :term:`BUILD_SYS` variable yourself. 1081 1082 :term:`BUILD_VENDOR` 1083 Specifies the vendor name to use when building for the build host. 1084 The default value is an empty string (""). 1085 1086 :term:`BUILDDIR` 1087 Points to the location of the :term:`Build Directory`. You can define 1088 this directory indirectly through the :ref:`structure-core-script` script 1089 by passing in a :term:`Build Directory` path when you run the script. If 1090 you run the script and do not provide a :term:`Build Directory` path, the 1091 :term:`BUILDDIR` defaults to ``build`` in the current directory. 1092 1093 :term:`BUILDHISTORY_COMMIT` 1094 When inheriting the :ref:`ref-classes-buildhistory` class, this variable 1095 specifies whether or not to commit the build history output in a local 1096 Git repository. If set to "1", this local repository will be maintained 1097 automatically by the :ref:`ref-classes-buildhistory` class and a commit 1098 will be created on every build for changes to each top-level subdirectory 1099 of the build history output (images, packages, and sdk). If you want to 1100 track changes to build history over time, you should set this value to 1101 "1". 1102 1103 By default, the :ref:`ref-classes-buildhistory` class 1104 enables committing the buildhistory output in a local Git repository:: 1105 1106 BUILDHISTORY_COMMIT ?= "1" 1107 1108 :term:`BUILDHISTORY_COMMIT_AUTHOR` 1109 When inheriting the :ref:`ref-classes-buildhistory` 1110 class, this variable specifies the author to use for each Git commit. 1111 In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the 1112 :term:`BUILDHISTORY_COMMIT` variable must 1113 be set to "1". 1114 1115 Git requires that the value you provide for the 1116 :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name 1117 email@host". Providing an email address or host that is not valid 1118 does not produce an error. 1119 1120 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1121 as follows:: 1122 1123 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" 1124 1125 :term:`BUILDHISTORY_DIR` 1126 When inheriting the :ref:`ref-classes-buildhistory` 1127 class, this variable specifies the directory in which build history 1128 information is kept. For more information on how the variable works, 1129 see the :ref:`ref-classes-buildhistory` class. 1130 1131 By default, the :ref:`ref-classes-buildhistory` class sets the directory 1132 as follows:: 1133 1134 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" 1135 1136 :term:`BUILDHISTORY_FEATURES` 1137 When inheriting the :ref:`ref-classes-buildhistory` 1138 class, this variable specifies the build history features to be 1139 enabled. For more information on how build history works, see the 1140 ":ref:`dev-manual/build-quality:maintaining build output quality`" 1141 section in the Yocto Project Development Tasks Manual. 1142 1143 You can specify these features in the form of a space-separated list: 1144 1145 - *image:* Analysis of the contents of images, which includes the 1146 list of installed packages among other things. 1147 1148 - *package:* Analysis of the contents of individual packages. 1149 1150 - *sdk:* Analysis of the contents of the software development kit 1151 (SDK). 1152 1153 - *task:* Save output file signatures for 1154 :ref:`shared state <overview-manual/concepts:shared state cache>` 1155 (sstate) tasks. 1156 This saves one file per task and lists the SHA-256 checksums for 1157 each file staged (i.e. the output of the task). 1158 1159 By default, the :ref:`ref-classes-buildhistory` class enables the 1160 following features:: 1161 1162 BUILDHISTORY_FEATURES ?= "image package sdk" 1163 1164 :term:`BUILDHISTORY_IMAGE_FILES` 1165 When inheriting the :ref:`ref-classes-buildhistory` 1166 class, this variable specifies a list of paths to files copied from 1167 the image contents into the build history directory under an 1168 "image-files" directory in the directory for the image, so that you 1169 can track the contents of each file. The default is to copy 1170 ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for 1171 changes in user and group entries. You can modify the list to include 1172 any file. Specifying an invalid path does not produce an error. 1173 Consequently, you can include files that might not always be present. 1174 1175 By default, the :ref:`ref-classes-buildhistory` class provides paths to 1176 the following files:: 1177 1178 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" 1179 1180 :term:`BUILDHISTORY_PATH_PREFIX_STRIP` 1181 When inheriting the :ref:`ref-classes-buildhistory` 1182 class, this variable specifies a common path prefix that should be 1183 stripped off the beginning of paths in the task signature list when the 1184 ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be 1185 useful when build history is populated from multiple sources that may not 1186 all use the same top level directory. 1187 1188 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1189 as follows:: 1190 1191 BUILDHISTORY_PATH_PREFIX_STRIP ?= "" 1192 1193 In this case, no prefixes will be stripped. 1194 1195 :term:`BUILDHISTORY_PUSH_REPO` 1196 When inheriting the :ref:`ref-classes-buildhistory` class, this variable 1197 optionally specifies a remote repository to which build history pushes 1198 Git changes. In order for :term:`BUILDHISTORY_PUSH_REPO` to work, 1199 :term:`BUILDHISTORY_COMMIT` must be set to "1". 1200 1201 The repository should correspond to a remote address that specifies a 1202 repository as understood by Git, or alternatively to a remote name 1203 that you have set up manually using ``git remote`` within the local 1204 repository. 1205 1206 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1207 as follows:: 1208 1209 BUILDHISTORY_PUSH_REPO ?= "" 1210 1211 :term:`BUILDNAME` 1212 See :term:`bitbake:BUILDNAME` in the BitBake manual. 1213 1214 :term:`BUILDSDK_CFLAGS` 1215 Specifies the flags to pass to the C compiler when building for the 1216 SDK. When building in the ``nativesdk-`` context, 1217 :term:`CFLAGS` is set to the value of this variable by 1218 default. 1219 1220 :term:`BUILDSDK_CPPFLAGS` 1221 Specifies the flags to pass to the C pre-processor (i.e. to both the 1222 C and the C++ compilers) when building for the SDK. When building in 1223 the ``nativesdk-`` context, :term:`CPPFLAGS` is set 1224 to the value of this variable by default. 1225 1226 :term:`BUILDSDK_CXXFLAGS` 1227 Specifies the flags to pass to the C++ compiler when building for the 1228 SDK. When building in the ``nativesdk-`` context, 1229 :term:`CXXFLAGS` is set to the value of this variable 1230 by default. 1231 1232 :term:`BUILDSDK_LDFLAGS` 1233 Specifies the flags to pass to the linker when building for the SDK. 1234 When building in the ``nativesdk-`` context, 1235 :term:`LDFLAGS` is set to the value of this variable 1236 by default. 1237 1238 :term:`BUILDSTATS_BASE` 1239 Points to the location of the directory that holds build statistics 1240 when you use and enable the :ref:`ref-classes-buildstats` class. The 1241 :term:`BUILDSTATS_BASE` directory defaults to 1242 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. 1243 1244 :term:`BUSYBOX_SPLIT_SUID` 1245 For the BusyBox recipe, specifies whether to split the output 1246 executable file into two parts: one for features that require 1247 ``setuid root``, and one for the remaining features (i.e. those that 1248 do not require ``setuid root``). 1249 1250 The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in 1251 splitting the output executable file. Set the variable to "0" to get 1252 a single output executable file. 1253 1254 :term:`BZRDIR` 1255 See :term:`bitbake:BZRDIR` in the BitBake manual. 1256 1257 :term:`CACHE` 1258 Specifies the directory BitBake uses to store a cache of the 1259 :term:`Metadata` so it does not need to be parsed every time 1260 BitBake is started. 1261 1262 :term:`CARGO_INSTALL_LIBRARIES` 1263 When inheriting the :ref:`ref-classes-cargo` class, the variable 1264 :term:`CARGO_INSTALL_LIBRARIES` can be set to a non-empty value by 1265 individual recipes to enable the installation of the libraries the 1266 recipe has built in ``${B}/target/${CARGO_TARGET_SUBDIR}`` (files ending 1267 with ``.so`` or ``.rlib``). By default this variable is not defined and 1268 libraries are not installed, to replicate the behavior of the ``cargo 1269 install`` command. 1270 1271 :term:`CC` 1272 The minimal command and arguments used to run the C compiler. 1273 1274 :term:`CFLAGS` 1275 Specifies the flags to pass to the C compiler. This variable is 1276 exported to an environment variable and thus made visible to the 1277 software being built during the compilation step. 1278 1279 Default initialization for :term:`CFLAGS` varies depending on what is 1280 being built: 1281 1282 - :term:`TARGET_CFLAGS` when building for the 1283 target 1284 1285 - :term:`BUILD_CFLAGS` when building for the 1286 build host (i.e. ``-native``) 1287 1288 - :term:`BUILDSDK_CFLAGS` when building for 1289 an SDK (i.e. ``nativesdk-``) 1290 1291 :term:`CHECKLAYER_REQUIRED_TESTS` 1292 The :term:`CHECKLAYER_REQUIRED_TESTS` variable lists the QA tests that are 1293 required to be enabled to pass the Yocto Project Compatible status for a 1294 layer. It is meant to be a read-only variable and any change to the 1295 variable may be done with the approval of the :oe_wiki:`Technical Steering 1296 Committee (TSC) </TSC>`. 1297 1298 For more information on the Yocto Project Compatible status, see 1299 the :ref:`dev-manual/layers:Making Sure Your Layer is Compatible With 1300 Yocto Project` section of the Yocto Project Development Manual. 1301 1302 :term:`CLASSOVERRIDE` 1303 An internal variable specifying the special class override that 1304 should currently apply (e.g. "class-target", "class-native", and so 1305 forth). The classes that use this variable (e.g. 1306 :ref:`ref-classes-native`, :ref:`ref-classes-nativesdk`, and so forth) 1307 set the variable to appropriate values. 1308 1309 .. note:: 1310 1311 :term:`CLASSOVERRIDE` gets its default "class-target" value from the 1312 ``bitbake.conf`` file. 1313 1314 As an example, the following override allows you to install extra 1315 files, but only when building for the target:: 1316 1317 do_install:append:class-target() { 1318 install my-extra-file ${D}${sysconfdir} 1319 } 1320 1321 Here is an example where ``FOO`` is set to 1322 "native" when building for the build host, and to "other" when not 1323 building for the build host:: 1324 1325 FOO:class-native = "native" 1326 FOO = "other" 1327 1328 The underlying mechanism behind :term:`CLASSOVERRIDE` is simply 1329 that it is included in the default value of 1330 :term:`OVERRIDES`. 1331 1332 :term:`CLEANBROKEN` 1333 If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the 1334 ``make clean`` command does not work for the software being built. 1335 Consequently, the OpenEmbedded build system will not try to run 1336 ``make clean`` during the :ref:`ref-tasks-configure` 1337 task, which is the default behavior. 1338 1339 :term:`COMBINED_FEATURES` 1340 Provides a list of hardware features that are enabled in both 1341 :term:`MACHINE_FEATURES` and 1342 :term:`DISTRO_FEATURES`. This select list of 1343 features contains features that make sense to be controlled both at 1344 the machine and distribution configuration level. For example, the 1345 "bluetooth" feature requires hardware support but should also be 1346 optional at the distribution level, in case the hardware supports 1347 Bluetooth but you do not ever intend to use it. 1348 1349 :term:`COMMERCIAL_AUDIO_PLUGINS` 1350 This variable is specific to the :yocto_git:`GStreamer recipes 1351 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. 1352 It allows to build the GStreamer `"ugly" 1353 <https://github.com/GStreamer/gst-plugins-ugly>`__ and 1354 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins. 1355 1356 See the :ref:`dev-manual/licenses:other variables related to commercial licenses` 1357 section for usage details. 1358 1359 :term:`COMMERCIAL_VIDEO_PLUGINS` 1360 This variable is specific to the :yocto_git:`GStreamer recipes 1361 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. 1362 It allows to build the GStreamer `"ugly" 1363 <https://github.com/GStreamer/gst-plugins-ugly>`__ and 1364 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins. 1365 1366 See the :ref:`dev-manual/licenses:other variables related to commercial licenses` 1367 section for usage details. 1368 1369 :term:`COMMON_LICENSE_DIR` 1370 Points to ``meta/files/common-licenses`` in the 1371 :term:`Source Directory`, which is where generic license 1372 files reside. 1373 1374 :term:`COMPATIBLE_HOST` 1375 A regular expression that resolves to one or more hosts (when the 1376 recipe is native) or one or more targets (when the recipe is 1377 non-native) with which a recipe is compatible. The regular expression 1378 is matched against :term:`HOST_SYS`. You can use the 1379 variable to stop recipes from being built for classes of systems with 1380 which the recipes are not compatible. Stopping these builds is 1381 particularly useful with kernels. The variable also helps to increase 1382 parsing speed since the build system skips parsing recipes not 1383 compatible with the current system. 1384 1385 :term:`COMPATIBLE_MACHINE` 1386 A regular expression that resolves to one or more target machines 1387 with which a recipe is compatible. The regular expression is matched 1388 against :term:`MACHINEOVERRIDES`. You can use 1389 the variable to stop recipes from being built for machines with which 1390 the recipes are not compatible. Stopping these builds is particularly 1391 useful with kernels. The variable also helps to increase parsing 1392 speed since the build system skips parsing recipes not compatible 1393 with the current machine. 1394 1395 If one wants to have a recipe only available for some architectures 1396 (here ``aarch64`` and ``mips64``), the following can be used:: 1397 1398 COMPATIBLE_MACHINE = "^$" 1399 COMPATIBLE_MACHINE:arch64 = "^(aarch64)$" 1400 COMPATIBLE_MACHINE:mips64 = "^(mips64)$" 1401 1402 The first line means "match all machines whose :term:`MACHINEOVERRIDES` 1403 contains the empty string", which will always be none. 1404 1405 The second is for matching all machines whose :term:`MACHINEOVERRIDES` 1406 contains one override which is exactly ``aarch64``. 1407 1408 The third is for matching all machines whose :term:`MACHINEOVERRIDES` 1409 contains one override which is exactly ``mips64``. 1410 1411 The same could be achieved with:: 1412 1413 COMPATIBLE_MACHINE = "^(aarch64|mips64)$" 1414 1415 .. note:: 1416 1417 When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from 1418 native, the recipe is always skipped. All native recipes must be 1419 entirely target independent and should not rely on :term:`MACHINE`. 1420 1421 :term:`COMPLEMENTARY_GLOB` 1422 Defines wildcards to match when installing a list of complementary 1423 packages for all the packages explicitly (or implicitly) installed in 1424 an image. 1425 1426 The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching 1427 (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), 1428 which is similar to the Unix style pathname pattern expansion 1429 (`glob <https://docs.python.org/3/library/glob.html>`__). 1430 1431 The resulting list of complementary packages is associated with an 1432 item that can be added to 1433 :term:`IMAGE_FEATURES`. An example usage of 1434 this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES` 1435 will install -dev packages (containing headers and other development 1436 files) for every package in the image. 1437 1438 To add a new feature item pointing to a wildcard, use a variable flag 1439 to specify the feature item name and use the value to specify the 1440 wildcard. Here is an example:: 1441 1442 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' 1443 1444 .. note:: 1445 1446 When installing complementary packages, recommends relationships 1447 (set via :term:`RRECOMMENDS`) are always ignored. 1448 1449 :term:`COMPONENTS_DIR` 1450 Stores sysroot components for each recipe. The OpenEmbedded build 1451 system uses :term:`COMPONENTS_DIR` when constructing recipe-specific 1452 sysroots for other recipes. 1453 1454 The default is 1455 "``${``\ :term:`STAGING_DIR`\ ``}-components``." 1456 (i.e. 1457 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). 1458 1459 :term:`CONF_VERSION` 1460 Tracks the version of the local configuration file (i.e. 1461 ``local.conf``). The value for :term:`CONF_VERSION` increments each time 1462 ``build/conf/`` compatibility changes. 1463 1464 :term:`CONFFILES` 1465 Identifies editable or configurable files that are part of a package. 1466 If the Package Management System (PMS) is being used to update 1467 packages on the target system, it is possible that configuration 1468 files you have changed after the original installation and that you 1469 now want to remain unchanged are overwritten. In other words, 1470 editable files might exist in the package that you do not want reset 1471 as part of the package update process. You can use the :term:`CONFFILES` 1472 variable to list the files in the package that you wish to prevent 1473 the PMS from overwriting during this update process. 1474 1475 To use the :term:`CONFFILES` variable, provide a package name override 1476 that identifies the resulting package. Then, provide a 1477 space-separated list of files. Here is an example:: 1478 1479 CONFFILES:${PN} += "${sysconfdir}/file1 \ 1480 ${sysconfdir}/file2 ${sysconfdir}/file3" 1481 1482 There is a relationship between the :term:`CONFFILES` and :term:`FILES` 1483 variables. The files listed within :term:`CONFFILES` must be a subset of 1484 the files listed within :term:`FILES`. Because the configuration files 1485 you provide with :term:`CONFFILES` are simply being identified so that 1486 the PMS will not overwrite them, it makes sense that the files must 1487 already be included as part of the package through the :term:`FILES` 1488 variable. 1489 1490 .. note:: 1491 1492 When specifying paths as part of the :term:`CONFFILES` variable, it is 1493 good practice to use appropriate path variables. 1494 For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` 1495 rather than ``/usr/bin``. You can find a list of these variables at 1496 the top of the ``meta/conf/bitbake.conf`` file in the 1497 :term:`Source Directory`. 1498 1499 :term:`CONFIG_INITRAMFS_SOURCE` 1500 Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The 1501 OpenEmbedded build system receives and uses this kernel Kconfig 1502 variable as an environment variable. By default, the variable is set 1503 to null (""). 1504 1505 The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive 1506 with a ``.cpio`` suffix or a space-separated list of directories and 1507 files for building the :term:`Initramfs` image. A cpio archive should contain 1508 a filesystem archive to be used as an :term:`Initramfs` image. Directories 1509 should contain a filesystem layout to be included in the :term:`Initramfs` 1510 image. Files should contain entries according to the format described 1511 by the ``usr/gen_init_cpio`` program in the kernel tree. 1512 1513 If you specify multiple directories and files, the :term:`Initramfs` image 1514 will be the aggregate of all of them. 1515 1516 For information on creating an :term:`Initramfs`, see the 1517 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 1518 in the Yocto Project Development Tasks Manual. 1519 1520 :term:`CONFIG_SITE` 1521 A list of files that contains ``autoconf`` test results relevant to 1522 the current build. This variable is used by the Autotools utilities 1523 when running ``configure``. 1524 1525 :term:`CONFIGURE_FLAGS` 1526 The minimal arguments for GNU configure. 1527 1528 :term:`CONFLICT_DISTRO_FEATURES` 1529 When inheriting the :ref:`ref-classes-features_check` 1530 class, this variable identifies distribution features that would be 1531 in conflict should the recipe be built. In other words, if the 1532 :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also 1533 appears in :term:`DISTRO_FEATURES` within the current configuration, then 1534 the recipe will be skipped, and if the build system attempts to build 1535 the recipe then an error will be triggered. 1536 1537 :term:`CONVERSION_CMD` 1538 This variable is used for storing image conversion commands. 1539 Image conversion can convert an image into different objects like: 1540 1541 - Compressed version of the image 1542 1543 - Checksums for the image 1544 1545 An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types` 1546 class is:: 1547 1548 CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}" 1549 1550 :term:`COPY_LIC_DIRS` 1551 If set to "1" along with the 1552 :term:`COPY_LIC_MANIFEST` variable, the 1553 OpenEmbedded build system copies into the image the license files, 1554 which are located in ``/usr/share/common-licenses``, for each 1555 package. The license files are placed in directories within the image 1556 itself during build time. 1557 1558 .. note:: 1559 1560 The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for 1561 newly installed packages to an image, which might be most suitable for 1562 read-only filesystems that cannot be upgraded. See the 1563 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1564 You can also reference the ":ref:`dev-manual/licenses:providing license text`" 1565 section in the Yocto Project Development Tasks Manual for 1566 information on providing license text. 1567 1568 :term:`COPY_LIC_MANIFEST` 1569 If set to "1", the OpenEmbedded build system copies the license 1570 manifest for the image to 1571 ``/usr/share/common-licenses/license.manifest`` within the image 1572 itself during build time. 1573 1574 .. note:: 1575 1576 The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for 1577 newly installed packages to an image, which might be most suitable for 1578 read-only filesystems that cannot be upgraded. See the 1579 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1580 You can also reference the ":ref:`dev-manual/licenses:providing license text`" 1581 section in the Yocto Project Development Tasks Manual for 1582 information on providing license text. 1583 1584 :term:`COPYLEFT_LICENSE_EXCLUDE` 1585 A space-separated list of licenses to exclude from the source archived by 1586 the :ref:`ref-classes-archiver` class. In other words, if a license in a 1587 recipe's :term:`LICENSE` value is in the value of 1588 :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the 1589 class. 1590 1591 .. note:: 1592 1593 The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the 1594 :term:`COPYLEFT_LICENSE_INCLUDE` variable. 1595 1596 The default value, which is "CLOSED Proprietary", for 1597 :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the 1598 :ref:`ref-classes-copyleft_filter` class, which 1599 is inherited by the :ref:`ref-classes-archiver` class. 1600 1601 :term:`COPYLEFT_LICENSE_INCLUDE` 1602 A space-separated list of licenses to include in the source archived 1603 by the :ref:`ref-classes-archiver` class. In other 1604 words, if a license in a recipe's :term:`LICENSE` 1605 value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its 1606 source is archived by the class. 1607 1608 The default value is set by the :ref:`ref-classes-copyleft_filter` class, 1609 which is inherited by the :ref:`ref-classes-archiver` class. The default 1610 value includes "GPL*", "LGPL*", and "AGPL*". 1611 1612 :term:`COPYLEFT_PN_EXCLUDE` 1613 A list of recipes to exclude in the source archived by the 1614 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_EXCLUDE` 1615 variable overrides the license inclusion and exclusion caused through the 1616 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` 1617 variables, respectively. 1618 1619 The default value, which is "" indicating to not explicitly exclude 1620 any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the 1621 :ref:`ref-classes-copyleft_filter` class, which is inherited by the 1622 :ref:`ref-classes-archiver` class. 1623 1624 :term:`COPYLEFT_PN_INCLUDE` 1625 A list of recipes to include in the source archived by the 1626 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_INCLUDE` 1627 variable overrides the license inclusion and exclusion caused through the 1628 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` 1629 variables, respectively. 1630 1631 The default value, which is "" indicating to not explicitly include 1632 any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the 1633 :ref:`ref-classes-copyleft_filter` class, which is inherited by the 1634 :ref:`ref-classes-archiver` class. 1635 1636 :term:`COPYLEFT_RECIPE_TYPES` 1637 A space-separated list of recipe types to include in the source 1638 archived by the :ref:`archiver <ref-classes-archiver>` class. 1639 Recipe types are ``target``, :ref:`ref-classes-native`, 1640 :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`, 1641 :ref:`ref-classes-crosssdk`, and :ref:`ref-classes-cross-canadian`. 1642 1643 The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES` 1644 is set by the :ref:`ref-classes-copyleft_filter` class, which is 1645 inherited by the :ref:`ref-classes-archiver` class. 1646 1647 :term:`CORE_IMAGE_EXTRA_INSTALL` 1648 Specifies the list of packages to be added to the image. You should 1649 only set this variable in the ``local.conf`` configuration file found 1650 in the :term:`Build Directory`. 1651 1652 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer 1653 supported. 1654 1655 :term:`COREBASE` 1656 Specifies the parent directory of the OpenEmbedded-Core Metadata 1657 layer (i.e. ``meta``). 1658 1659 It is an important distinction that :term:`COREBASE` points to the parent 1660 of this layer and not the layer itself. Consider an example where you 1661 have cloned the Poky Git repository and retained the ``poky`` name 1662 for your local copy of the repository. In this case, :term:`COREBASE` 1663 points to the ``poky`` folder because it is the parent directory of 1664 the ``poky/meta`` layer. 1665 1666 :term:`COREBASE_FILES` 1667 Lists files from the :term:`COREBASE` directory that 1668 should be copied other than the layers listed in the 1669 ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows 1670 to copy metadata from the OpenEmbedded build system 1671 into the extensible SDK. 1672 1673 Explicitly listing files in :term:`COREBASE` is needed because it 1674 typically contains build directories and other files that should not 1675 normally be copied into the extensible SDK. Consequently, the value 1676 of :term:`COREBASE_FILES` is used in order to only copy the files that 1677 are actually needed. 1678 1679 :term:`CPP` 1680 The minimal command and arguments used to run the C preprocessor. 1681 1682 :term:`CPPFLAGS` 1683 Specifies the flags to pass to the C pre-processor (i.e. to both the 1684 C and the C++ compilers). This variable is exported to an environment 1685 variable and thus made visible to the software being built during the 1686 compilation step. 1687 1688 Default initialization for :term:`CPPFLAGS` varies depending on what is 1689 being built: 1690 1691 - :term:`TARGET_CPPFLAGS` when building for 1692 the target 1693 1694 - :term:`BUILD_CPPFLAGS` when building for the 1695 build host (i.e. ``-native``) 1696 1697 - :term:`BUILDSDK_CPPFLAGS` when building 1698 for an SDK (i.e. ``nativesdk-``) 1699 1700 :term:`CROSS_COMPILE` 1701 The toolchain binary prefix for the target tools. The 1702 :term:`CROSS_COMPILE` variable is the same as the 1703 :term:`TARGET_PREFIX` variable. 1704 1705 .. note:: 1706 1707 The OpenEmbedded build system sets the :term:`CROSS_COMPILE` 1708 variable only in certain contexts (e.g. when building for kernel 1709 and kernel module recipes). 1710 1711 :term:`CVE_CHECK_CREATE_MANIFEST` 1712 Specifies whether to create a CVE manifest to place in the deploy 1713 directory. The default is "1". 1714 1715 :term:`CVE_CHECK_IGNORE` 1716 This variable is deprecated and should be replaced by :term:`CVE_STATUS`. 1717 1718 :term:`CVE_CHECK_MANIFEST_JSON` 1719 Specifies the path to the CVE manifest in JSON format. See 1720 :term:`CVE_CHECK_CREATE_MANIFEST`. 1721 1722 :term:`CVE_CHECK_MANIFEST_JSON_SUFFIX` 1723 Allows to modify the JSON manifest suffix. See 1724 :term:`CVE_CHECK_MANIFEST_JSON`. 1725 1726 :term:`CVE_CHECK_REPORT_PATCHED` 1727 Specifies whether or not the :ref:`ref-classes-cve-check` 1728 class should report patched or ignored CVEs. The default is "1", but you 1729 may wish to set it to "0" if you do not need patched or ignored CVEs in 1730 the logs. 1731 1732 :term:`CVE_CHECK_SHOW_WARNINGS` 1733 Specifies whether or not the :ref:`ref-classes-cve-check` 1734 class should generate warning messages on the console when unpatched 1735 CVEs are found. The default is "1", but you may wish to set it to "0" if 1736 you are already examining/processing the logs after the build has 1737 completed and thus do not need the warning messages. 1738 1739 :term:`CVE_CHECK_SKIP_RECIPE` 1740 The list of package names (:term:`PN`) for which 1741 CVEs (Common Vulnerabilities and Exposures) are ignored. 1742 1743 :term:`CVE_DB_INCR_UPDATE_AGE_THRES` 1744 Specifies the maximum age of the CVE database in seconds for an 1745 incremental update (instead of a full-download). Use "0" to force a 1746 full-download. 1747 1748 :term:`CVE_DB_UPDATE_INTERVAL` 1749 Specifies the CVE database update interval in seconds, as used by 1750 ``cve-update-db-native``. The default value is "86400" i.e. once a day 1751 (24*60*60). If the value is set to "0" then the update will be forced 1752 every time. Alternatively, a negative value e.g. "-1" will disable 1753 updates entirely. 1754 1755 :term:`CVE_PRODUCT` 1756 In a recipe, defines the name used to match the recipe name 1757 against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__. 1758 1759 The default is ${:term:`BPN`} (except for recipes that inherit the 1760 :ref:`ref-classes-pypi` class where it is set based upon 1761 :term:`PYPI_PACKAGE`). If it does not match the name in the NIST CVE 1762 database or matches with multiple entries in the database, the default 1763 value needs to be changed. 1764 1765 Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`:: 1766 1767 CVE_PRODUCT = "oracle_berkeley_db berkeley_db" 1768 1769 Sometimes the product name is not specific enough, for example 1770 "tar" has been matching CVEs for the GNU ``tar`` package and also 1771 the ``node-tar`` node.js extension. To avoid this problem, use the 1772 vendor name as a prefix. The syntax for this is:: 1773 1774 CVE_PRODUCT = "vendor:package" 1775 1776 :term:`CVE_STATUS` 1777 The CVE ID which is patched or should be ignored. Here is 1778 an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`:: 1779 1780 CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows" 1781 1782 It has the format "reason: description" and the description is optional. 1783 The Reason is mapped to the final CVE state by mapping via 1784 :term:`CVE_CHECK_STATUSMAP`. See :ref:`dev-manual/vulnerabilities:fixing vulnerabilities in recipes` 1785 for details. 1786 1787 :term:`CVE_STATUS_GROUPS` 1788 If there are many CVEs with the same status and reason, they can by simplified by using this 1789 variable instead of many similar lines with :term:`CVE_STATUS`:: 1790 1791 CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED" 1792 1793 CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002" 1794 CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows" 1795 CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004" 1796 CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally" 1797 1798 :term:`CVE_CHECK_STATUSMAP` 1799 Mapping variable for all possible reasons of :term:`CVE_STATUS`: 1800 ``Patched``, ``Unpatched`` and ``Ignored``. 1801 See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details:: 1802 1803 CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored" 1804 1805 :term:`CVE_VERSION` 1806 In a recipe, defines the version used to match the recipe version 1807 against the version in the `NIST CVE database <https://nvd.nist.gov/>`__ 1808 when usign :ref:`ref-classes-cve-check`. 1809 1810 The default is ${:term:`PV`} but if recipes use custom version numbers 1811 which do not map to upstream software component release versions and the versions 1812 used in the CVE database, then this variable can be used to set the 1813 version number for :ref:`ref-classes-cve-check`. Example:: 1814 1815 CVE_VERSION = "2.39" 1816 1817 :term:`CVSDIR` 1818 The directory in which files checked out under the CVS system are 1819 stored. 1820 1821 :term:`CXX` 1822 The minimal command and arguments used to run the C++ compiler. 1823 1824 :term:`CXXFLAGS` 1825 Specifies the flags to pass to the C++ compiler. This variable is 1826 exported to an environment variable and thus made visible to the 1827 software being built during the compilation step. 1828 1829 Default initialization for :term:`CXXFLAGS` varies depending on what is 1830 being built: 1831 1832 - :term:`TARGET_CXXFLAGS` when building for 1833 the target 1834 1835 - :term:`BUILD_CXXFLAGS` when building for the 1836 build host (i.e. ``-native``) 1837 1838 - :term:`BUILDSDK_CXXFLAGS` when building 1839 for an SDK (i.e. ``nativesdk-``) 1840 1841 :term:`D` 1842 The destination directory. The location in the :term:`Build Directory` 1843 where components are installed by the 1844 :ref:`ref-tasks-install` task. This location defaults 1845 to:: 1846 1847 ${WORKDIR}/image 1848 1849 .. note:: 1850 1851 Tasks that read from or write to this directory should run under 1852 :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`. 1853 1854 :term:`DATE` 1855 The date the build was started. Dates appear using the year, month, 1856 and day (YMD) format (e.g. "20150209" for February 9th, 2015). 1857 1858 :term:`DATETIME` 1859 The date and time on which the current build started. The format is 1860 suitable for timestamps. 1861 1862 :term:`DEBIAN_NOAUTONAME` 1863 When the :ref:`ref-classes-debian` class is inherited, 1864 which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a 1865 particular package should not be renamed according to Debian library 1866 package naming. You must use the package name as an override when you 1867 set this variable. Here is an example from the ``fontconfig`` recipe:: 1868 1869 DEBIAN_NOAUTONAME:fontconfig-utils = "1" 1870 1871 :term:`DEBIANNAME` 1872 When the :ref:`ref-classes-debian` class is inherited, 1873 which is the default behavior, :term:`DEBIANNAME` allows you to override 1874 the library name for an individual package. Overriding the library 1875 name in these cases is rare. You must use the package name as an 1876 override when you set this variable. Here is an example from the 1877 ``dbus`` recipe:: 1878 1879 DEBIANNAME:${PN} = "dbus-1" 1880 1881 :term:`DEBUG_BUILD` 1882 Specifies to build packages with debugging information. This 1883 influences the value of the :term:`SELECTED_OPTIMIZATION` variable. 1884 1885 :term:`DEBUG_OPTIMIZATION` 1886 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when 1887 compiling a system for debugging. This variable defaults to "-O 1888 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". 1889 1890 :term:`DEBUG_PREFIX_MAP` 1891 Allows to set C compiler options, such as ``-fdebug-prefix-map``, 1892 ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to 1893 replace build-time paths by install-time ones in the debugging sections 1894 of binaries. This makes compiler output files location independent, 1895 at the cost of having to pass an extra command to tell the debugger 1896 where source files are. 1897 1898 This is used by the Yocto Project to guarantee 1899 :doc:`/test-manual/reproducible-builds` even when the source code of 1900 a package uses the ``__FILE__`` or ``assert()`` macros. See the 1901 `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__ 1902 website for details. 1903 1904 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 1905 not intended to be user-configurable. 1906 1907 :term:`DEFAULT_PREFERENCE` 1908 Specifies a weak bias for recipe selection priority. 1909 1910 The most common usage of this is variable is to set it to "-1" within 1911 a recipe for a development version of a piece of software. Using the 1912 variable in this way causes the stable version of the recipe to build 1913 by default in the absence of :term:`PREFERRED_VERSION` being used to 1914 build the development version. 1915 1916 .. note:: 1917 1918 The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden 1919 by :term:`BBFILE_PRIORITY` if that variable is different between two 1920 layers that contain different versions of the same recipe. 1921 1922 :term:`DEFAULT_TIMEZONE` 1923 Specifies the time zone set in the image. 1924 1925 This variable causes the ``tzdata`` package to configure 1926 ``${sysconfdir}/localtime`` accordingly. Valid values are all files 1927 found in ``/usr/share/zoneinfo`` like ``CET`` or ``Asia/Baku``. 1928 1929 :term:`DEFAULTTUNE` 1930 The default CPU and Application Binary Interface (ABI) tunings (i.e. 1931 the "tune") used by the OpenEmbedded build system. The 1932 :term:`DEFAULTTUNE` helps define 1933 :term:`TUNE_FEATURES`. 1934 1935 The default tune is either implicitly or explicitly set by the 1936 machine (:term:`MACHINE`). However, you can override 1937 the setting using available tunes as defined with 1938 :term:`AVAILTUNES`. 1939 1940 :term:`DEPENDS` 1941 Lists a recipe's build-time dependencies. These are dependencies on 1942 other recipes whose contents (e.g. headers and shared libraries) are 1943 needed by the recipe at build time. 1944 1945 As an example, consider a recipe ``foo`` that contains the following 1946 assignment:: 1947 1948 DEPENDS = "bar" 1949 1950 The practical effect of the previous assignment is that all files 1951 installed by bar will be available in the appropriate staging sysroot, 1952 given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time 1953 the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is 1954 implemented by having :ref:`ref-tasks-configure` depend on the 1955 :ref:`ref-tasks-populate_sysroot` task of each recipe listed in 1956 :term:`DEPENDS`, through a 1957 ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` 1958 declaration in the :ref:`ref-classes-base` class. 1959 1960 .. note:: 1961 1962 It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST` 1963 explicitly. The standard classes and build-related variables are 1964 configured to automatically use the appropriate staging sysroots. 1965 1966 As another example, :term:`DEPENDS` can also be used to add utilities 1967 that run on the build machine during the build. For example, a recipe 1968 that makes use of a code generator built by the recipe ``codegen`` 1969 might have the following:: 1970 1971 DEPENDS = "codegen-native" 1972 1973 For more 1974 information, see the :ref:`ref-classes-native` class and 1975 the :term:`EXTRANATIVEPATH` variable. 1976 1977 .. note:: 1978 1979 - :term:`DEPENDS` is a list of recipe names. Or, to be more precise, 1980 it is a list of :term:`PROVIDES` names, which 1981 usually match recipe names. Putting a package name such as 1982 "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo" 1983 instead, as this will put files from all the packages that make 1984 up ``foo``, which includes those from ``foo-dev``, into the 1985 sysroot. 1986 1987 - One recipe having another recipe in :term:`DEPENDS` does not by 1988 itself add any runtime dependencies between the packages 1989 produced by the two recipes. However, as explained in the 1990 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 1991 section in the Yocto Project Overview and Concepts Manual, 1992 runtime dependencies will often be added automatically, meaning 1993 :term:`DEPENDS` alone is sufficient for most recipes. 1994 1995 - Counterintuitively, :term:`DEPENDS` is often necessary even for 1996 recipes that install precompiled components. For example, if 1997 ``libfoo`` is a precompiled library that links against 1998 ``libbar``, then linking against ``libfoo`` requires both 1999 ``libfoo`` and ``libbar`` to be available in the sysroot. 2000 Without a :term:`DEPENDS` from the recipe that installs ``libfoo`` 2001 to the recipe that installs ``libbar``, other recipes might 2002 fail to link against ``libfoo``. 2003 2004 For information on runtime dependencies, see the :term:`RDEPENDS` 2005 variable. You can also see the 2006 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and 2007 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" 2008 sections in the BitBake User Manual for additional information on tasks 2009 and dependencies. 2010 2011 :term:`DEPLOY_DIR` 2012 Points to the general area that the OpenEmbedded build system uses to 2013 place images, packages, SDKs, and other output files that are ready 2014 to be used outside of the build system. By default, this directory 2015 resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``. 2016 2017 For more information on the structure of the Build Directory, see 2018 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 2019 For more detail on the contents of the ``deploy`` directory, see the 2020 ":ref:`overview-manual/concepts:images`", 2021 ":ref:`overview-manual/concepts:package feeds`", and 2022 ":ref:`overview-manual/concepts:application development sdk`" sections all in the 2023 Yocto Project Overview and Concepts Manual. 2024 2025 :term:`DEPLOY_DIR_DEB` 2026 Points to the area that the OpenEmbedded build system uses to place 2027 Debian packages that are ready to be used outside of the build 2028 system. This variable applies only when :term:`PACKAGE_CLASSES` contains 2029 ":ref:`ref-classes-package_deb`". 2030 2031 The BitBake configuration file initially defines the 2032 :term:`DEPLOY_DIR_DEB` variable as a sub-folder of 2033 :term:`DEPLOY_DIR`:: 2034 2035 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" 2036 2037 The :ref:`ref-classes-package_deb` class uses the 2038 :term:`DEPLOY_DIR_DEB` variable to make sure the 2039 :ref:`ref-tasks-package_write_deb` task 2040 writes Debian packages into the appropriate folder. For more 2041 information on how packaging works, see the 2042 ":ref:`overview-manual/concepts:package feeds`" section 2043 in the Yocto Project Overview and Concepts Manual. 2044 2045 :term:`DEPLOY_DIR_IMAGE` 2046 Points to the area that the OpenEmbedded build system uses to place 2047 images and other associated output files that are ready to be 2048 deployed onto the target machine. The directory is machine-specific 2049 as it contains the ``${MACHINE}`` name. By default, this directory 2050 resides within the :term:`Build Directory` as 2051 ``${DEPLOY_DIR}/images/${MACHINE}/``. 2052 2053 It must not be used directly in recipes when deploying files. Instead, 2054 it's only useful when a recipe needs to "read" a file already deployed 2055 by a dependency. So, it should be filled with the contents of 2056 :term:`DEPLOYDIR` by the :ref:`ref-classes-deploy` class or with the 2057 contents of :term:`IMGDEPLOYDIR` by the :ref:`ref-classes-image` class. 2058 2059 For more information on the structure of the :term:`Build Directory`, see 2060 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 2061 For more detail on the contents of the ``deploy`` directory, see the 2062 ":ref:`overview-manual/concepts:images`" and 2063 ":ref:`overview-manual/concepts:application development sdk`" sections both in 2064 the Yocto Project Overview and Concepts Manual. 2065 2066 :term:`DEPLOY_DIR_IPK` 2067 Points to the area that the OpenEmbedded build system uses to place 2068 IPK packages that are ready to be used outside of the build system. 2069 This variable applies only when :term:`PACKAGE_CLASSES` contains 2070 ":ref:`ref-classes-package_ipk`". 2071 2072 The BitBake configuration file initially defines this variable as a 2073 sub-folder of :term:`DEPLOY_DIR`:: 2074 2075 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" 2076 2077 The :ref:`ref-classes-package_ipk` class uses the :term:`DEPLOY_DIR_IPK` 2078 variable to make sure the :ref:`ref-tasks-package_write_ipk` task 2079 writes IPK packages into the appropriate folder. For more information 2080 on how packaging works, see the 2081 ":ref:`overview-manual/concepts:package feeds`" section 2082 in the Yocto Project Overview and Concepts Manual. 2083 2084 :term:`DEPLOY_DIR_RPM` 2085 Points to the area that the OpenEmbedded build system uses to place 2086 RPM packages that are ready to be used outside of the build system. 2087 This variable applies only when :term:`PACKAGE_CLASSES` contains 2088 ":ref:`ref-classes-package_rpm`". 2089 2090 The BitBake configuration file initially defines this variable as a 2091 sub-folder of :term:`DEPLOY_DIR`:: 2092 2093 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" 2094 2095 The :ref:`ref-classes-package_rpm` class uses the 2096 :term:`DEPLOY_DIR_RPM` variable to make sure the 2097 :ref:`ref-tasks-package_write_rpm` task 2098 writes RPM packages into the appropriate folder. For more information 2099 on how packaging works, see the 2100 ":ref:`overview-manual/concepts:package feeds`" section 2101 in the Yocto Project Overview and Concepts Manual. 2102 2103 :term:`DEPLOYDIR` 2104 When inheriting the :ref:`ref-classes-deploy` class, the 2105 :term:`DEPLOYDIR` points to a temporary work area for deployed files that 2106 is set in the :ref:`ref-classes-deploy` class as follows:: 2107 2108 DEPLOYDIR = "${WORKDIR}/deploy-${PN}" 2109 2110 Recipes inheriting the :ref:`ref-classes-deploy` class should copy files to be 2111 deployed into :term:`DEPLOYDIR`, and the class will take care of copying 2112 them into :term:`DEPLOY_DIR_IMAGE` 2113 afterwards. 2114 2115 :term:`DESCRIPTION` 2116 The package description used by package managers. If not set, 2117 :term:`DESCRIPTION` takes the value of the :term:`SUMMARY` 2118 variable. 2119 2120 :term:`DEV_PKG_DEPENDENCY` 2121 Provides an easy way for recipes to disable or adjust the runtime recommendation 2122 (:term:`RRECOMMENDS`) of the ``${PN}-dev`` package on the main 2123 (``${PN}``) package. 2124 2125 :term:`DISABLE_STATIC` 2126 Used in order to disable static linking by default (in order to save 2127 space, since static libraries are often unused in embedded systems.) 2128 The default value is " --disable-static", however it can be set to "" 2129 in order to enable static linking if desired. Certain recipes do this 2130 individually, and also there is a 2131 ``meta/conf/distro/include/no-static-libs.inc`` include file that 2132 disables static linking for a number of recipes. Some software 2133 packages or build tools (such as CMake) have explicit support for 2134 enabling / disabling static linking, and in those cases 2135 :term:`DISABLE_STATIC` is not used. 2136 2137 :term:`DISTRO` 2138 The short name of the distribution. For information on the long name 2139 of the distribution, see the :term:`DISTRO_NAME` 2140 variable. 2141 2142 The :term:`DISTRO` variable corresponds to a distribution configuration 2143 file whose root name is the same as the variable's argument and whose 2144 filename extension is ``.conf``. For example, the distribution 2145 configuration file for the Poky distribution is named ``poky.conf`` 2146 and resides in the ``meta-poky/conf/distro`` directory of the 2147 :term:`Source Directory`. 2148 2149 Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as 2150 follows:: 2151 2152 DISTRO = "poky" 2153 2154 Distribution configuration files are located in a ``conf/distro`` 2155 directory within the :term:`Metadata` that contains the 2156 distribution configuration. The value for :term:`DISTRO` must not contain 2157 spaces, and is typically all lower-case. 2158 2159 .. note:: 2160 2161 If the :term:`DISTRO` variable is blank, a set of default configurations 2162 are used, which are specified within 2163 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2164 2165 :term:`DISTRO_CODENAME` 2166 Specifies a codename for the distribution being built. 2167 2168 :term:`DISTRO_EXTRA_RDEPENDS` 2169 Specifies a list of distro-specific packages to add to all images. 2170 This variable takes effect through ``packagegroup-base`` so the 2171 variable only really applies to the more full-featured images that 2172 include ``packagegroup-base``. You can use this variable to keep 2173 distro policy out of generic images. As with all other distro 2174 variables, you set this variable in the distro ``.conf`` file. 2175 2176 :term:`DISTRO_EXTRA_RRECOMMENDS` 2177 Specifies a list of distro-specific packages to add to all images if 2178 the packages exist. The packages might not exist or be empty (e.g. 2179 kernel modules). The list of packages are automatically installed but 2180 you can remove them. 2181 2182 :term:`DISTRO_FEATURES` 2183 The software support you want in your distribution for various 2184 features. You define your distribution features in the distribution 2185 configuration file. 2186 2187 In most cases, the presence or absence of a feature in 2188 :term:`DISTRO_FEATURES` is translated to the appropriate option supplied 2189 to the configure script during the 2190 :ref:`ref-tasks-configure` task for recipes that 2191 optionally support the feature. For example, specifying "x11" in 2192 :term:`DISTRO_FEATURES`, causes every piece of software built for the 2193 target that can optionally support X11 to have its X11 support 2194 enabled. 2195 2196 .. note:: 2197 2198 Just enabling :term:`DISTRO_FEATURES` alone doesn't 2199 enable feature support for packages. Mechanisms such as making 2200 :term:`PACKAGECONFIG` track :term:`DISTRO_FEATURES` are used 2201 to enable/disable package features. 2202 2203 Two more examples are Bluetooth and NFS support. For a more complete 2204 list of features that ships with the Yocto Project and that you can 2205 provide with this variable, see the ":ref:`ref-features-distro`" section. 2206 2207 :term:`DISTRO_FEATURES_BACKFILL` 2208 A space-separated list of features to be added to :term:`DISTRO_FEATURES` 2209 if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. 2210 2211 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 2212 not intended to be user-configurable. It is best to just reference 2213 the variable to see which distro features are being 2214 :ref:`backfilled <ref-features-backfill>` for all distro configurations. 2215 2216 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 2217 A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL` 2218 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added 2219 to :term:`DISTRO_FEATURES`) during the build. 2220 2221 This corresponds to an opt-out mechanism. When new default distro 2222 features are introduced, distribution maintainers can review (`consider`) 2223 them and decide to exclude them from the 2224 :ref:`backfilled <ref-features-backfill>` features. Therefore, the 2225 combination of :term:`DISTRO_FEATURES_BACKFILL` and 2226 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to 2227 add new default features without breaking existing distributions. 2228 2229 2230 :term:`DISTRO_FEATURES_DEFAULT` 2231 A convenience variable that gives you the default list of distro 2232 features with the exception of any features specific to the C library 2233 (``libc``). 2234 2235 When creating a custom distribution, you might find it useful to be 2236 able to reuse the default 2237 :term:`DISTRO_FEATURES` options without the 2238 need to write out the full set. Here is an example that uses 2239 :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file:: 2240 2241 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" 2242 2243 :term:`DISTRO_FEATURES_FILTER_NATIVE` 2244 Specifies a list of features that if present in the target 2245 :term:`DISTRO_FEATURES` value should be 2246 included in :term:`DISTRO_FEATURES` when building native recipes. This 2247 variable is used in addition to the features filtered using the 2248 :term:`DISTRO_FEATURES_NATIVE` 2249 variable. 2250 2251 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` 2252 Specifies a list of features that if present in the target 2253 :term:`DISTRO_FEATURES` value should be included in 2254 :term:`DISTRO_FEATURES` when building :ref:`ref-classes-nativesdk` 2255 recipes. This variable is used in addition to the features filtered using 2256 the :term:`DISTRO_FEATURES_NATIVESDK` variable. 2257 2258 :term:`DISTRO_FEATURES_NATIVE` 2259 Specifies a list of features that should be included in 2260 :term:`DISTRO_FEATURES` when building native 2261 recipes. This variable is used in addition to the features filtered 2262 using the 2263 :term:`DISTRO_FEATURES_FILTER_NATIVE` 2264 variable. 2265 2266 :term:`DISTRO_FEATURES_NATIVESDK` 2267 Specifies a list of features that should be included in 2268 :term:`DISTRO_FEATURES` when building 2269 :ref:`ref-classes-nativesdk` recipes. This variable is used 2270 in addition to the features filtered using the 2271 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` variable. 2272 2273 :term:`DISTRO_NAME` 2274 The long name of the distribution. For information on the short name 2275 of the distribution, see the :term:`DISTRO` variable. 2276 2277 The :term:`DISTRO_NAME` variable corresponds to a distribution 2278 configuration file whose root name is the same as the variable's 2279 argument and whose filename extension is ``.conf``. For example, the 2280 distribution configuration file for the Poky distribution is named 2281 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory 2282 of the :term:`Source Directory`. 2283 2284 Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set 2285 as follows:: 2286 2287 DISTRO_NAME = "Poky (Yocto Project Reference Distro)" 2288 2289 Distribution configuration files are located in a ``conf/distro`` 2290 directory within the :term:`Metadata` that contains the 2291 distribution configuration. 2292 2293 .. note:: 2294 2295 If the :term:`DISTRO_NAME` variable is blank, a set of default 2296 configurations are used, which are specified within 2297 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2298 2299 :term:`DISTRO_VERSION` 2300 The version of the distribution. 2301 2302 :term:`DISTROOVERRIDES` 2303 A colon-separated list of overrides specific to the current 2304 distribution. By default, this list includes the value of 2305 :term:`DISTRO`. 2306 2307 You can extend :term:`DISTROOVERRIDES` to add extra overrides that should 2308 apply to the distribution. 2309 2310 The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it 2311 is included in the default value of 2312 :term:`OVERRIDES`. 2313 2314 Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf 2315 </poky/tree/meta-poky/conf/distro/poky-tiny.conf>`:: 2316 2317 DISTROOVERRIDES = "poky:poky-tiny" 2318 2319 :term:`DL_DIR` 2320 The central download directory used by the build process to store 2321 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring 2322 for everything except Git repositories. If you want tarballs of Git 2323 repositories, use the 2324 :term:`BB_GENERATE_MIRROR_TARBALLS` 2325 variable. 2326 2327 You can set this directory by defining the :term:`DL_DIR` variable in the 2328 ``conf/local.conf`` file. This directory is self-maintaining and you 2329 should not have to touch it. By default, the directory is 2330 ``downloads`` in the :term:`Build Directory`:: 2331 2332 #DL_DIR ?= "${TOPDIR}/downloads" 2333 2334 To specify a different download directory, 2335 simply remove the comment from the line and provide your directory. 2336 2337 During a first build, the system downloads many different source code 2338 tarballs from various upstream projects. Downloading can take a 2339 while, particularly if your network connection is slow. Tarballs are 2340 all stored in the directory defined by :term:`DL_DIR` and the build 2341 system looks there first to find source tarballs. 2342 2343 .. note:: 2344 2345 When wiping and rebuilding, you can preserve this directory to 2346 speed up this part of subsequent builds. 2347 2348 You can safely share this directory between multiple builds on the 2349 same development machine. For additional information on how the build 2350 process gets source files when working behind a firewall or proxy 2351 server, see this specific question in the ":doc:`faq`" 2352 chapter. You can also refer to the 2353 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 2354 Wiki page. 2355 2356 :term:`DOC_COMPRESS` 2357 When inheriting the :ref:`ref-classes-compress_doc` 2358 class, this variable sets the compression policy used when the 2359 OpenEmbedded build system compresses manual and info pages. By 2360 default, the compression method used is gz (gzip). Other policies 2361 available are xz and bz2. 2362 2363 For information on policies and on how to use this variable, see the 2364 comments in the ``meta/classes-recipe/compress_doc.bbclass`` file. 2365 2366 :term:`DT_FILES` 2367 Space-separated list of device tree source files to compile using 2368 a recipe that inherits the :ref:`ref-classes-devicetree` class. These 2369 are relative to the :term:`DT_FILES_PATH`. 2370 2371 For convenience, both ``.dts`` and ``.dtb`` extensions can be used. 2372 2373 Use an empty string (default) to build all device tree sources within 2374 the :term:`DT_FILES_PATH` directory. 2375 2376 :term:`DT_FILES_PATH` 2377 When compiling out-of-tree device tree sources using a recipe that 2378 inherits the :ref:`ref-classes-devicetree` class, this variable specifies 2379 the path to the directory containing dts files to build. 2380 2381 Defaults to the :term:`S` directory. 2382 2383 :term:`DT_PADDING_SIZE` 2384 When inheriting the :ref:`ref-classes-devicetree` class, this variable 2385 specifies the size of padding appended to the device tree blob, used as 2386 extra space typically for additional properties during boot. 2387 2388 :term:`EFI_ARCH` 2389 The CPU architecture name within EFI standard. Set in 2390 :oe_git:`meta/conf/image-uefi.conf 2391 <openembedded-core/tree/meta/conf/image-uefi.conf>`. 2392 2393 :term:`EFI_PROVIDER` 2394 When building bootable images (i.e. where ``hddimg``, ``iso``, or 2395 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the 2396 :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The 2397 default is "grub-efi", but "systemd-boot" can be used instead. 2398 2399 See the :ref:`ref-classes-systemd-boot` and :ref:`ref-classes-image-live` 2400 classes for more information. 2401 2402 :term:`EFI_UKI_DIR` 2403 The primary place for the UKI image inside the EFI System Partition. 2404 2405 :term:`EFI_UKI_PATH` 2406 The path for the UKI image inside the root filesystem. 2407 2408 :term:`ENABLE_BINARY_LOCALE_GENERATION` 2409 Variable that controls which locales for ``glibc`` are generated 2410 during the build (useful if the target device has 64Mbytes of RAM or 2411 less). 2412 2413 :term:`ERR_REPORT_DIR` 2414 When used with the :ref:`ref-classes-report-error` class, specifies the 2415 path used for storing the debug files created by the :ref:`error reporting 2416 tool <dev-manual/error-reporting-tool:using the error reporting tool>`, 2417 which allows you to submit build errors you encounter to a central 2418 database. By default, the value of this variable is 2419 ``${``\ :term:`LOG_DIR`\ ``}/error-report``. 2420 2421 You can set :term:`ERR_REPORT_DIR` to the path you want the error 2422 reporting tool to store the debug files as follows in your 2423 ``local.conf`` file:: 2424 2425 ERR_REPORT_DIR = "path" 2426 2427 :term:`ERROR_QA` 2428 Specifies the quality assurance checks whose failures are reported as 2429 errors by the OpenEmbedded build system. You set this variable in 2430 your distribution configuration file. For a list of the checks you 2431 can control with this variable, see the 2432 ":ref:`ref-classes-insane`" section. 2433 2434 :term:`ESDK_CLASS_INHERIT_DISABLE` 2435 A list of classes to remove from the :term:`INHERIT` 2436 value globally within the extensible SDK configuration. The 2437 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the 2438 default value:: 2439 2440 ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc" 2441 2442 Some classes are not generally applicable within the extensible SDK 2443 context. You can use this variable to disable those classes. 2444 2445 For additional information on how to customize the extensible SDK's 2446 configuration, see the 2447 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2448 section in the Yocto Project Application Development and the 2449 Extensible Software Development Kit (eSDK) manual. 2450 2451 :term:`ESDK_LOCALCONF_ALLOW` 2452 A list of variables allowed through from the OpenEmbedded build 2453 system configuration into the extensible SDK configuration. By 2454 default, the list of variables is empty and is set in the 2455 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. 2456 2457 This list overrides the variables specified using the 2458 :term:`ESDK_LOCALCONF_REMOVE` variable as well as 2459 other variables automatically added due to the "/" character 2460 being found at the start of the 2461 value, which is usually indicative of being a path and thus might not 2462 be valid on the system where the SDK is installed. 2463 2464 For additional information on how to customize the extensible SDK's 2465 configuration, see the 2466 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2467 section in the Yocto Project Application Development and the 2468 Extensible Software Development Kit (eSDK) manual. 2469 2470 :term:`ESDK_LOCALCONF_REMOVE` 2471 A list of variables not allowed through from the OpenEmbedded build 2472 system configuration into the extensible SDK configuration. Usually, 2473 these are variables that are specific to the machine on which the 2474 build system is running and thus would be potentially problematic 2475 within the extensible SDK. 2476 2477 By default, :term:`ESDK_LOCALCONF_REMOVE` is set in the 2478 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and 2479 excludes the following variables: 2480 2481 - :term:`CONF_VERSION` 2482 - :term:`BB_NUMBER_THREADS` 2483 - :term:`BB_NUMBER_PARSE_THREADS` 2484 - :term:`PARALLEL_MAKE` 2485 - :term:`PRSERV_HOST` 2486 - :term:`SSTATE_MIRRORS` :term:`DL_DIR` 2487 - :term:`SSTATE_DIR` :term:`TMPDIR` 2488 - :term:`BB_SERVER_TIMEOUT` 2489 2490 For additional information on how to customize the extensible SDK's 2491 configuration, see the 2492 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2493 section in the Yocto Project Application Development and the 2494 Extensible Software Development Kit (eSDK) manual. 2495 2496 :term:`EXCLUDE_FROM_SHLIBS` 2497 Triggers the OpenEmbedded build system's shared libraries resolver to 2498 exclude an entire package when scanning for shared libraries. 2499 2500 .. note:: 2501 2502 The shared libraries resolver's functionality results in part from 2503 the internal function ``package_do_shlibs``, which is part of the 2504 :ref:`ref-tasks-package` task. You should be aware that the shared 2505 libraries resolver might implicitly define some dependencies between 2506 packages. 2507 2508 The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the 2509 :term:`PRIVATE_LIBS` variable, which excludes a 2510 package's particular libraries only and not the whole package. 2511 2512 Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a 2513 particular package:: 2514 2515 EXCLUDE_FROM_SHLIBS = "1" 2516 2517 :term:`EXCLUDE_FROM_WORLD` 2518 Directs BitBake to exclude a recipe from world builds (i.e. 2519 ``bitbake world``). During world builds, BitBake locates, parses and 2520 builds all recipes found in every layer exposed in the 2521 ``bblayers.conf`` configuration file. 2522 2523 To exclude a recipe from a world build using this variable, set the 2524 variable to "1" in the recipe. 2525 2526 .. note:: 2527 2528 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a 2529 world build in order to satisfy dependencies of other recipes. Adding 2530 a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not 2531 explicitly added to the list of build targets in a world build. 2532 2533 :term:`EXTENDPE` 2534 Used with file and pathnames to create a prefix for a recipe's 2535 version based on the recipe's :term:`PE` value. If :term:`PE` 2536 is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that 2537 value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1"). 2538 If a recipe's :term:`PE` is not set (the default) or is equal to zero, 2539 :term:`EXTENDPE` becomes "". 2540 2541 See the :term:`STAMP` variable for an example. 2542 2543 :term:`EXTENDPKGV` 2544 The full package version specification as it appears on the final 2545 packages produced by a recipe. The variable's value is normally used 2546 to fix a runtime dependency to the exact same version of another 2547 package in the same recipe:: 2548 2549 RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" 2550 2551 The dependency relationships are intended to force the package 2552 manager to upgrade these types of packages in lock-step. 2553 2554 :term:`EXTERNAL_KERNEL_TOOLS` 2555 When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these 2556 tools are not in the source tree. 2557 2558 When kernel tools are available in the tree, they are preferred over 2559 any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS` 2560 variable tells the OpenEmbedded build system to prefer the installed 2561 external tools. See the :ref:`ref-classes-kernel-yocto` class in 2562 ``meta/classes-recipe`` to see how the variable is used. 2563 2564 :term:`EXTERNAL_KERNEL_DEVICETREE` 2565 When inheriting :ref:`ref-classes-kernel-fitimage` and a 2566 :term:`PREFERRED_PROVIDER` for ``virtual/dtb`` set to ``devicetree``, the 2567 variable :term:`EXTERNAL_KERNEL_DEVICETREE` can be used to specify a 2568 directory containing one or more compiled device tree or device tree 2569 overlays to use. 2570 2571 :term:`KERNEL_LOCALVERSION` 2572 This variable allows to append a string to the version 2573 of the kernel image. This corresponds to the ``CONFIG_LOCALVERSION`` 2574 kernel configuration parameter. 2575 2576 Using this variable is only useful when you are using a kernel recipe 2577 inheriting the :ref:`ref-classes-kernel` class, and which doesn't 2578 already set a local version. Therefore, setting this variable has no 2579 impact on ``linux-yocto`` kernels. 2580 2581 :term:`EXTERNAL_TOOLCHAIN` 2582 When you intend to use an 2583 :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`, 2584 this variable allows to specify the directory where this toolchain was 2585 installed. 2586 2587 :term:`EXTERNALSRC` 2588 When inheriting the :ref:`ref-classes-externalsrc` 2589 class, this variable points to the source tree, which is outside of 2590 the OpenEmbedded build system. When set, this variable sets the 2591 :term:`S` variable, which is what the OpenEmbedded build 2592 system uses to locate unpacked recipe source code. 2593 2594 See the ":ref:`ref-classes-externalsrc`" section for details. You 2595 can also find information on how to use this variable in the 2596 ":ref:`dev-manual/building:building software from an external source`" 2597 section in the Yocto Project Development Tasks Manual. 2598 2599 :term:`EXTERNALSRC_BUILD` 2600 When inheriting the :ref:`ref-classes-externalsrc` 2601 class, this variable points to the directory in which the recipe's 2602 source code is built, which is outside of the OpenEmbedded build 2603 system. When set, this variable sets the :term:`B` variable, 2604 which is what the OpenEmbedded build system uses to locate the 2605 :term:`Build Directory`. 2606 2607 See the ":ref:`ref-classes-externalsrc`" section for details. You 2608 can also find information on how to use this variable in the 2609 ":ref:`dev-manual/building:building software from an external source`" 2610 section in the Yocto Project Development Tasks Manual. 2611 2612 :term:`EXTRA_AUTORECONF` 2613 For recipes inheriting the :ref:`ref-classes-autotools` 2614 class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to 2615 pass to the ``autoreconf`` command that is executed during the 2616 :ref:`ref-tasks-configure` task. 2617 2618 The default value is "--exclude=autopoint". 2619 2620 :term:`EXTRA_IMAGE_FEATURES` 2621 A list of additional features to include in an image. When listing 2622 more than one feature, separate them with a space. 2623 2624 Typically, you configure this variable in your ``local.conf`` file, 2625 which is found in the :term:`Build Directory`. Although you can use this 2626 variable from within a recipe, best practices dictate that you do not. 2627 2628 .. note:: 2629 2630 To enable primary features from within the image recipe, use the 2631 :term:`IMAGE_FEATURES` variable. 2632 2633 Here are some examples of features you can add: 2634 2635 - "dbg-pkgs" --- adds -dbg packages for all installed packages including 2636 symbol information for debugging and profiling. 2637 2638 - "empty-root-password" --- This feature can be used if you want to 2639 allow root login with an empty password. 2640 - "allow-empty-password" --- Allows Dropbear and OpenSSH to accept 2641 logins from accounts having an empty password string. 2642 - "allow-root-login" --- Allows Dropbear and OpenSSH to accept root logins. 2643 - "post-install-logging" --- Enables logging postinstall script runs to 2644 the ``/var/log/postinstall.log`` file on first boot of the image on 2645 the target system. 2646 - "dev-pkgs" --- adds -dev packages for all installed packages. This is 2647 useful if you want to develop against the libraries in the image. 2648 - "read-only-rootfs" --- creates an image whose root filesystem is 2649 read-only. See the 2650 ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`" 2651 section in the Yocto Project Development Tasks Manual for more 2652 information 2653 - "tools-debug" --- adds debugging tools such as gdb and strace. 2654 - "tools-sdk" --- adds development tools such as gcc, make, 2655 pkgconfig and so forth. 2656 - "tools-testapps" --- adds useful testing tools 2657 such as ts_print, aplay, arecord and so forth. 2658 2659 For a complete list of image features that ships with the Yocto 2660 Project, see the ":ref:`ref-features-image`" section. 2661 2662 For an example that shows how to customize your image by using this 2663 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 2664 section in the Yocto Project Development Tasks Manual. 2665 2666 :term:`EXTRA_IMAGECMD` 2667 Specifies additional options for the image creation command that has 2668 been specified in :term:`IMAGE_CMD`. When setting 2669 this variable, use an override for the associated image type. Here is 2670 an example:: 2671 2672 EXTRA_IMAGECMD:ext3 ?= "-i 4096" 2673 2674 :term:`EXTRA_IMAGEDEPENDS` 2675 A list of recipes to build that do not provide packages for 2676 installing into the root filesystem. 2677 2678 Sometimes a recipe is required to build the final image but is not 2679 needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS` 2680 variable to list these recipes and thus specify the dependencies. A 2681 typical example is a required bootloader in a machine configuration. 2682 2683 .. note:: 2684 2685 To add packages to the root filesystem, see the various 2686 :term:`RDEPENDS` and :term:`RRECOMMENDS` variables. 2687 2688 :term:`EXTRA_OECMAKE` 2689 Additional `CMake <https://cmake.org/overview/>`__ options. See the 2690 :ref:`ref-classes-cmake` class for additional information. 2691 2692 :term:`EXTRA_OECONF` 2693 Additional ``configure`` script options. See 2694 :term:`PACKAGECONFIG_CONFARGS` for 2695 additional information on passing configure script options. 2696 2697 :term:`EXTRA_OEMAKE` 2698 Additional GNU ``make`` options. 2699 2700 Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the 2701 variable to specify any required GNU options. 2702 2703 :term:`PARALLEL_MAKE` and 2704 :term:`PARALLEL_MAKEINST` also make use of 2705 :term:`EXTRA_OEMAKE` to pass the required flags. 2706 2707 :term:`EXTRA_OESCONS` 2708 When inheriting the :ref:`ref-classes-scons` class, this 2709 variable specifies additional configuration options you want to pass 2710 to the ``scons`` command line. 2711 2712 :term:`EXTRA_OEMESON` 2713 Additional `Meson <https://mesonbuild.com/>`__ options. See the 2714 :ref:`ref-classes-meson` class for additional information. 2715 2716 In addition to standard Meson options, such options correspond to 2717 `Meson build options <https://mesonbuild.com/Build-options.html>`__ 2718 defined in the ``meson_options.txt`` file in the sources to build. 2719 Here is an example:: 2720 2721 EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled" 2722 2723 Note that any custom value for the Meson ``--buildtype`` option 2724 should be set through the :term:`MESON_BUILDTYPE` variable. 2725 2726 :term:`EXTRA_USERS_PARAMS` 2727 When inheriting the :ref:`ref-classes-extrausers` 2728 class, this variable provides image level user and group operations. 2729 This is a more global method of providing user and group 2730 configuration as compared to using the 2731 :ref:`ref-classes-useradd` class, which ties user and 2732 group configurations to a specific recipe. 2733 2734 The set list of commands you can configure using the 2735 :term:`EXTRA_USERS_PARAMS` is shown in the 2736 :ref:`ref-classes-extrausers` class. These commands map to the normal 2737 Unix commands of the same names:: 2738 2739 # EXTRA_USERS_PARAMS = "\ 2740 # useradd -p '' tester; \ 2741 # groupadd developers; \ 2742 # userdel nobody; \ 2743 # groupdel -g video; \ 2744 # groupmod -g 1020 developers; \ 2745 # usermod -s /bin/sh tester; \ 2746 # " 2747 2748 Hardcoded passwords are supported via the ``-p`` parameters for 2749 ``useradd`` or ``usermod``, but only hashed. 2750 2751 Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns 2752 passwords. First on host, create the (escaped) password hash:: 2753 2754 printf "%q" $(mkpasswd -m sha256crypt tester01) 2755 2756 The resulting hash is set to a variable and used in ``useradd`` command parameters:: 2757 2758 inherit extrausers 2759 PASSWD = "\$X\$ABC123\$A-Long-Hash" 2760 EXTRA_USERS_PARAMS = "\ 2761 useradd -p '${PASSWD}' tester-jim; \ 2762 useradd -p '${PASSWD}' tester-sue; \ 2763 " 2764 2765 Finally, here is an example that sets the root password:: 2766 2767 inherit extrausers 2768 EXTRA_USERS_PARAMS = "\ 2769 usermod -p '${PASSWD}' root; \ 2770 " 2771 2772 .. note:: 2773 2774 From a security perspective, hardcoding a default password is not 2775 generally a good idea or even legal in some jurisdictions. It is 2776 recommended that you do not do this if you are building a production 2777 image. 2778 2779 Additionally there is a special ``passwd-expire`` command that will 2780 cause the password for a user to be expired and thus force changing it 2781 on first login, for example:: 2782 2783 EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;" 2784 2785 .. note:: 2786 2787 At present, ``passwd-expire`` may only work for remote logins when 2788 using OpenSSH and not dropbear as an SSH server. 2789 2790 :term:`EXTRANATIVEPATH` 2791 A list of subdirectories of 2792 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` 2793 added to the beginning of the environment variable ``PATH``. As an 2794 example, the following prepends 2795 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to 2796 ``PATH``:: 2797 2798 EXTRANATIVEPATH = "foo bar" 2799 2800 :term:`FAKEROOT` 2801 See :term:`bitbake:FAKEROOT` in the BitBake manual. 2802 2803 :term:`FAKEROOTBASEENV` 2804 See :term:`bitbake:FAKEROOTBASEENV` in the BitBake manual. 2805 2806 :term:`FAKEROOTCMD` 2807 See :term:`bitbake:FAKEROOTCMD` in the BitBake manual. 2808 2809 :term:`FAKEROOTDIRS` 2810 See :term:`bitbake:FAKEROOTDIRS` in the BitBake manual. 2811 2812 :term:`FAKEROOTENV` 2813 See :term:`bitbake:FAKEROOTENV` in the BitBake manual. 2814 2815 :term:`FAKEROOTNOENV` 2816 See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual. 2817 2818 :term:`FEATURE_PACKAGES` 2819 Defines one or more packages to include in an image when a specific 2820 item is included in :term:`IMAGE_FEATURES`. 2821 When setting the value, :term:`FEATURE_PACKAGES` should have the name of 2822 the feature item as an override. Here is an example:: 2823 2824 FEATURE_PACKAGES_widget = "package1 package2" 2825 2826 In this example, if "widget" were added to :term:`IMAGE_FEATURES`, 2827 package1 and package2 would be included in the image. 2828 2829 .. note:: 2830 2831 Packages installed by features defined through :term:`FEATURE_PACKAGES` 2832 are often package groups. While similarly named, you should not 2833 confuse the :term:`FEATURE_PACKAGES` variable with package groups, which 2834 are discussed elsewhere in the documentation. 2835 2836 :term:`FEED_DEPLOYDIR_BASE_URI` 2837 Points to the base URL of the server and location within the 2838 document-root that provides the metadata and packages required by 2839 OPKG to support runtime package management of IPK packages. You set 2840 this variable in your ``local.conf`` file. 2841 2842 Consider the following example:: 2843 2844 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" 2845 2846 This example assumes you are serving 2847 your packages over HTTP and your databases are located in a directory 2848 named ``BOARD-dir``, which is underneath your HTTP server's 2849 document-root. In this case, the OpenEmbedded build system generates 2850 a set of configuration files for you in your target that work with 2851 the feed. 2852 2853 :term:`FETCHCMD` 2854 See :term:`bitbake:FETCHCMD` in the BitBake manual. 2855 2856 :term:`FILE` 2857 See :term:`bitbake:FILE` in the BitBake manual. 2858 2859 :term:`FILES` 2860 The list of files and directories that are placed in a package. The 2861 :term:`PACKAGES` variable lists the packages 2862 generated by a recipe. 2863 2864 To use the :term:`FILES` variable, provide a package name override that 2865 identifies the resulting package. Then, provide a space-separated 2866 list of files or paths that identify the files you want included as 2867 part of the resulting package. Here is an example:: 2868 2869 FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" 2870 2871 .. note:: 2872 2873 - When specifying files or paths, you can pattern match using 2874 Python's 2875 `glob <https://docs.python.org/3/library/glob.html>`__ 2876 syntax. For details on the syntax, see the documentation by 2877 following the previous link. 2878 2879 - When specifying paths as part of the :term:`FILES` variable, it is 2880 good practice to use appropriate path variables. For example, 2881 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` 2882 rather than ``/usr/bin``. You can find a list of these 2883 variables at the top of the ``meta/conf/bitbake.conf`` file in 2884 the :term:`Source Directory`. You will also 2885 find the default values of the various ``FILES:*`` variables in 2886 this file. 2887 2888 If some of the files you provide with the :term:`FILES` variable are 2889 editable and you know they should not be overwritten during the 2890 package update process by the Package Management System (PMS), you 2891 can identify these files so that the PMS will not overwrite them. See 2892 the :term:`CONFFILES` variable for information on 2893 how to identify these files to the PMS. 2894 2895 :term:`FILES_SOLIBSDEV` 2896 Defines the file specification to match 2897 :term:`SOLIBSDEV`. In other words, 2898 :term:`FILES_SOLIBSDEV` defines the full path name of the development 2899 symbolic link (symlink) for shared libraries on the target platform. 2900 2901 The following statement from the ``bitbake.conf`` shows how it is 2902 set:: 2903 2904 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" 2905 2906 :term:`FILESEXTRAPATHS` 2907 A colon-separated list to extend the search path the OpenEmbedded build 2908 system uses when looking for files and patches as it processes recipes 2909 and append files. The default directories BitBake uses when it processes 2910 recipes are initially defined by the :term:`FILESPATH` variable. You can 2911 extend :term:`FILESPATH` variable by using :term:`FILESEXTRAPATHS`. 2912 2913 Best practices dictate that you accomplish this by using 2914 :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you 2915 prepend paths as follows:: 2916 2917 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 2918 2919 In the above example, the build system first 2920 looks for files in a directory that has the same name as the 2921 corresponding append file. 2922 2923 .. note:: 2924 2925 When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate 2926 expansion (``:=``) operator. Immediate expansion makes sure that 2927 BitBake evaluates :term:`THISDIR` at the time the 2928 directive is encountered rather than at some later time when 2929 expansion might result in a directory that does not contain the 2930 files you need. 2931 2932 Also, include the trailing separating colon character if you are 2933 prepending. The trailing colon character is necessary because you 2934 are directing BitBake to extend the path by prepending directories 2935 to the search path. 2936 2937 Here is another common use:: 2938 2939 FILESEXTRAPATHS:prepend := "${THISDIR}/files:" 2940 2941 In this example, the build system extends the 2942 :term:`FILESPATH` variable to include a directory named ``files`` that is 2943 in the same directory as the corresponding append file. 2944 2945 This next example specifically adds three paths:: 2946 2947 FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:" 2948 2949 A final example shows how you can extend the search path and include 2950 a :term:`MACHINE`-specific override, which is useful 2951 in a BSP layer:: 2952 2953 FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:" 2954 2955 The previous statement appears in the 2956 ``linux-yocto-dev.bbappend`` file, which is found in the 2957 :ref:`overview-manual/development-environment:yocto project source repositories` in 2958 ``meta-intel/common/recipes-kernel/linux``. Here, the machine 2959 override is a special :term:`PACKAGE_ARCH` 2960 definition for multiple ``meta-intel`` machines. 2961 2962 .. note:: 2963 2964 For a layer that supports a single BSP, the override could just be 2965 the value of :term:`MACHINE`. 2966 2967 By prepending paths in ``.bbappend`` files, you allow multiple append 2968 files that reside in different layers but are used for the same 2969 recipe to correctly extend the path. 2970 2971 :term:`FILESOVERRIDES` 2972 A colon-separated list to specify a subset of :term:`OVERRIDES` used by 2973 the OpenEmbedded build system for creating :term:`FILESPATH`. The 2974 :term:`FILESOVERRIDES` variable uses overrides to automatically extend 2975 the :term:`FILESPATH` variable. For an example of how that works, see the 2976 :term:`FILESPATH` variable description. Additionally, you find more 2977 information on how overrides are handled in the 2978 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 2979 section of the BitBake User Manual. 2980 2981 By default, the :term:`FILESOVERRIDES` variable is defined as:: 2982 2983 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" 2984 2985 .. note:: 2986 2987 Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up 2988 with expected overrides and are used in an expected manner by the 2989 build system. 2990 2991 :term:`FILESPATH` 2992 A colon-separated list specifying the default set of directories the 2993 OpenEmbedded build system uses when searching for patches and files. 2994 2995 During the build process, BitBake searches each directory in 2996 :term:`FILESPATH` in the specified order when looking for files and 2997 patches specified by each ``file://`` URI in a recipe's 2998 :term:`SRC_URI` statements. 2999 3000 The default value for the :term:`FILESPATH` variable is defined in the 3001 :ref:`ref-classes-base` class found in ``meta/classes-global`` in the 3002 :term:`Source Directory`:: 3003 3004 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ 3005 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" 3006 3007 The 3008 :term:`FILESPATH` variable is automatically extended using the overrides 3009 from the :term:`FILESOVERRIDES` variable. 3010 3011 .. note:: 3012 3013 - Do not hand-edit the :term:`FILESPATH` variable. If you want the 3014 build system to look in directories other than the defaults, 3015 extend the :term:`FILESPATH` variable by using the 3016 :term:`FILESEXTRAPATHS` variable. 3017 3018 - Be aware that the default :term:`FILESPATH` directories do not map 3019 to directories in custom layers where append files 3020 (``.bbappend``) are used. If you want the build system to find 3021 patches or files that reside with your append files, you need 3022 to extend the :term:`FILESPATH` variable by using the 3023 :term:`FILESEXTRAPATHS` variable. 3024 3025 You can take advantage of this searching behavior in useful ways. For 3026 example, consider a case where there is the following directory structure 3027 for general and machine-specific configurations:: 3028 3029 files/defconfig 3030 files/MACHINEA/defconfig 3031 files/MACHINEB/defconfig 3032 3033 Also in the example, the :term:`SRC_URI` statement contains 3034 "file://defconfig". Given this scenario, you can set 3035 :term:`MACHINE` to "MACHINEA" and cause the build 3036 system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to 3037 "MACHINEB" and the build system uses files from ``files/MACHINEB``. 3038 Finally, for any machine other than "MACHINEA" and "MACHINEB", the 3039 build system uses files from ``files/defconfig``. 3040 3041 You can find out more about the patching process in the 3042 ":ref:`overview-manual/concepts:patching`" section 3043 in the Yocto Project Overview and Concepts Manual and the 3044 ":ref:`dev-manual/new-recipe:patching code`" section in 3045 the Yocto Project Development Tasks Manual. See the 3046 :ref:`ref-tasks-patch` task as well. 3047 3048 :term:`FILESYSTEM_PERMS_TABLES` 3049 Allows you to define your own file permissions settings tables as part 3050 of your configuration for the packaging process. For example, suppose 3051 you need a consistent set of custom permissions for a set of groups 3052 and users across an entire work project. It is best to do this in the 3053 packages themselves but this is not always possible. 3054 3055 By default, the OpenEmbedded build system uses the ``fs-perms.txt``, 3056 ``fs-perms-volatile-log.txt`` and ``fs-perms-volatile-tmp.txt`` which are 3057 located in the ``meta/files`` folder in the :term:`Source Directory`. If 3058 you create your own permission setting table files, you should place 3059 those in your layer. 3060 3061 You can override the value of :term:`FILESYSTEM_PERMS_TABLES` variable 3062 in your distribution configuration file to point to your custom 3063 permission table files. You can specify one or more file permissions 3064 setting tables. The paths that you specify to these files must be defined 3065 within the :term:`BBPATH` variable. 3066 3067 In order to disable the volatile log, which is enabled by default, one 3068 can remove the ``files/fs-perms-volatile-log.txt`` value from 3069 ``FILESYSTEM_PERMS_TABLES``. Similarly, in order to disable the volatile 3070 tmp, one can remove the ``files/fs-perms-volatile-tmp.txt`` value. 3071 3072 For guidance on how to define your own file permissions settings 3073 tables, examine the existing ``fs-perms.txt``, 3074 ``fs-perms-volatile-log.txt`` and ``fs-perms-volatile-tmp.txt`` files. 3075 3076 :term:`FIRMWARE_COMPRESSION` 3077 The :term:`FIRMWARE_COMPRESSION` allows compressing the firmware provided 3078 by the ``linux-firmware`` recipe. The default value of this variable is an 3079 empty string (no compression), and the possible values it can take are 3080 ``xz`` and ``zst``. This can allow significant disk space savings. 3081 3082 For this to work, the Linux Kernel requires the 3083 ``CONFIG_FW_LOADER_COMPRESS_XZ`` or ``CONFIG_FW_LOADER_COMPRESS_ZSTD`` 3084 configuration options to be set. 3085 3086 :term:`FIT_ADDRESS_CELLS` 3087 Specifies the value of the ``#address-cells`` value for the 3088 description of the FIT image. 3089 3090 The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` 3091 class, which corresponds to 32 bit addresses. 3092 3093 For platforms that need to set 64 bit addresses, for example in 3094 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to 3095 set this value to "2", as two 32 bit values (cells) will be needed 3096 to represent such addresses. 3097 3098 Here is an example setting "0x400000000" as a load address:: 3099 3100 FIT_ADDRESS_CELLS = "2" 3101 UBOOT_LOADADDRESS= "0x04 0x00000000" 3102 3103 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. 3104 3105 :term:`FIT_CONF_DEFAULT_DTB` 3106 Specifies the default device tree binary (dtb) file for a FIT image 3107 when multiple ones are provided. 3108 3109 This variable is used in the :ref:`ref-classes-kernel-fitimage` class. 3110 3111 :term:`FIT_DESC` 3112 Specifies the description string encoded into a FIT image. The 3113 default value is set by the :ref:`ref-classes-kernel-fitimage` class as 3114 follows:: 3115 3116 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" 3117 3118 :term:`FIT_GENERATE_KEYS` 3119 Decides whether to generate the keys for signing the FIT image if 3120 they don't already exist. The keys are created in 3121 :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0" 3122 by the :ref:`ref-classes-kernel-fitimage` class. 3123 3124 :term:`FIT_HASH_ALG` 3125 Specifies the hash algorithm used in creating the FIT Image. 3126 This variable is set by default to "sha256" by the 3127 :ref:`ref-classes-kernel-fitimage` class. 3128 3129 :term:`FIT_KERNEL_COMP_ALG` 3130 The compression algorithm to use for the kernel image inside the FIT Image. 3131 At present, the only supported values are "gzip" (default), "lzo" or "none". 3132 If you set this variable to anything other than "none" you may also need 3133 to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`. 3134 3135 This variable is used in the :ref:`ref-classes-kernel-uboot` class. 3136 3137 :term:`FIT_KERNEL_COMP_ALG_EXTENSION` 3138 File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default 3139 value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you 3140 set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this 3141 variable to ".lzo". 3142 3143 :term:`FIT_KEY_GENRSA_ARGS` 3144 Arguments to ``openssl genrsa`` for generating a RSA private key for 3145 signing the FIT image. The default value is set to "-F4" by the 3146 :ref:`ref-classes-kernel-fitimage` class. 3147 3148 :term:`FIT_KEY_REQ_ARGS` 3149 Arguments to ``openssl req`` for generating a certificate for signing 3150 the FIT image. The default value is "-batch -new" by the 3151 :ref:`ref-classes-kernel-fitimage` class, "batch" for 3152 non interactive mode and "new" for generating new keys. 3153 3154 :term:`FIT_KEY_SIGN_PKCS` 3155 Format for the public key certificate used for signing the FIT image. 3156 The default value is set to "x509" by the 3157 :ref:`ref-classes-kernel-fitimage` class. 3158 3159 :term:`FIT_SIGN_ALG` 3160 Specifies the signature algorithm used in creating the FIT Image. 3161 This variable is set by default to "rsa2048" by the 3162 :ref:`ref-classes-kernel-fitimage` class. 3163 3164 :term:`FIT_PAD_ALG` 3165 Specifies the padding algorithm used in creating the FIT Image. 3166 The default value is set to "pkcs-1.5" by the 3167 :ref:`ref-classes-kernel-fitimage` class. 3168 3169 :term:`FIT_SIGN_INDIVIDUAL` 3170 If set to "1", then the :ref:`ref-classes-kernel-fitimage` 3171 class will sign the kernel, dtb and ramdisk images individually in addition 3172 to signing the FIT image itself. This could be useful if you are 3173 intending to verify signatures in another context than booting via 3174 U-Boot. 3175 3176 This variable is set to "0" by default. 3177 3178 :term:`FIT_SIGN_NUMBITS` 3179 Size of the private key used in the FIT image, in number of bits. 3180 The default value for this variable is set to "2048" 3181 by the :ref:`ref-classes-kernel-fitimage` class. 3182 3183 :term:`FONT_EXTRA_RDEPENDS` 3184 When inheriting the :ref:`ref-classes-fontcache` class, 3185 this variable specifies the runtime dependencies for font packages. 3186 By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils". 3187 3188 :term:`FONT_PACKAGES` 3189 When inheriting the :ref:`ref-classes-fontcache` class, this variable 3190 identifies packages containing font files that need to be cached by 3191 Fontconfig. By default, the :ref:`ref-classes-fontcache` class assumes 3192 that fonts are in the recipe's main package (i.e. 3193 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you 3194 need are in a package other than that main package. 3195 3196 :term:`FORCE_RO_REMOVE` 3197 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED`` 3198 during the generation of the root filesystem. 3199 3200 Set the variable to "1" to force the removal of these packages. 3201 3202 :term:`FULL_OPTIMIZATION` 3203 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when 3204 compiling an optimized system. This variable defaults to "-O2 -pipe 3205 ${DEBUG_FLAGS}". 3206 3207 :term:`GCCPIE` 3208 Enables Position Independent Executables (PIE) within the GNU C 3209 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented 3210 Programming (ROP) attacks much more difficult to execute. 3211 3212 By default the ``security_flags.inc`` file enables PIE by setting the 3213 variable as follows:: 3214 3215 GCCPIE ?= "--enable-default-pie" 3216 3217 :term:`GCCVERSION` 3218 Specifies the default version of the GNU C Compiler (GCC) used for 3219 compilation. By default, :term:`GCCVERSION` is set to "8.x" in the 3220 ``meta/conf/distro/include/tcmode-default.inc`` include file:: 3221 3222 GCCVERSION ?= "8.%" 3223 3224 You can override this value by setting it in a 3225 configuration file such as the ``local.conf``. 3226 3227 :term:`GDB` 3228 The minimal command and arguments to run the GNU Debugger. 3229 3230 :term:`GIR_EXTRA_LIBS_PATH` 3231 Allows to specify an extra search path for ``.so`` files 3232 in GLib related recipes using GObject introspection, 3233 and which do not compile without this setting. 3234 See the ":ref:`dev-manual/gobject-introspection:enabling gobject introspection support`" 3235 section for details. 3236 3237 :term:`GITDIR` 3238 The directory in which a local copy of a Git repository is stored 3239 when it is cloned. 3240 3241 :term:`GITHUB_BASE_URI` 3242 When inheriting the :ref:`ref-classes-github-releases` 3243 class, specifies the base URL for fetching releases for the github 3244 project you wish to fetch sources from. The default value is as follows:: 3245 3246 GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/" 3247 3248 :term:`GLIBC_GENERATE_LOCALES` 3249 Specifies the list of GLIBC locales to generate should you not wish 3250 to generate all LIBC locals, which can be time consuming. 3251 3252 .. note:: 3253 3254 If you specifically remove the locale ``en_US.UTF-8``, you must set 3255 :term:`IMAGE_LINGUAS` appropriately. 3256 3257 You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file. 3258 By default, all locales are generated:: 3259 3260 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" 3261 3262 :term:`GO_IMPORT` 3263 When inheriting the :ref:`ref-classes-go` class, this mandatory variable 3264 sets the import path for the Go package that will be created for the code 3265 to build. If you have a ``go.mod`` file in the source directory, this 3266 typically matches the path in the ``module`` line in this file. 3267 3268 Other Go programs importing this package will use this path. 3269 3270 Here is an example setting from the 3271 :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>` 3272 recipe:: 3273 3274 GO_IMPORT = "golang.org/x/example" 3275 3276 :term:`GO_INSTALL` 3277 When inheriting the :ref:`ref-classes-go` class, this optional variable 3278 specifies which packages in the sources should be compiled and 3279 installed in the Go build space by the 3280 `go install <https://go.dev/ref/mod#go-install>`__ command. 3281 3282 Here is an example setting from the 3283 :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>` 3284 recipe:: 3285 3286 GO_INSTALL = "\ 3287 ${GO_IMPORT}/cmd/crucible \ 3288 ${GO_IMPORT}/cmd/habtool \ 3289 " 3290 3291 By default, :term:`GO_INSTALL` is defined as:: 3292 3293 GO_INSTALL ?= "${GO_IMPORT}/..." 3294 3295 The ``...`` wildcard means that it will catch all 3296 packages found in the sources. 3297 3298 See the :term:`GO_INSTALL_FILTEROUT` variable for 3299 filtering out unwanted packages from the ones 3300 found from the :term:`GO_INSTALL` value. 3301 3302 :term:`GO_INSTALL_FILTEROUT` 3303 When using the Go "vendor" mechanism to bring in dependencies for a Go 3304 package, the default :term:`GO_INSTALL` setting, which uses the ``...`` 3305 wildcard, will include the vendored packages in the build, which produces 3306 incorrect results. 3307 3308 There are also some Go packages that are structured poorly, so that the 3309 ``...`` wildcard results in building example or test code that should not 3310 be included in the build, or could fail to build. 3311 3312 This optional variable allows for filtering out a subset of the sources. 3313 It defaults to excluding everything under the ``vendor`` subdirectory 3314 under package's main directory. This is the normal location for vendored 3315 packages, but it can be overridden by a recipe to filter out other 3316 subdirectories if needed. 3317 3318 :term:`GO_WORKDIR` 3319 When using Go Modules, the current working directory must be the directory 3320 containing the ``go.mod`` file, or one of its subdirectories. When the 3321 ``go`` tool is used, it will automatically look for the ``go.mod`` file 3322 in the Go working directory or in any parent directory, but not in 3323 subdirectories. 3324 3325 When using the :ref:`ref-classes-go-mod` class to use Go modules, 3326 the optional :term:`GO_WORKDIR` variable, defaulting to the value 3327 of :term:`GO_IMPORT`, allows to specify a different Go working directory. 3328 3329 :term:`GROUPADD_PARAM` 3330 When inheriting the :ref:`ref-classes-useradd` class, 3331 this variable specifies for a package what parameters should be 3332 passed to the ``groupadd`` command if you wish to add a group to the 3333 system when the package is installed. 3334 3335 Here is an example from the ``dbus`` recipe:: 3336 3337 GROUPADD_PARAM:${PN} = "-r netdev" 3338 3339 More than one group can be added by separating each set of different 3340 groups' parameters with a semicolon. 3341 3342 Here is an example adding multiple groups from the ``useradd-example.bb`` 3343 file in the ``meta-skeleton`` layer:: 3344 3345 GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2" 3346 3347 For information on the standard Linux shell command 3348 ``groupadd``, see https://linux.die.net/man/8/groupadd. 3349 3350 :term:`GROUPMEMS_PARAM` 3351 When inheriting the :ref:`ref-classes-useradd` class, 3352 this variable specifies for a package what parameters should be 3353 passed to the ``groupmems`` command if you wish to modify the members 3354 of a group when the package is installed. 3355 3356 For information on the standard Linux shell command ``groupmems``, 3357 see https://linux.die.net/man/8/groupmems. 3358 3359 :term:`GRUB_GFXSERIAL` 3360 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics 3361 and serial in the boot menu. Set this variable to "1" in your 3362 ``local.conf`` or distribution configuration file to enable graphics 3363 and serial in the menu. 3364 3365 See the :ref:`ref-classes-grub-efi` class for more 3366 information on how this variable is used. 3367 3368 :term:`GRUB_OPTS` 3369 Additional options to add to the GNU GRand Unified Bootloader (GRUB) 3370 configuration. Use a semi-colon character (``;``) to separate 3371 multiple options. 3372 3373 The :term:`GRUB_OPTS` variable is optional. See the 3374 :ref:`ref-classes-grub-efi` class for more information 3375 on how this variable is used. 3376 3377 :term:`GRUB_TIMEOUT` 3378 Specifies the timeout before executing the default ``LABEL`` in the 3379 GNU GRand Unified Bootloader (GRUB). 3380 3381 The :term:`GRUB_TIMEOUT` variable is optional. See the 3382 :ref:`ref-classes-grub-efi` class for more information 3383 on how this variable is used. 3384 3385 :term:`GRUB_TITLE` 3386 Specifies custom titles for GRUB labels defined in :term:`LABELS`. See 3387 the :ref:`ref-classes-grub-efi` class for more information on how this 3388 variable is used. 3389 3390 :term:`GTKIMMODULES_PACKAGES` 3391 When inheriting the :ref:`ref-classes-gtk-immodules-cache` class, 3392 this variable specifies the packages that contain the GTK+ input 3393 method modules being installed when the modules are in packages other 3394 than the main package. 3395 3396 :term:`HGDIR` 3397 See :term:`bitbake:HGDIR` in the BitBake manual. 3398 3399 :term:`HOMEPAGE` 3400 Website where more information about the software the recipe is 3401 building can be found. 3402 3403 :term:`HOST_ARCH` 3404 The name of the target architecture, which is normally the same as 3405 :term:`TARGET_ARCH`. The OpenEmbedded build system 3406 supports many architectures. Here is an example list of architectures 3407 supported. This list is by no means complete as the architecture is 3408 configurable: 3409 3410 - arm 3411 - i586 3412 - x86_64 3413 - powerpc 3414 - powerpc64 3415 - mips 3416 - mipsel 3417 3418 :term:`HOST_CC_ARCH` 3419 Specifies architecture-specific compiler flags that are passed to the 3420 C compiler. 3421 3422 Default initialization for :term:`HOST_CC_ARCH` varies depending on what 3423 is being built: 3424 3425 - :term:`TARGET_CC_ARCH` when building for the 3426 target 3427 3428 - :term:`BUILD_CC_ARCH` when building for the build host (i.e. 3429 ``-native``) 3430 3431 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e. 3432 ``nativesdk-``) 3433 3434 :term:`HOST_OS` 3435 Specifies the name of the target operating system, which is normally 3436 the same as the :term:`TARGET_OS`. The variable can 3437 be set to "linux" for ``glibc``-based systems and to "linux-musl" for 3438 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and 3439 "linux-musleabi" values possible. 3440 3441 :term:`HOST_PREFIX` 3442 Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX` 3443 is normally the same as :term:`TARGET_PREFIX`. 3444 3445 :term:`HOST_SYS` 3446 Specifies the system, including the architecture and the operating 3447 system, for which the build is occurring in the context of the 3448 current recipe. 3449 3450 The OpenEmbedded build system automatically sets this variable based 3451 on :term:`HOST_ARCH`, 3452 :term:`HOST_VENDOR`, and 3453 :term:`HOST_OS` variables. 3454 3455 .. note:: 3456 3457 You do not need to set the variable yourself. 3458 3459 Consider these two examples: 3460 3461 - Given a native recipe on a 32-bit x86 machine running Linux, the 3462 value is "i686-linux". 3463 3464 - Given a recipe being built for a little-endian MIPS target running 3465 Linux, the value might be "mipsel-linux". 3466 3467 :term:`HOST_VENDOR` 3468 Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the 3469 same as :term:`TARGET_VENDOR`. 3470 3471 :term:`HOSTTOOLS` 3472 A space-separated list (filter) of tools on the build host that 3473 should be allowed to be called from within build tasks. Using this 3474 filter helps reduce the possibility of host contamination. If a tool 3475 specified in the value of :term:`HOSTTOOLS` is not found on the build 3476 host, the OpenEmbedded build system produces an error and the build 3477 is not started. 3478 3479 For additional information, see 3480 :term:`HOSTTOOLS_NONFATAL`. 3481 3482 :term:`HOSTTOOLS_NONFATAL` 3483 A space-separated list (filter) of tools on the build host that 3484 should be allowed to be called from within build tasks. Using this 3485 filter helps reduce the possibility of host contamination. Unlike 3486 :term:`HOSTTOOLS`, the OpenEmbedded build system 3487 does not produce an error if a tool specified in the value of 3488 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can 3489 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools. 3490 3491 :term:`ICECC_CLASS_DISABLE` 3492 Identifies user classes that you do not want the Icecream distributed 3493 compile support to consider. This variable is used by the 3494 :ref:`ref-classes-icecc` class. You set this variable in 3495 your ``local.conf`` file. 3496 3497 When you list classes using this variable, the recipes inheriting 3498 those classes will not benefit from distributed compilation across 3499 remote hosts. Instead they will be built locally. 3500 3501 :term:`ICECC_DISABLED` 3502 Disables or enables the ``icecc`` (Icecream) function. For more 3503 information on this function and best practices for using this 3504 variable, see the ":ref:`ref-classes-icecc`" 3505 section. 3506 3507 Setting this variable to "1" in your ``local.conf`` disables the 3508 function:: 3509 3510 ICECC_DISABLED ??= "1" 3511 3512 To enable the function, set the variable as follows:: 3513 3514 ICECC_DISABLED = "" 3515 3516 :term:`ICECC_ENV_EXEC` 3517 Points to the ``icecc-create-env`` script that you provide. This 3518 variable is used by the :ref:`ref-classes-icecc` class. You 3519 set this variable in your ``local.conf`` file. 3520 3521 If you do not point to a script that you provide, the OpenEmbedded 3522 build system uses the default script provided by the 3523 :oe_git:`icecc-create-env_0.1.bb 3524 </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>` 3525 recipe, which is a modified version and not the one that comes with 3526 ``icecream``. 3527 3528 :term:`ICECC_PARALLEL_MAKE` 3529 Extra options passed to the ``make`` command during the 3530 :ref:`ref-tasks-compile` task that specify parallel 3531 compilation. This variable usually takes the form of "-j x", where x 3532 represents the maximum number of parallel threads ``make`` can run. 3533 3534 .. note:: 3535 3536 The options passed affect builds on all enabled machines on the 3537 network, which are machines running the ``iceccd`` daemon. 3538 3539 If your enabled machines support multiple cores, coming up with the 3540 maximum number of parallel threads that gives you the best 3541 performance could take some experimentation since machine speed, 3542 network lag, available memory, and existing machine loads can all 3543 affect build time. Consequently, unlike the 3544 :term:`PARALLEL_MAKE` variable, there is no 3545 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal 3546 performance. 3547 3548 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not 3549 use it (i.e. the system does not detect and assign the number of 3550 cores as is done with :term:`PARALLEL_MAKE`). 3551 3552 :term:`ICECC_PATH` 3553 The location of the ``icecc`` binary. You can set this variable in 3554 your ``local.conf`` file. If your ``local.conf`` file does not define 3555 this variable, the :ref:`ref-classes-icecc` class attempts 3556 to define it by locating ``icecc`` using ``which``. 3557 3558 :term:`ICECC_RECIPE_DISABLE` 3559 Identifies user recipes that you do not want the Icecream distributed 3560 compile support to consider. This variable is used by the 3561 :ref:`ref-classes-icecc` class. You set this variable in 3562 your ``local.conf`` file. 3563 3564 When you list recipes using this variable, you are excluding them 3565 from distributed compilation across remote hosts. Instead they will 3566 be built locally. 3567 3568 :term:`ICECC_RECIPE_ENABLE` 3569 Identifies user recipes that use an empty 3570 :term:`PARALLEL_MAKE` variable that you want to 3571 force remote distributed compilation on using the Icecream 3572 distributed compile support. This variable is used by the 3573 :ref:`ref-classes-icecc` class. You set this variable in 3574 your ``local.conf`` file. 3575 3576 :term:`IMAGE_BASENAME` 3577 The base name of image output files. This variable defaults to the 3578 recipe name (``${``\ :term:`PN`\ ``}``). 3579 3580 :term:`IMAGE_BOOT_FILES` 3581 A space-separated list of files installed into the boot partition 3582 when preparing an image using the Wic tool with the 3583 ``bootimg-partition`` source plugin. By default, 3584 the files are 3585 installed under the same name as the source files. To change the 3586 installed name, separate it from the original name with a semi-colon 3587 (;). Source files need to be located in 3588 :term:`DEPLOY_DIR_IMAGE`. Here are two 3589 examples:: 3590 3591 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" 3592 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" 3593 3594 Alternatively, source files can be picked up using a glob pattern. In 3595 this case, the destination file must have the same name as the base 3596 name of the source file path. To install files into a directory 3597 within the target location, pass its name after a semi-colon (;). 3598 Here are two examples:: 3599 3600 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" 3601 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" 3602 3603 The first example 3604 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles`` 3605 into the root of the target partition. The second example installs 3606 the same files into a ``boot`` directory within the target partition. 3607 3608 You can find information on how to use the Wic tool in the 3609 ":ref:`dev-manual/wic:creating partitioned images using wic`" 3610 section of the Yocto Project Development Tasks Manual. Reference 3611 material for Wic is located in the 3612 ":doc:`/ref-manual/kickstart`" chapter. 3613 3614 :term:`IMAGE_BUILDINFO_FILE` 3615 When using the :ref:`ref-classes-image-buildinfo` class, 3616 specifies the file in the image to write the build information into. The 3617 default value is "``${sysconfdir}/buildinfo``". 3618 3619 :term:`IMAGE_BUILDINFO_VARS` 3620 When using the :ref:`ref-classes-image-buildinfo` class, 3621 specifies the list of variables to include in the `Build Configuration` 3622 section of the output file (as a space-separated list). Defaults to 3623 ":term:`DISTRO` :term:`DISTRO_VERSION`". 3624 3625 :term:`IMAGE_CLASSES` 3626 A list of classes that all images should inherit. This is typically used 3627 to enable functionality across all image recipes. 3628 3629 Classes specified in :term:`IMAGE_CLASSES` must be located in the 3630 ``classes-recipe/`` or ``classes/`` subdirectories. 3631 3632 :term:`IMAGE_CMD` 3633 Specifies the command to create the image file for a specific image 3634 type, which corresponds to the value set in 3635 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, 3636 ``btrfs``, and so forth). When setting this variable, you should use 3637 an override for the associated type. Here is an example:: 3638 3639 IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \ 3640 --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \ 3641 ${EXTRA_IMAGECMD}" 3642 3643 You typically do not need to set this variable unless you are adding 3644 support for a new image type. For more examples on how to set this 3645 variable, see the :ref:`ref-classes-image_types` 3646 class file, which is ``meta/classes-recipe/image_types.bbclass``. 3647 3648 :term:`IMAGE_DEVICE_TABLES` 3649 Specifies one or more files that contain custom device tables that 3650 are passed to the ``makedevs`` command as part of creating an image. 3651 These files list basic device nodes that should be created under 3652 ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set, 3653 ``files/device_table-minimal.txt`` is used, which is located by 3654 :term:`BBPATH`. For details on how you should write 3655 device table files, see ``meta/files/device_table-minimal.txt`` as an 3656 example. 3657 3658 :term:`IMAGE_EFI_BOOT_FILES` 3659 A space-separated list of files installed into the boot partition 3660 when preparing an image using the Wic tool with the 3661 ``bootimg-efi`` source plugin. By default, 3662 the files are 3663 installed under the same name as the source files. To change the 3664 installed name, separate it from the original name with a semi-colon 3665 (;). Source files need to be located in 3666 :term:`DEPLOY_DIR_IMAGE`. Here are two 3667 examples:: 3668 3669 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" 3670 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" 3671 3672 Alternatively, source files can be picked up using a glob pattern. In 3673 this case, the destination file must have the same name as the base 3674 name of the source file path. To install files into a directory 3675 within the target location, pass its name after a semi-colon (;). 3676 Here are two examples:: 3677 3678 IMAGE_EFI_BOOT_FILES = "boot/loader/*" 3679 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" 3680 3681 The first example 3682 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/`` 3683 into the root of the target partition. The second example installs 3684 the same files into a ``boot`` directory within the target partition. 3685 3686 You can find information on how to use the Wic tool in the 3687 ":ref:`dev-manual/wic:creating partitioned images using wic`" 3688 section of the Yocto Project Development Tasks Manual. Reference 3689 material for Wic is located in the 3690 ":doc:`/ref-manual/kickstart`" chapter. 3691 3692 :term:`IMAGE_FEATURES` 3693 The primary list of features to include in an image. Typically, you 3694 configure this variable in an image recipe. Although you can use this 3695 variable from your ``local.conf`` file, which is found in the 3696 :term:`Build Directory`, best practices dictate that you do 3697 not. 3698 3699 .. note:: 3700 3701 To enable extra features from outside the image recipe, use the 3702 :term:`EXTRA_IMAGE_FEATURES` variable. 3703 3704 For a list of image features that ships with the Yocto Project, see 3705 the ":ref:`ref-features-image`" section. 3706 3707 For an example that shows how to customize your image by using this 3708 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 3709 section in the Yocto Project Development Tasks Manual. 3710 3711 :term:`IMAGE_FSTYPES` 3712 Specifies the formats the OpenEmbedded build system uses during the 3713 build when creating the root filesystem. For example, setting 3714 :term:`IMAGE_FSTYPES` as follows causes the build system to create root 3715 filesystems using two formats: ``.ext3`` and ``.tar.bz2``:: 3716 3717 IMAGE_FSTYPES = "ext3 tar.bz2" 3718 3719 For the complete list of supported image formats from which you can 3720 choose, see :term:`IMAGE_TYPES`. 3721 3722 .. note:: 3723 3724 - If an image recipe uses the "inherit image" line and you are 3725 setting :term:`IMAGE_FSTYPES` inside the recipe, you must set 3726 :term:`IMAGE_FSTYPES` prior to using the "inherit image" line. 3727 3728 - Due to the way the OpenEmbedded build system processes this 3729 variable, you cannot update its contents by using ``:append`` 3730 or ``:prepend``. You must use the ``+=`` operator to add one or 3731 more options to the :term:`IMAGE_FSTYPES` variable. 3732 3733 :term:`IMAGE_INSTALL` 3734 Used by recipes to specify the packages to install into an image 3735 through the :ref:`ref-classes-image` class. Use the 3736 :term:`IMAGE_INSTALL` variable with care to avoid ordering issues. 3737 3738 Image recipes set :term:`IMAGE_INSTALL` to specify the packages to 3739 install into an image through :ref:`ref-classes-image`. Additionally, 3740 there are "helper" classes such as the :ref:`ref-classes-core-image` 3741 class which can take lists used with :term:`IMAGE_FEATURES` and turn 3742 them into auto-generated entries in :term:`IMAGE_INSTALL` in addition 3743 to its default contents. 3744 3745 When you use this variable, it is best to use it as follows:: 3746 3747 IMAGE_INSTALL:append = " package-name" 3748 3749 Be sure to include the space 3750 between the quotation character and the start of the package name or 3751 names. 3752 3753 .. note:: 3754 3755 - When working with a 3756 :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 3757 image, do not use the :term:`IMAGE_INSTALL` variable to specify 3758 packages for installation. Instead, use the 3759 :term:`PACKAGE_INSTALL` variable, which 3760 allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a 3761 fixed set of packages and not be affected by :term:`IMAGE_INSTALL`. 3762 For information on creating an :term:`Initramfs`, see the 3763 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" 3764 section in the Yocto Project Development Tasks Manual. 3765 3766 - Using :term:`IMAGE_INSTALL` with the 3767 :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` 3768 BitBake operator within the ``/conf/local.conf`` file or from 3769 within an image recipe is not recommended. Use of this operator in 3770 these ways can cause ordering issues. Since 3771 :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a 3772 default value using the 3773 :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` 3774 operator, using a ``+=`` operation against :term:`IMAGE_INSTALL` 3775 results in unexpected behavior when used within 3776 ``conf/local.conf``. Furthermore, the same operation from within an 3777 image recipe may or may not succeed depending on the specific 3778 situation. In both these cases, the behavior is contrary to how 3779 most users expect the ``+=`` operator to work. 3780 3781 :term:`IMAGE_LINGUAS` 3782 Specifies the list of locales to install into the image during the 3783 root filesystem construction process. The OpenEmbedded build system 3784 automatically splits locale files, which are used for localization, 3785 into separate packages. Setting the :term:`IMAGE_LINGUAS` variable 3786 ensures that any locale packages that correspond to packages already 3787 selected for installation into the image are also installed. Here is 3788 an example:: 3789 3790 IMAGE_LINGUAS = "pt-br de-de" 3791 3792 In this example, the build system ensures any Brazilian Portuguese 3793 and German locale files that correspond to packages in the image are 3794 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as 3795 ``*-locale-pt`` and ``*-locale-de``, since some software packages 3796 only provide locale files by language and not by country-specific 3797 language). 3798 3799 See the :term:`GLIBC_GENERATE_LOCALES` 3800 variable for information on generating GLIBC locales. 3801 3802 3803 :term:`IMAGE_LINK_NAME` 3804 The name of the output image symlink (which does not include 3805 the version part as :term:`IMAGE_NAME` does). The default value 3806 is derived using the :term:`IMAGE_BASENAME` and 3807 :term:`IMAGE_MACHINE_SUFFIX` variables:: 3808 3809 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}" 3810 3811 .. note:: 3812 3813 It is possible to set this to "" to disable symlink creation, 3814 however, you also need to set :term:`IMAGE_NAME` to still have 3815 a reasonable value e.g.:: 3816 3817 IMAGE_LINK_NAME = "" 3818 IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" 3819 3820 :term:`IMAGE_MACHINE_SUFFIX` 3821 Specifies the by default machine-specific suffix for image file names 3822 (before the extension). The default value is set as follows:: 3823 3824 IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}" 3825 3826 The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE` 3827 subdirectory, so you may find it unnecessary to also include this suffix 3828 in the name of every image file. If you prefer to remove the suffix you 3829 can set this variable to an empty string:: 3830 3831 IMAGE_MACHINE_SUFFIX = "" 3832 3833 (Not to be confused with :term:`IMAGE_NAME_SUFFIX`.) 3834 3835 :term:`IMAGE_MANIFEST` 3836 The manifest file for the image. This file lists all the installed 3837 packages that make up the image. The file contains package 3838 information on a line-per-package basis as follows:: 3839 3840 packagename packagearch version 3841 3842 The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest 3843 file as follows:: 3844 3845 IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest" 3846 3847 The location is 3848 derived using the :term:`IMGDEPLOYDIR` 3849 and :term:`IMAGE_NAME` variables. You can find 3850 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" 3851 section in the Yocto Project Overview and Concepts Manual. 3852 3853 :term:`IMAGE_NAME` 3854 The name of the output image files minus the extension. By default 3855 this variable is set using the :term:`IMAGE_LINK_NAME`, and 3856 :term:`IMAGE_VERSION_SUFFIX` variables:: 3857 3858 IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}" 3859 3860 :term:`IMAGE_NAME_SUFFIX` 3861 Suffix used for the image output filename --- defaults to ``".rootfs"`` 3862 to distinguish the image file from other files created during image 3863 building; however if this suffix is redundant or not desired you can 3864 clear the value of this variable (set the value to ""). For example, 3865 this is typically cleared in :term:`Initramfs` image recipes. 3866 3867 :term:`IMAGE_OUTPUT_MANIFEST` 3868 When inheriting the :ref:`ref-classes-image` class directly or through the 3869 :ref:`ref-classes-core-image` class, the :term:`IMAGE_OUTPUT_MANIFEST` 3870 points to a manifest ``json`` file that lists what images were created by 3871 various image creation tasks (as defined by the :term:`IMAGE_FSTYPES` 3872 variable). It is set in the :ref:`ref-classes-image` class as follows:: 3873 3874 IMAGE_OUTPUT_MANIFEST = "${IMAGE_OUTPUT_MANIFEST_DIR}/manifest.json" 3875 3876 :term:`IMAGE_OUTPUT_MANIFEST_DIR` 3877 When inheriting the :ref:`ref-classes-image` class directly or through the 3878 :ref:`ref-classes-core-image` class, the :term:`IMAGE_OUTPUT_MANIFEST_DIR` points to 3879 a directory that stores a manifest ``json`` file that lists what 3880 images were created by various image creation tasks (as defined by the 3881 :term:`IMAGE_FSTYPES` variable). It is set in the :ref:`ref-classes-image` 3882 class as follows:: 3883 3884 IMAGE_OUTPUT_MANIFEST_DIR = "${WORKDIR}/deploy-image-output-manifest" 3885 3886 :term:`IMAGE_OVERHEAD_FACTOR` 3887 Defines a multiplier that the build system applies to the initial 3888 image size for cases when the multiplier times the returned disk 3889 usage value for the image is greater than the sum of 3890 :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of 3891 the multiplier applied to the initial image size creates free disk 3892 space in the image as overhead. By default, the build process uses a 3893 multiplier of 1.3 for this variable. This default value results in 3894 30% free disk space added to the image when this method is used to 3895 determine the final generated image size. You should be aware that 3896 post install scripts and the package management system uses disk 3897 space inside this overhead area. Consequently, the multiplier does 3898 not produce an image with all the theoretical free disk space. See 3899 :term:`IMAGE_ROOTFS_SIZE` for information on how the build system 3900 determines the overall image size. 3901 3902 The default 30% free disk space typically gives the image enough room 3903 to boot and allows for basic post installs while still leaving a 3904 small amount of free disk space. If 30% free space is inadequate, you 3905 can increase the default value. For example, the following setting 3906 gives you 50% free space added to the image:: 3907 3908 IMAGE_OVERHEAD_FACTOR = "1.5" 3909 3910 Alternatively, you can ensure a specific amount of free disk space is 3911 added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3912 variable. 3913 3914 :term:`IMAGE_PKGTYPE` 3915 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the 3916 OpenEmbedded build system. The variable is defined appropriately by 3917 the :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`, 3918 or :ref:`ref-classes-package_ipk` class. 3919 3920 The :ref:`ref-classes-populate-sdk-*` and :ref:`ref-classes-image` 3921 classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs. 3922 3923 You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the 3924 variable is set indirectly through the appropriate 3925 :ref:`package_* <ref-classes-package>` class using the 3926 :term:`PACKAGE_CLASSES` variable. The 3927 OpenEmbedded build system uses the first package type (e.g. DEB, RPM, 3928 or IPK) that appears with the variable 3929 3930 .. note:: 3931 3932 Files using the ``.tar`` format are never used as a substitute 3933 packaging format for DEB, RPM, and IPK formatted files for your image 3934 or SDK. 3935 3936 :term:`IMAGE_POSTPROCESS_COMMAND` 3937 Specifies a list of functions to call once the OpenEmbedded build 3938 system creates the final image output files. You can specify 3939 functions separated by spaces:: 3940 3941 IMAGE_POSTPROCESS_COMMAND += "function" 3942 3943 If you need to pass the root filesystem path to a command within the 3944 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3945 directory that becomes the root filesystem image. See the 3946 :term:`IMAGE_ROOTFS` variable for more 3947 information. 3948 3949 :term:`IMAGE_PREPROCESS_COMMAND` 3950 Specifies a list of functions to call before the OpenEmbedded build 3951 system creates the final image output files. You can specify 3952 functions separated by spaces:: 3953 3954 IMAGE_PREPROCESS_COMMAND += "function" 3955 3956 If you need to pass the root filesystem path to a command within the 3957 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3958 directory that becomes the root filesystem image. See the 3959 :term:`IMAGE_ROOTFS` variable for more 3960 information. 3961 3962 :term:`IMAGE_ROOTFS` 3963 The location of the root filesystem while it is under construction 3964 (i.e. during the :ref:`ref-tasks-rootfs` task). This 3965 variable is not configurable. Do not change it. 3966 3967 :term:`IMAGE_ROOTFS_ALIGNMENT` 3968 Specifies the alignment for the output image file in Kbytes. If the 3969 size of the image is not a multiple of this value, then the size is 3970 rounded up to the nearest multiple of the value. The default value is 3971 "1". See :term:`IMAGE_ROOTFS_SIZE` for 3972 additional information. 3973 3974 :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3975 Defines additional free disk space created in the image in Kbytes. By 3976 default, this variable is set to "0". This free disk space is added 3977 to the image after the build system determines the image size as 3978 described in :term:`IMAGE_ROOTFS_SIZE`. 3979 3980 This variable is particularly useful when you want to ensure that a 3981 specific amount of free disk space is available on a device after an 3982 image is installed and running. For example, to be sure 5 Gbytes of 3983 free disk space is available, set the variable as follows:: 3984 3985 IMAGE_ROOTFS_EXTRA_SPACE = "5242880" 3986 3987 For example, the Yocto Project Build Appliance specifically requests 3988 40 Gbytes of extra space with the line:: 3989 3990 IMAGE_ROOTFS_EXTRA_SPACE = "41943040" 3991 3992 :term:`IMAGE_ROOTFS_SIZE` 3993 Defines the size in Kbytes for the generated image. The OpenEmbedded 3994 build system determines the final size for the generated image using 3995 an algorithm that takes into account the initial disk space used for 3996 the generated image, a requested size for the image, and requested 3997 additional free disk space to be added to the image. Programatically, 3998 the build system determines the final size of the generated image as 3999 follows:: 4000 4001 if (image-du * overhead) < rootfs-size: 4002 internal-rootfs-size = rootfs-size + xspace 4003 else: 4004 internal-rootfs-size = (image-du * overhead) + xspace 4005 where: 4006 image-du = Returned value of the du command on the image. 4007 overhead = IMAGE_OVERHEAD_FACTOR 4008 rootfs-size = IMAGE_ROOTFS_SIZE 4009 internal-rootfs-size = Initial root filesystem size before any modifications. 4010 xspace = IMAGE_ROOTFS_EXTRA_SPACE 4011 4012 See the :term:`IMAGE_OVERHEAD_FACTOR` 4013 and :term:`IMAGE_ROOTFS_EXTRA_SPACE` 4014 variables for related information. 4015 4016 :term:`IMAGE_TYPEDEP` 4017 Specifies a dependency from one image type on another. Here is an 4018 example from the :ref:`ref-classes-image-live` class:: 4019 4020 IMAGE_TYPEDEP:live = "ext3" 4021 4022 In the previous example, the variable ensures that when "live" is 4023 listed with the :term:`IMAGE_FSTYPES` variable, 4024 the OpenEmbedded build system produces an ``ext3`` image first since 4025 one of the components of the live image is an ``ext3`` formatted 4026 partition containing the root filesystem. 4027 4028 :term:`IMAGE_TYPES` 4029 Specifies the complete list of supported image types by default: 4030 4031 - btrfs 4032 - container 4033 - cpio 4034 - cpio.gz 4035 - cpio.lz4 4036 - cpio.lzma 4037 - cpio.xz 4038 - cramfs 4039 - erofs 4040 - erofs-lz4 4041 - erofs-lz4hc 4042 - ext2 4043 - ext2.bz2 4044 - ext2.gz 4045 - ext2.lzma 4046 - ext3 4047 - ext3.gz 4048 - ext4 4049 - ext4.gz 4050 - f2fs 4051 - hddimg 4052 - iso 4053 - jffs2 4054 - jffs2.sum 4055 - multiubi 4056 - squashfs 4057 - squashfs-lz4 4058 - squashfs-lzo 4059 - squashfs-xz 4060 - tar 4061 - tar.bz2 4062 - tar.gz 4063 - tar.lz4 4064 - tar.xz 4065 - tar.zst 4066 - ubi 4067 - ubifs 4068 - wic 4069 - wic.bz2 4070 - wic.gz 4071 - wic.lzma 4072 - wic.zst 4073 4074 For more information about these types of images, see 4075 ``meta/classes-recipe/image_types*.bbclass`` in the :term:`Source Directory`. 4076 4077 :term:`IMAGE_VERSION_SUFFIX` 4078 Version suffix that is part of the default :term:`IMAGE_NAME` and 4079 :term:`KERNEL_ARTIFACT_NAME` values. 4080 Defaults to ``"-${DATETIME}"``, however you could set this to a 4081 version string that comes from your external build environment if 4082 desired, and this suffix would then be used consistently across 4083 the build artifacts. 4084 4085 :term:`IMGDEPLOYDIR` 4086 When inheriting the :ref:`ref-classes-image` class directly or 4087 through the :ref:`ref-classes-core-image` class, the 4088 :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files 4089 that is set in the ``image`` class as follows:: 4090 4091 IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete" 4092 4093 Recipes inheriting the :ref:`ref-classes-image` class should copy 4094 files to be deployed into :term:`IMGDEPLOYDIR`, and the class will take 4095 care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards. 4096 4097 :term:`IMGMANIFESTDIR` 4098 When inheriting the :ref:`ref-classes-image` class directly or through the 4099 :ref:`ref-classes-core-image` class, the :term:`IMGMANIFESTDIR` setting 4100 points to a temporary area that stores manifest ``json`` files, that list 4101 what images were created by various images creation tasks (as defined by 4102 the :term:`IMAGE_FSTYPES` variable). It is set in the 4103 :ref:`ref-classes-image` class as follows:: 4104 4105 IMGMANIFESTDIR = "${WORKDIR}/image-task-manifest" 4106 4107 :term:`INCOMPATIBLE_LICENSE` 4108 Specifies a space-separated list of license names (as they would 4109 appear in :term:`LICENSE`) that should be excluded 4110 from the build (if set globally), or from an image (if set locally 4111 in an image recipe). 4112 4113 When the variable is set globally, recipes that provide no alternatives to listed 4114 incompatible licenses are not built. Packages that are individually 4115 licensed with the specified incompatible licenses will be deleted. 4116 Most of the time this does not allow a feasible build (because it becomes impossible 4117 to satisfy build time dependencies), so the recommended way to 4118 implement license restrictions is to set the variable in specific 4119 image recipes where the restrictions must apply. That way there 4120 are no build time restrictions, but the license check is still 4121 performed when the image's filesystem is assembled from packages. 4122 4123 There is some support for wildcards in this variable's value, 4124 however it is restricted to specific licenses. Currently only 4125 these wildcards are allowed and expand as follows: 4126 4127 - ``AGPL-3.0*"``: ``AGPL-3.0-only``, ``AGPL-3.0-or-later`` 4128 - ``GPL-3.0*``: ``GPL-3.0-only``, ``GPL-3.0-or-later`` 4129 - ``LGPL-3.0*``: ``LGPL-3.0-only``, ``LGPL-3.0-or-later`` 4130 4131 .. note:: 4132 4133 This functionality is only regularly tested using the following 4134 setting:: 4135 4136 INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*" 4137 4138 4139 Although you can use other settings, you might be required to 4140 remove dependencies on (or provide alternatives to) components that 4141 are required to produce a functional system image. 4142 4143 :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS` 4144 Specifies a space-separated list of package and license pairs that 4145 are allowed to be used even if the license is specified in 4146 :term:`INCOMPATIBLE_LICENSE`. The package and license pairs are 4147 separated using a colon. Example:: 4148 4149 INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only" 4150 4151 :term:`INHERIT` 4152 Causes the named class or classes to be inherited globally. Anonymous 4153 functions in the class or classes are not executed for the base 4154 configuration and in each individual recipe. The OpenEmbedded build 4155 system ignores changes to :term:`INHERIT` in individual recipes. 4156 Classes inherited using :term:`INHERIT` must be located in the 4157 ``classes-global/`` or ``classes/`` subdirectories. 4158 4159 For more information on :term:`INHERIT`, see the 4160 :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" 4161 section in the BitBake User Manual. 4162 4163 :term:`INHERIT_DISTRO` 4164 Lists classes that will be inherited at the distribution level. It is 4165 unlikely that you want to edit this variable. 4166 4167 Classes specified in :term:`INHERIT_DISTRO` must be located in the 4168 ``classes-global/`` or ``classes/`` subdirectories. 4169 4170 The default value of the variable is set as follows in the 4171 ``meta/conf/distro/defaultsetup.conf`` file:: 4172 4173 INHERIT_DISTRO ?= "debian devshell sstate license remove-libtool create-spdx" 4174 4175 :term:`INHIBIT_DEFAULT_DEPS` 4176 Prevents the default dependencies, namely the C compiler and standard 4177 C library (libc), from being added to :term:`DEPENDS`. 4178 This variable is usually used within recipes that do not require any 4179 compilation using the C compiler. 4180 4181 Set the variable to "1" to prevent the default dependencies from 4182 being added. 4183 4184 :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` 4185 Prevents the OpenEmbedded build system from splitting out debug 4186 information during packaging. By default, the build system splits out 4187 debugging information during the 4188 :ref:`ref-tasks-package` task. For more information on 4189 how debug information is split out, see the 4190 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 4191 variable. 4192 4193 To prevent the build system from splitting out debug information 4194 during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as 4195 follows:: 4196 4197 INHIBIT_PACKAGE_DEBUG_SPLIT = "1" 4198 4199 :term:`INHIBIT_PACKAGE_STRIP` 4200 If set to "1", causes the build to not strip binaries in resulting 4201 packages and prevents the ``-dbg`` package from containing the source 4202 files. 4203 4204 By default, the OpenEmbedded build system strips binaries and puts 4205 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. 4206 Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you 4207 plan to debug in general. 4208 4209 :term:`INHIBIT_SYSROOT_STRIP` 4210 If set to "1", causes the build to not strip binaries in the 4211 resulting sysroot. 4212 4213 By default, the OpenEmbedded build system strips binaries in the 4214 resulting sysroot. When you specifically set the 4215 :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit 4216 this stripping. 4217 4218 If you want to use this variable, include the :ref:`ref-classes-staging` 4219 class. This class uses a ``sys_strip()`` function to test for the variable 4220 and acts accordingly. 4221 4222 .. note:: 4223 4224 Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and 4225 special circumstances. For example, suppose you are building 4226 bare-metal firmware by using an external GCC toolchain. Furthermore, 4227 even if the toolchain's binaries are strippable, there are other files 4228 needed for the build that are not strippable. 4229 4230 :term:`INIT_MANAGER` 4231 Specifies the system init manager to use. Available options are: 4232 4233 - ``sysvinit`` 4234 - ``systemd`` 4235 - ``mdev-busybox`` 4236 4237 With ``sysvinit``, the init manager is set to 4238 :wikipedia:`SysVinit <Init#SysV-style>`, the traditional UNIX init 4239 system. This is the default choice in the Poky distribution, together with 4240 the Udev device manager (see the ":ref:`device-manager`" section). 4241 4242 With ``systemd``, the init manager becomes :wikipedia:`systemd <Systemd>`, 4243 which comes with the :wikipedia:`udev <Udev>` device manager. 4244 4245 With ``mdev-busybox``, the init manager becomes the much simpler BusyBox 4246 init, together with the BusyBox mdev device manager. This is the simplest 4247 and lightest solution, and probably the best choice for low-end systems 4248 with a rather slow CPU and a limited amount of RAM. 4249 4250 More concretely, this is used to include 4251 ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global 4252 configuration. You can have a look at the 4253 :yocto_git:`meta/conf/distro/include/init-manager-*.inc </poky/tree/meta/conf/distro/include>` 4254 files for more information, and also the ":ref:`init-manager`" 4255 section in the Yocto Project Development Tasks Manual. 4256 4257 :term:`INITRAMFS_DEPLOY_DIR_IMAGE` 4258 Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs` 4259 where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is 4260 set by default to ``${DEPLOY_DIR_IMAGE}`` in the 4261 :ref:`ref-classes-kernel` class and it's only meant to be changed when 4262 building an :term:`Initramfs` image from a separate multiconfig via 4263 :term:`INITRAMFS_MULTICONFIG`. 4264 4265 :term:`INITRAMFS_FSTYPES` 4266 Defines the format for the output image of an initial RAM filesystem 4267 (:term:`Initramfs`), which is used during boot. Supported formats are the 4268 same as those supported by the 4269 :term:`IMAGE_FSTYPES` variable. 4270 4271 The default value of this variable, which is set in the 4272 ``meta/conf/bitbake.conf`` configuration file in the 4273 :term:`Source Directory`, is "cpio.gz". The Linux kernel's 4274 :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem 4275 :wikipedia:`initrd <Initrd>` mechanism, expects 4276 an optionally compressed cpio archive. 4277 4278 :term:`INITRAMFS_IMAGE` 4279 Specifies the :term:`PROVIDES` name of an image 4280 recipe that is used to build an initial RAM filesystem (:term:`Initramfs`) 4281 image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an 4282 additional recipe to be built as a dependency to whatever root 4283 filesystem recipe you might be using (e.g. ``core-image-sato``). The 4284 :term:`Initramfs` image recipe you provide should set 4285 :term:`IMAGE_FSTYPES` to 4286 :term:`INITRAMFS_FSTYPES`. 4287 4288 An :term:`Initramfs` image provides a temporary root filesystem used for 4289 early system initialization (e.g. loading of modules needed to locate 4290 and mount the "real" root filesystem). 4291 4292 .. note:: 4293 4294 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` 4295 recipe in the :term:`Source Directory` 4296 for an example :term:`Initramfs` recipe. To select this sample recipe as 4297 the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE` 4298 to "core-image-minimal-initramfs". 4299 4300 You can also find more information by referencing the 4301 ``meta-poky/conf/templates/default/local.conf.sample.extended`` 4302 configuration file in the Source Directory, the :ref:`ref-classes-image` 4303 class, and the :ref:`ref-classes-kernel` class to see how to use the 4304 :term:`INITRAMFS_IMAGE` variable. 4305 4306 If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no 4307 :term:`Initramfs` image is built. 4308 4309 For more information, you can also see the 4310 :term:`INITRAMFS_IMAGE_BUNDLE` 4311 variable, which allows the generated image to be bundled inside the 4312 kernel image. Additionally, for information on creating an :term:`Initramfs` 4313 image, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 4314 in the Yocto Project Development Tasks Manual. 4315 4316 :term:`INITRAMFS_IMAGE_BUNDLE` 4317 Controls whether or not the image recipe specified by 4318 :term:`INITRAMFS_IMAGE` is run through an 4319 extra pass 4320 (:ref:`ref-tasks-bundle_initramfs`) during 4321 kernel compilation in order to build a single binary that contains 4322 both the kernel image and the initial RAM filesystem (:term:`Initramfs`) 4323 image. This makes use of the 4324 :term:`CONFIG_INITRAMFS_SOURCE` kernel 4325 feature. 4326 4327 .. note:: 4328 4329 Bundling the :term:`Initramfs` with the kernel conflates the code in the 4330 :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 4331 compatible software may be part of a bundled :term:`Initramfs`. 4332 4333 .. note:: 4334 4335 Using an extra compilation pass to bundle the :term:`Initramfs` avoids a 4336 circular dependency between the kernel recipe and the :term:`Initramfs` 4337 recipe should the :term:`Initramfs` include kernel modules. Should that be 4338 the case, the :term:`Initramfs` recipe depends on the kernel for the 4339 kernel modules, and the kernel depends on the :term:`Initramfs` recipe 4340 since the :term:`Initramfs` is bundled inside the kernel image. 4341 4342 The combined binary is deposited into the ``tmp/deploy`` directory, 4343 which is part of the :term:`Build Directory`. 4344 4345 Setting the variable to "1" in a configuration file causes the 4346 OpenEmbedded build system to generate a kernel image with the 4347 :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within:: 4348 4349 INITRAMFS_IMAGE_BUNDLE = "1" 4350 4351 By default, the :ref:`ref-classes-kernel` class sets this variable to a 4352 null string as follows:: 4353 4354 INITRAMFS_IMAGE_BUNDLE ?= "" 4355 4356 .. note:: 4357 4358 You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a 4359 configuration file. You cannot set the variable in a recipe file. 4360 4361 See the 4362 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>` 4363 file for additional information. Also, for information on creating an 4364 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 4365 in the Yocto Project Development Tasks Manual. 4366 4367 :term:`INITRAMFS_IMAGE_NAME` 4368 4369 This value needs to stay in sync with :term:`IMAGE_LINK_NAME`, but with 4370 :term:`INITRAMFS_IMAGE` instead of :term:`IMAGE_BASENAME`. The default value 4371 is set as follows: 4372 4373 INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}" 4374 4375 That is, if :term:`INITRAMFS_IMAGE` is set, the value of 4376 :term:`INITRAMFS_IMAGE_NAME` will be set based upon 4377 :term:`INITRAMFS_IMAGE` and :term:`IMAGE_MACHINE_SUFFIX`. 4378 4379 4380 :term:`INITRAMFS_LINK_NAME` 4381 The link name of the initial RAM filesystem image. This variable is 4382 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4383 follows:: 4384 4385 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" 4386 4387 The value of the 4388 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4389 file, has the following value:: 4390 4391 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4392 4393 See the :term:`MACHINE` variable for additional 4394 information. 4395 4396 :term:`INITRAMFS_MULTICONFIG` 4397 Defines the multiconfig to create a multiconfig dependency to be used by 4398 the :ref:`ref-classes-kernel` class. 4399 4400 This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from 4401 a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`. 4402 4403 For more information on how to bundle an :term:`Initramfs` image from a separate 4404 multiconfig see the ":ref:`dev-manual/building:Bundling an Initramfs Image From a Separate Multiconfig`" 4405 section in the Yocto Project Development Tasks Manual. 4406 4407 :term:`INITRAMFS_NAME` 4408 The base name of the initial RAM filesystem image. This variable is 4409 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4410 follows:: 4411 4412 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" 4413 4414 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4415 4416 :term:`INITRD` 4417 Indicates list of filesystem images to concatenate and use as an 4418 initial RAM disk (``initrd``). 4419 4420 The :term:`INITRD` variable is an optional variable used with the 4421 :ref:`ref-classes-image-live` class. 4422 4423 :term:`INITRD_IMAGE` 4424 When building a "live" bootable image (i.e. when 4425 :term:`IMAGE_FSTYPES` contains "live"), 4426 :term:`INITRD_IMAGE` specifies the image recipe that should be built to 4427 provide the initial RAM disk image. The default value is 4428 "core-image-minimal-initramfs". 4429 4430 See the :ref:`ref-classes-image-live` class for more information. 4431 4432 :term:`INITSCRIPT_NAME` 4433 The filename of the initialization script as installed to 4434 ``${sysconfdir}/init.d``. 4435 4436 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. 4437 The variable is mandatory. 4438 4439 :term:`INITSCRIPT_PACKAGES` 4440 A list of the packages that contain initscripts. If multiple packages 4441 are specified, you need to append the package name to the other 4442 ``INITSCRIPT_*`` as an override. 4443 4444 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. 4445 The variable is optional and defaults to the :term:`PN` 4446 variable. 4447 4448 :term:`INITSCRIPT_PARAMS` 4449 Specifies the options to pass to ``update-rc.d``. Here is an example:: 4450 4451 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." 4452 4453 In this example, the script has a runlevel of 99, starts the script 4454 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. 4455 4456 The variable's default value is "defaults", which is set in the 4457 :ref:`ref-classes-update-rc.d` class. 4458 4459 The value in :term:`INITSCRIPT_PARAMS` is passed through to the 4460 ``update-rc.d`` command. For more information on valid parameters, 4461 please see the ``update-rc.d`` manual page at 4462 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html 4463 4464 :term:`INSANE_SKIP` 4465 Specifies the QA checks to skip for a specific package within a 4466 recipe. For example, to skip the check for symbolic link ``.so`` 4467 files in the main package of a recipe, add the following to the 4468 recipe. The package name override must be used, which in this example 4469 is ``${PN}``:: 4470 4471 INSANE_SKIP:${PN} += "dev-so" 4472 4473 See the ":ref:`ref-classes-insane`" section for a 4474 list of the valid QA checks you can specify using this variable. 4475 4476 :term:`INSTALL_TIMEZONE_FILE` 4477 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. 4478 Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the 4479 configuration level to disable this behavior. 4480 4481 :term:`IPK_FEED_URIS` 4482 When the IPK backend is in use and package management is enabled on 4483 the target, you can use this variable to set up ``opkg`` in the 4484 target image to point to package feeds on a nominated server. Once 4485 the feed is established, you can perform installations or upgrades 4486 using the package manager at runtime. 4487 4488 :term:`KARCH` 4489 Defines the kernel architecture used when assembling the 4490 configuration. Architectures supported for this release are: 4491 4492 - powerpc 4493 - i386 4494 - x86_64 4495 - arm 4496 - qemu 4497 - mips 4498 4499 You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. 4500 4501 :term:`KBRANCH` 4502 A regular expression used by the build process to explicitly identify 4503 the kernel branch that is validated, patched, and configured during a 4504 build. You must set this variable to ensure the exact kernel branch 4505 you want is being used by the build process. 4506 4507 Values for this variable are set in the kernel's recipe file and the 4508 kernel's append file. For example, if you are using the 4509 ``linux-yocto_4.12`` kernel, the kernel recipe file is the 4510 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH` 4511 is set as follows in that kernel recipe file:: 4512 4513 KBRANCH ?= "standard/base" 4514 4515 This variable is also used from the kernel's append file to identify 4516 the kernel branch specific to a particular machine or target 4517 hardware. Continuing with the previous kernel example, the kernel's 4518 append file is located in the 4519 BSP layer for a given machine. For example, the append file for the 4520 Beaglebone and generic versions of both 32 and 64-bit IA 4521 machines (``meta-yocto-bsp``) is named 4522 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend``. 4523 Here are the related statements from that append file:: 4524 4525 KBRANCH:genericx86 = "v6.1/standard/base" 4526 KBRANCH:genericx86-64 = "v6.1/standard/base" 4527 KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" 4528 4529 The :term:`KBRANCH` statements 4530 identify the kernel branch to use when building for each supported 4531 BSP. 4532 4533 :term:`KBUILD_DEFCONFIG` 4534 When used with the :ref:`ref-classes-kernel-yocto` 4535 class, specifies an "in-tree" kernel configuration file for use 4536 during a kernel build. 4537 4538 Typically, when using a ``defconfig`` to configure a kernel during a 4539 build, you place the file in your layer in the same manner as you 4540 would place patch files and configuration fragment files (i.e. 4541 "out-of-tree"). However, if you want to use a ``defconfig`` file that 4542 is part of the kernel tree (i.e. "in-tree"), you can use the 4543 :term:`KBUILD_DEFCONFIG` variable and append the 4544 :term:`KMACHINE` variable to point to the 4545 ``defconfig`` file. 4546 4547 To use the variable, set it in the append file for your kernel recipe 4548 using the following form:: 4549 4550 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file" 4551 4552 Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses 4553 a ``defconfig`` file named "bcm2709_defconfig":: 4554 4555 KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig" 4556 4557 As an alternative, you can use the following within your append file:: 4558 4559 KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file" 4560 4561 For more 4562 information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the 4563 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" 4564 section in the Yocto Project Linux Kernel Development Manual. 4565 4566 :term:`KCONFIG_MODE` 4567 When used with the :ref:`ref-classes-kernel-yocto` 4568 class, specifies the kernel configuration values to use for options 4569 not specified in the provided ``defconfig`` file. Valid options are:: 4570 4571 KCONFIG_MODE = "alldefconfig" 4572 KCONFIG_MODE = "allnoconfig" 4573 4574 In ``alldefconfig`` mode the options not explicitly specified will be 4575 assigned their Kconfig default value. In ``allnoconfig`` mode the 4576 options not explicitly specified will be disabled in the kernel 4577 config. 4578 4579 In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where 4580 the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file 4581 will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed 4582 in ``${WORKDIR}`` through a meta-layer will be handled in 4583 ``allnoconfig`` mode. 4584 4585 An "in-tree" ``defconfig`` file can be selected via the 4586 :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to 4587 be explicitly set. 4588 4589 A ``defconfig`` file compatible with ``allnoconfig`` mode can be 4590 generated by copying the ``.config`` file from a working Linux kernel 4591 build, renaming it to ``defconfig`` and placing it into the Linux 4592 kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does 4593 not need to be explicitly set. 4594 4595 A ``defconfig`` file compatible with ``alldefconfig`` mode can be 4596 generated using the 4597 :ref:`ref-tasks-savedefconfig` 4598 task and placed into the Linux kernel ``${WORKDIR}`` through your 4599 meta-layer. Explicitely set :term:`KCONFIG_MODE`:: 4600 4601 KCONFIG_MODE = "alldefconfig" 4602 4603 :term:`KERNEL_ALT_IMAGETYPE` 4604 Specifies an alternate kernel image type for creation in addition to 4605 the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and 4606 :term:`KERNEL_IMAGETYPES` variables. 4607 4608 :term:`KERNEL_ARTIFACT_NAME` 4609 Specifies the name of all of the build artifacts. You can change the 4610 name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME` 4611 variable. 4612 4613 The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the 4614 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the 4615 following default value:: 4616 4617 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" 4618 4619 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`IMAGE_MACHINE_SUFFIX` 4620 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information. 4621 4622 :term:`KERNEL_CLASSES` 4623 A list of classes defining kernel image types that the 4624 :ref:`ref-classes-kernel` class should inherit. You typically 4625 append this variable to enable extended image types. An example is 4626 ":ref:`ref-classes-kernel-fitimage`", which enables 4627 FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``. 4628 You can register custom kernel image types with the 4629 :ref:`ref-classes-kernel` class using this variable. 4630 4631 :term:`KERNEL_CONSOLE` 4632 The :term:`KERNEL_CONSOLE` variable holds the value of the ``console`` 4633 parameter of the kernel command line and can be used in places such as a 4634 ``wks`` description file for :ref:`Wic images <dev-manual/wic:creating 4635 partitioned images using wic>`. 4636 4637 The default value of this variable is extracted from the first console 4638 device and setting in :term:`SERIAL_CONSOLES`. If nothing is found in 4639 :term:`SERIAL_CONSOLES`, the default value is set to ``ttyS0,115200``. 4640 4641 For more information, see the `Kernel command-line documentation 4642 <https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html>`__. 4643 4644 :term:`KERNEL_DANGLING_FEATURES_WARN_ONLY` 4645 When kernel configuration fragments are missing for some 4646 :term:`KERNEL_FEATURES` specified by layers or BSPs, 4647 building and configuring the kernel stops with an error. 4648 4649 You can turn these errors into warnings by setting the 4650 following in ``conf/local.conf``:: 4651 4652 KERNEL_DANGLING_FEATURES_WARN_ONLY = "1" 4653 4654 You will still be warned that runtime issues may occur, 4655 but at least the kernel configuration and build process will 4656 be allowed to continue. 4657 4658 :term:`KERNEL_DEBUG_TIMESTAMPS` 4659 If set to "1", enables timestamping functionality during building 4660 the kernel. The default is "0" to disable this for reproducibility 4661 reasons. 4662 4663 :term:`KERNEL_DEPLOY_DEPEND` 4664 Provides a means of controlling the dependency of an image recipe 4665 on the kernel. The default value is "virtual/kernel:do_deploy", 4666 however for a small initramfs image or other images that do not 4667 need the kernel, this can be set to "" in the image recipe. 4668 4669 :term:`KERNEL_DEVICETREE` 4670 Specifies the name of the generated Linux kernel device tree (i.e. 4671 the ``.dtb``) file. 4672 4673 .. note:: 4674 4675 There is legacy support for specifying the full path to the device 4676 tree. However, providing just the ``.dtb`` file is preferred. 4677 4678 In order to use this variable, the :ref:`ref-classes-kernel-devicetree` 4679 class must be inherited. 4680 4681 :term:`KERNEL_DEVICETREE_BUNDLE` 4682 When set to "1", this variable allows to bundle the Linux kernel 4683 and the Device Tree Binary together in a single file. 4684 4685 This feature is currently only supported on the "arm" (32 bit) 4686 architecture. 4687 4688 This variable is set to "0" by default by the 4689 :ref:`ref-classes-kernel-devicetree` class. 4690 4691 :term:`KERNEL_DTB_LINK_NAME` 4692 The link name of the kernel device tree binary (DTB). This variable 4693 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4694 follows:: 4695 4696 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4697 4698 The 4699 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in 4700 the same file, has the following value:: 4701 4702 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4703 4704 See the :term:`MACHINE` variable for additional 4705 information. 4706 4707 :term:`KERNEL_DTB_NAME` 4708 The base name of the kernel device tree binary (DTB). This variable 4709 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4710 follows:: 4711 4712 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4713 4714 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4715 4716 :term:`KERNEL_DTBDEST` 4717 This variable, used by the :ref:`ref-classes-kernel-devicetree` 4718 class, allows to change the installation directory of the DTB 4719 (Device Tree Binary) files. 4720 4721 It is set by default to "${KERNEL_IMAGEDEST}" by the 4722 :ref:`ref-classes-kernel` class. 4723 4724 :term:`KERNEL_DTBVENDORED` 4725 This variable, used by the :ref:`ref-classes-kernel-devicetree`, 4726 allows to ignore vendor subdirectories when installing DTB 4727 (Device Tree Binary) files, when it is set to "false". 4728 4729 To keep vendor subdirectories, set this variable to "true". 4730 4731 It is set by default to "false" by the :ref:`ref-classes-kernel` class. 4732 4733 :term:`KERNEL_DTC_FLAGS` 4734 Specifies the ``dtc`` flags that are passed to the Linux kernel build 4735 system when generating the device trees (via ``DTC_FLAGS`` environment 4736 variable). 4737 4738 In order to use this variable, the :ref:`ref-classes-kernel-devicetree` 4739 class must be inherited. 4740 4741 :term:`KERNEL_EXTRA_ARGS` 4742 Specifies additional ``make`` command-line arguments the OpenEmbedded 4743 build system passes on when compiling the kernel. 4744 4745 :term:`KERNEL_FEATURES` 4746 Includes additional kernel metadata. In the OpenEmbedded build 4747 system, the default Board Support Packages (BSPs) 4748 :term:`Metadata` is provided through the 4749 :term:`KMACHINE` and :term:`KBRANCH` 4750 variables. You can use the :term:`KERNEL_FEATURES` variable from within 4751 the kernel recipe or kernel append file to further add metadata for 4752 all BSPs or specific BSPs. 4753 4754 The metadata you add through this variable includes config fragments 4755 and features descriptions, which usually includes patches as well as 4756 config fragments. You typically override the :term:`KERNEL_FEATURES` 4757 variable for a specific machine. In this way, you can provide 4758 validated, but optional, sets of kernel configurations and features. 4759 4760 For example, the following example from the ``linux-yocto-rt_4.12`` 4761 kernel recipe adds "netfilter" and "taskstats" features to all BSPs 4762 as well as "virtio" configurations to all QEMU machines. The last two 4763 statements add specific configurations to targeted machine types:: 4764 4765 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" 4766 KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" 4767 KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc" 4768 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" 4769 KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc" 4770 4771 :term:`KERNEL_FIT_LINK_NAME` 4772 The link name of the kernel flattened image tree (FIT) image. This 4773 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` 4774 file as follows:: 4775 4776 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4777 4778 The value of the 4779 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4780 file, has the following value:: 4781 4782 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4783 4784 See the :term:`MACHINE` variable for additional 4785 information. 4786 4787 :term:`KERNEL_FIT_NAME` 4788 The base name of the kernel flattened image tree (FIT) image. This 4789 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` 4790 file as follows:: 4791 4792 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4793 4794 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4795 4796 :term:`KERNEL_IMAGE_LINK_NAME` 4797 The link name for the kernel image. This variable is set in the 4798 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 4799 4800 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4801 4802 The value of 4803 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4804 file, has the following value:: 4805 4806 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4807 4808 See the :term:`MACHINE` variable for additional 4809 information. 4810 4811 :term:`KERNEL_IMAGE_MAXSIZE` 4812 Specifies the maximum size of the kernel image file in kilobytes. If 4813 :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is 4814 checked against the set value during the 4815 :ref:`ref-tasks-sizecheck` task. The task fails if 4816 the kernel image file is larger than the setting. 4817 4818 :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a 4819 limited amount of space in which the kernel image must be stored. 4820 4821 By default, this variable is not set, which means the size of the 4822 kernel image is not checked. 4823 4824 :term:`KERNEL_IMAGE_NAME` 4825 The base name of the kernel image. This variable is set in the 4826 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 4827 4828 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4829 4830 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4831 4832 :term:`KERNEL_IMAGETYPE` 4833 The type of kernel to build for a device, usually set by the machine 4834 configuration files and defaults to "zImage". This variable is used 4835 when building the kernel and is passed to ``make`` as the target to 4836 build. 4837 4838 To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`. 4839 4840 :term:`KERNEL_IMAGETYPES` 4841 Lists additional types of kernel images to build for a device in addition 4842 to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the 4843 machine configuration files. 4844 4845 :term:`KERNEL_MODULE_AUTOLOAD` 4846 Lists kernel modules that need to be auto-loaded during boot. 4847 4848 .. note:: 4849 4850 This variable replaces the deprecated :term:`module_autoload` 4851 variable. 4852 4853 You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it 4854 can be recognized by the kernel recipe or by an out-of-tree kernel 4855 module recipe (e.g. a machine configuration file, a distribution 4856 configuration file, an append file for the recipe, or the recipe 4857 itself). 4858 4859 Specify it as follows:: 4860 4861 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" 4862 4863 Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build 4864 system to populate the ``/etc/modules-load.d/modname.conf`` file with 4865 the list of modules to be auto-loaded on boot. The modules appear 4866 one-per-line in the file. Here is an example of the most common use 4867 case:: 4868 4869 KERNEL_MODULE_AUTOLOAD += "module_name" 4870 4871 For information on how to populate the ``modname.conf`` file with 4872 ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable. 4873 4874 :term:`KERNEL_MODULE_PROBECONF` 4875 Provides a list of modules for which the OpenEmbedded build system 4876 expects to find ``module_conf_``\ modname values that specify 4877 configuration for each of the modules. For information on how to 4878 provide those module configurations, see the 4879 :term:`module_conf_* <module_conf>` variable. 4880 4881 :term:`KERNEL_PACKAGE_NAME` 4882 Specifies the base name of the kernel packages, such as "kernel" 4883 in the kernel packages such as "kernel-modules", "kernel-image" and 4884 "kernel-dbg". 4885 4886 The default value for this variable is set to "kernel" by the 4887 :ref:`ref-classes-kernel` class. 4888 4889 :term:`KERNEL_PATH` 4890 The location of the kernel sources. This variable is set to the value 4891 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` 4892 class. For information on how this variable is used, see the 4893 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4894 section in the Yocto Project Linux Kernel Development Manual. 4895 4896 To help maximize compatibility with out-of-tree drivers used to build 4897 modules, the OpenEmbedded build system also recognizes and uses the 4898 :term:`KERNEL_SRC` variable, which is identical to 4899 the :term:`KERNEL_PATH` variable. Both variables are common variables 4900 used by external Makefiles to point to the kernel source directory. 4901 4902 :term:`KERNEL_SRC` 4903 The location of the kernel sources. This variable is set to the value 4904 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` 4905 class. For information on how this variable is used, see the 4906 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4907 section in the Yocto Project Linux Kernel Development Manual. 4908 4909 To help maximize compatibility with out-of-tree drivers used to build 4910 modules, the OpenEmbedded build system also recognizes and uses the 4911 :term:`KERNEL_PATH` variable, which is identical 4912 to the :term:`KERNEL_SRC` variable. Both variables are common variables 4913 used by external Makefiles to point to the kernel source directory. 4914 4915 :term:`KERNEL_STRIP` 4916 Allows to specific which ``strip`` command to use to strip the kernel 4917 binary, typically either GNU binutils ``strip`` or ``llvm-strip``. 4918 4919 :term:`KERNEL_VERSION` 4920 Specifies the version of the kernel as extracted from ``version.h`` 4921 or ``utsrelease.h`` within the kernel sources. Effects of setting 4922 this variable do not take effect until the kernel has been 4923 configured. Consequently, attempting to refer to this variable in 4924 contexts prior to configuration will not work. 4925 4926 :term:`KERNELDEPMODDEPEND` 4927 Specifies whether the data referenced through 4928 :term:`PKGDATA_DIR` is needed or not. 4929 :term:`KERNELDEPMODDEPEND` does not control whether or not that data 4930 exists, but simply whether or not it is used. If you do not need to 4931 use the data, set the :term:`KERNELDEPMODDEPEND` variable in your 4932 :term:`Initramfs` recipe. Setting the variable there when the data is not 4933 needed avoids a potential dependency loop. 4934 4935 :term:`KFEATURE_DESCRIPTION` 4936 Provides a short description of a configuration fragment. You use 4937 this variable in the ``.scc`` file that describes a configuration 4938 fragment file. Here is the variable used in a file named ``smp.scc`` 4939 to describe SMP being enabled:: 4940 4941 define KFEATURE_DESCRIPTION "Enable SMP" 4942 4943 :term:`KMACHINE` 4944 The machine as known by the kernel. Sometimes the machine name used 4945 by the kernel does not match the machine name used by the 4946 OpenEmbedded build system. For example, the machine name that the 4947 OpenEmbedded build system understands as ``core2-32-intel-common`` 4948 goes by a different name in the Linux Yocto kernel. The kernel 4949 understands that machine as ``intel-core2-32``. For cases like these, 4950 the :term:`KMACHINE` variable maps the kernel machine name to the 4951 OpenEmbedded build system machine name. 4952 4953 These mappings between different names occur in the Yocto Linux 4954 Kernel's ``meta`` branch. As an example take a look in the 4955 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:: 4956 4957 LINUX_VERSION:core2-32-intel-common = "3.19.0" 4958 COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}" 4959 SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" 4960 SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" 4961 KMACHINE:core2-32-intel-common = "intel-core2-32" 4962 KBRANCH:core2-32-intel-common = "standard/base" 4963 KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}" 4964 4965 The :term:`KMACHINE` statement says 4966 that the kernel understands the machine name as "intel-core2-32". 4967 However, the OpenEmbedded build system understands the machine as 4968 "core2-32-intel-common". 4969 4970 :term:`KTYPE` 4971 Defines the kernel type to be used in assembling the configuration. 4972 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 4973 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" 4974 section in the 4975 Yocto Project Linux Kernel Development Manual for more information on 4976 kernel types. 4977 4978 You define the :term:`KTYPE` variable in the 4979 :ref:`kernel-dev/advanced:bsp descriptions`. The 4980 value you use must match the value used for the 4981 :term:`LINUX_KERNEL_TYPE` value used by the 4982 kernel recipe. 4983 4984 :term:`LABELS` 4985 Provides a list of targets for automatic configuration. 4986 4987 See the :ref:`ref-classes-grub-efi` class for more 4988 information on how this variable is used. 4989 4990 :term:`LAYERDEPENDS` 4991 Lists the layers, separated by spaces, on which this recipe depends. 4992 Optionally, you can specify a specific layer version for a dependency 4993 by adding it to the end of the layer name. Here is an example:: 4994 4995 LAYERDEPENDS_mylayer = "anotherlayer (=3)" 4996 4997 In this previous example, 4998 version 3 of "anotherlayer" is compared against 4999 :term:`LAYERVERSION`\ ``_anotherlayer``. 5000 5001 An error is produced if any dependency is missing or the version 5002 numbers (if specified) do not match exactly. This variable is used in 5003 the ``conf/layer.conf`` file and must be suffixed with the name of 5004 the specific layer (e.g. ``LAYERDEPENDS_mylayer``). 5005 5006 :term:`LAYERDIR` 5007 When used inside the ``layer.conf`` configuration file, this variable 5008 provides the path of the current layer. This variable is not 5009 available outside of ``layer.conf`` and references are expanded 5010 immediately when parsing of the file completes. 5011 5012 :term:`LAYERDIR_RE` 5013 See :term:`bitbake:LAYERDIR_RE` in the BitBake manual. 5014 5015 :term:`LAYERRECOMMENDS` 5016 Lists the layers, separated by spaces, recommended for use with this 5017 layer. 5018 5019 Optionally, you can specify a specific layer version for a 5020 recommendation by adding the version to the end of the layer name. 5021 Here is an example:: 5022 5023 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" 5024 5025 In this previous example, version 3 of "anotherlayer" is compared 5026 against ``LAYERVERSION_anotherlayer``. 5027 5028 This variable is used in the ``conf/layer.conf`` file and must be 5029 suffixed with the name of the specific layer (e.g. 5030 ``LAYERRECOMMENDS_mylayer``). 5031 5032 :term:`LAYERSERIES_COMPAT` 5033 See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual. 5034 5035 :term:`LAYERVERSION` 5036 Optionally specifies the version of a layer as a single number. You 5037 can use this within :term:`LAYERDEPENDS` for 5038 another layer in order to depend on a specific version of the layer. 5039 This variable is used in the ``conf/layer.conf`` file and must be 5040 suffixed with the name of the specific layer (e.g. 5041 ``LAYERVERSION_mylayer``). 5042 5043 :term:`LD` 5044 The minimal command and arguments used to run the linker. 5045 5046 :term:`LDFLAGS` 5047 Specifies the flags to pass to the linker. This variable is exported 5048 to an environment variable and thus made visible to the software 5049 being built during the compilation step. 5050 5051 Default initialization for :term:`LDFLAGS` varies depending on what is 5052 being built: 5053 5054 - :term:`TARGET_LDFLAGS` when building for the 5055 target 5056 5057 - :term:`BUILD_LDFLAGS` when building for the 5058 build host (i.e. ``-native``) 5059 5060 - :term:`BUILDSDK_LDFLAGS` when building for 5061 an SDK (i.e. ``nativesdk-``) 5062 5063 :term:`LEAD_SONAME` 5064 Specifies the lead (or primary) compiled library file (i.e. ``.so``) 5065 that the :ref:`ref-classes-debian` class applies its 5066 naming policy to given a recipe that packages multiple libraries. 5067 5068 This variable works in conjunction with the :ref:`ref-classes-debian` 5069 class. 5070 5071 :term:`LIC_FILES_CHKSUM` 5072 Checksums of the license text in the recipe source code. 5073 5074 This variable tracks changes in license text of the source code 5075 files. If the license text is changed, it will trigger a build 5076 failure, which gives the developer an opportunity to review any 5077 license change. 5078 5079 This variable must be defined for all recipes (unless 5080 :term:`LICENSE` is set to "CLOSED"). 5081 5082 For more information, see the ":ref:`dev-manual/licenses:tracking license changes`" 5083 section in the Yocto Project Development Tasks Manual. 5084 5085 :term:`LICENSE` 5086 The list of source licenses for the recipe. Follow these rules: 5087 5088 - Do not use spaces within individual license names. 5089 5090 - Separate license names using \| (pipe) when there is a choice 5091 between licenses. 5092 5093 - Separate license names using & (ampersand) when there are 5094 multiple licenses for different parts of the source. 5095 5096 - You can use spaces between license names. 5097 5098 - For standard licenses, use the names of the files in 5099 ``meta/files/common-licenses/`` or the 5100 :term:`SPDXLICENSEMAP` flag names defined in 5101 ``meta/conf/licenses.conf``. 5102 5103 Here are some examples:: 5104 5105 LICENSE = "LGPL-2.1-only | GPL-3.0-only" 5106 LICENSE = "MPL-1.0 & LGPL-2.1-only" 5107 LICENSE = "GPL-2.0-or-later" 5108 5109 The first example is from the 5110 recipes for Qt, which the user may choose to distribute under either 5111 the LGPL version 2.1 or GPL version 3. The second example is from 5112 Cairo where two licenses cover different parts of the source code. 5113 The final example is from ``sysstat``, which presents a single 5114 license. 5115 5116 You can also specify licenses on a per-package basis to handle 5117 situations where components of the output have different licenses. 5118 For example, a piece of software whose code is licensed under GPLv2 5119 but has accompanying documentation licensed under the GNU Free 5120 Documentation License 1.2 could be specified as follows:: 5121 5122 LICENSE = "GFDL-1.2 & GPL-2.0-only" 5123 LICENSE:${PN} = "GPL-2.0.only" 5124 LICENSE:${PN}-doc = "GFDL-1.2" 5125 5126 :term:`LICENSE_CREATE_PACKAGE` 5127 Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded 5128 build system to create an extra package (i.e. 5129 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add 5130 those packages to the 5131 :term:`RRECOMMENDS`\ ``:${PN}``. 5132 5133 The ``${PN}-lic`` package installs a directory in 5134 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base 5135 name, and installs files in that directory that contain license and 5136 copyright information (i.e. copies of the appropriate license files 5137 from ``meta/common-licenses`` that match the licenses specified in 5138 the :term:`LICENSE` variable of the recipe metadata 5139 and copies of files marked in 5140 :term:`LIC_FILES_CHKSUM` as containing 5141 license text). 5142 5143 For related information on providing license text, see the 5144 :term:`COPY_LIC_DIRS` variable, the 5145 :term:`COPY_LIC_MANIFEST` variable, and the 5146 ":ref:`dev-manual/licenses:providing license text`" 5147 section in the Yocto Project Development Tasks Manual. 5148 5149 :term:`LICENSE_FLAGS` 5150 Specifies additional flags for a recipe you must allow through 5151 :term:`LICENSE_FLAGS_ACCEPTED` in 5152 order for the recipe to be built. When providing multiple flags, 5153 separate them with spaces. 5154 5155 This value is independent of :term:`LICENSE` and is 5156 typically used to mark recipes that might require additional licenses 5157 in order to be used in a commercial product. For more information, 5158 see the 5159 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" 5160 section in the Yocto Project Development Tasks Manual. 5161 5162 :term:`LICENSE_FLAGS_ACCEPTED` 5163 Lists license flags that when specified in 5164 :term:`LICENSE_FLAGS` within a recipe should not 5165 prevent that recipe from being built. For more information, see the 5166 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" 5167 section in the Yocto Project Development Tasks Manual. 5168 5169 :term:`LICENSE_FLAGS_DETAILS` 5170 Adds details about a flag in :term:`LICENSE_FLAGS`. This way, 5171 if such a flag is not accepted through :term:`LICENSE_FLAGS_ACCEPTED`, 5172 the error message will be more informative, containing the specified 5173 extra details. 5174 5175 For example, a recipe with an EULA may set:: 5176 5177 LICENSE_FLAGS = "FooBar-EULA" 5178 LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula." 5179 5180 If ``Foobar-EULA`` isn't in :term:`LICENSE_FLAGS_ACCEPTED`, the 5181 error message is more useful:: 5182 5183 Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED. 5184 For further details, see https://example.com/eula. 5185 5186 :term:`LICENSE_PATH` 5187 Path to additional licenses used during the build. By default, the 5188 OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the 5189 directory that holds common license text used during the build. The 5190 :term:`LICENSE_PATH` variable allows you to extend that location to other 5191 areas that have additional licenses:: 5192 5193 LICENSE_PATH += "path-to-additional-common-licenses" 5194 5195 :term:`LINUX_KERNEL_TYPE` 5196 Defines the kernel type to be used in assembling the configuration. 5197 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 5198 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" 5199 section in the 5200 Yocto Project Linux Kernel Development Manual for more information on 5201 kernel types. 5202 5203 If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to 5204 "standard". Together with :term:`KMACHINE`, the 5205 :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by 5206 the kernel tools to find the appropriate description within the 5207 kernel :term:`Metadata` with which to build out the sources 5208 and configuration. 5209 5210 :term:`LINUX_VERSION` 5211 The Linux version from ``kernel.org`` on which the Linux kernel image 5212 being built using the OpenEmbedded build system is based. You define 5213 this variable in the kernel recipe. For example, the 5214 ``linux-yocto-3.4.bb`` kernel recipe found in 5215 ``meta/recipes-kernel/linux`` defines the variables as follows:: 5216 5217 LINUX_VERSION ?= "3.4.24" 5218 5219 The :term:`LINUX_VERSION` variable is used to define :term:`PV` 5220 for the recipe:: 5221 5222 PV = "${LINUX_VERSION}+git" 5223 5224 :term:`LINUX_VERSION_EXTENSION` 5225 A string extension compiled into the version string of the Linux 5226 kernel built with the OpenEmbedded build system. You define this 5227 variable in the kernel recipe. For example, the linux-yocto kernel 5228 recipes all define the variable as follows:: 5229 5230 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" 5231 5232 Defining this variable essentially sets the Linux kernel 5233 configuration item ``CONFIG_LOCALVERSION``, which is visible through 5234 the ``uname`` command. Here is an example that shows the extension 5235 assuming it was set as previously shown:: 5236 5237 $ uname -r 5238 3.7.0-rc8-custom 5239 5240 :term:`LOG_DIR` 5241 Specifies the directory to which the OpenEmbedded build system writes 5242 overall log files. The default directory is ``${TMPDIR}/log``. 5243 5244 For the directory containing logs specific to each task, see the 5245 :term:`T` variable. 5246 5247 :term:`MACHINE` 5248 Specifies the target device for which the image is built. You define 5249 :term:`MACHINE` in the ``local.conf`` file found in the 5250 :term:`Build Directory`. By default, :term:`MACHINE` is set to 5251 "qemux86", which is an x86-based architecture machine to be emulated 5252 using QEMU:: 5253 5254 MACHINE ?= "qemux86" 5255 5256 The variable corresponds to a machine configuration file of the same 5257 name, through which machine-specific configurations are set. Thus, 5258 when :term:`MACHINE` is set to "qemux86", the corresponding 5259 ``qemux86.conf`` machine configuration file can be found in 5260 the :term:`Source Directory` in 5261 ``meta/conf/machine``. 5262 5263 The list of machines supported by the Yocto Project as shipped 5264 include the following:: 5265 5266 MACHINE ?= "qemuarm" 5267 MACHINE ?= "qemuarm64" 5268 MACHINE ?= "qemumips" 5269 MACHINE ?= "qemumips64" 5270 MACHINE ?= "qemuppc" 5271 MACHINE ?= "qemux86" 5272 MACHINE ?= "qemux86-64" 5273 MACHINE ?= "genericx86" 5274 MACHINE ?= "genericx86-64" 5275 MACHINE ?= "beaglebone" 5276 5277 The last five are Yocto Project reference hardware 5278 boards, which are provided in the ``meta-yocto-bsp`` layer. 5279 5280 .. note:: 5281 5282 Adding additional Board Support Package (BSP) layers to your 5283 configuration adds new possible settings for :term:`MACHINE`. 5284 5285 :term:`MACHINE_ARCH` 5286 Specifies the name of the machine-specific architecture. This 5287 variable is set automatically from :term:`MACHINE` or 5288 :term:`TUNE_PKGARCH`. You should not hand-edit 5289 the :term:`MACHINE_ARCH` variable. 5290 5291 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 5292 A list of required machine-specific packages to install as part of 5293 the image being built. The build process depends on these packages 5294 being present. Furthermore, because this is a "machine-essential" 5295 variable, the list of packages are essential for the machine to boot. 5296 The impact of this variable affects images based on 5297 ``packagegroup-core-boot``, including the ``core-image-minimal`` 5298 image. 5299 5300 This variable is similar to the 5301 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception 5302 that the image being built has a build dependency on the variable's 5303 list of packages. In other words, the image will not build if a file 5304 in this list is not found. 5305 5306 As an example, suppose the machine for which you are building 5307 requires ``example-init`` to be run during boot to initialize the 5308 hardware. In this case, you would use the following in the machine's 5309 ``.conf`` configuration file:: 5310 5311 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" 5312 5313 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` 5314 A list of recommended machine-specific packages to install as part of 5315 the image being built. The build process does not depend on these 5316 packages being present. However, because this is a 5317 "machine-essential" variable, the list of packages are essential for 5318 the machine to boot. The impact of this variable affects images based 5319 on ``packagegroup-core-boot``, including the ``core-image-minimal`` 5320 image. 5321 5322 This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 5323 variable with the exception that the image being built does not have 5324 a build dependency on the variable's list of packages. In other 5325 words, the image will still build if a package in this list is not 5326 found. Typically, this variable is used to handle essential kernel 5327 modules, whose functionality may be selected to be built into the 5328 kernel rather than as a module, in which case a package will not be 5329 produced. 5330 5331 Consider an example where you have a custom kernel where a specific 5332 touchscreen driver is required for the machine to be usable. However, 5333 the driver can be built as a module or into the kernel depending on 5334 the kernel configuration. If the driver is built as a module, you 5335 want it to be installed. But, when the driver is built into the 5336 kernel, you still want the build to succeed. This variable sets up a 5337 "recommends" relationship so that in the latter case, the build will 5338 not fail due to the missing package. To accomplish this, assuming the 5339 package for the module was called ``kernel-module-ab123``, you would 5340 use the following in the machine's ``.conf`` configuration file:: 5341 5342 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" 5343 5344 .. note:: 5345 5346 In this example, the ``kernel-module-ab123`` recipe needs to 5347 explicitly set its :term:`PACKAGES` variable to ensure that BitBake 5348 does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to 5349 satisfy the dependency. 5350 5351 Some examples of these machine essentials are flash, screen, 5352 keyboard, mouse, or touchscreen drivers (depending on the machine). 5353 5354 :term:`MACHINE_EXTRA_RDEPENDS` 5355 A list of machine-specific packages to install as part of the image 5356 being built that are not essential for the machine to boot. However, 5357 the build process for more fully-featured images depends on the 5358 packages being present. 5359 5360 This variable affects all images based on ``packagegroup-base``, 5361 which does not include the ``core-image-minimal`` or 5362 ``core-image-full-cmdline`` images. 5363 5364 The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable 5365 with the exception that the image being built has a build dependency 5366 on the variable's list of packages. In other words, the image will 5367 not build if a file in this list is not found. 5368 5369 An example is a machine that has WiFi capability but is not essential 5370 for the machine to boot the image. However, if you are building a 5371 more fully-featured image, you want to enable the WiFi. The package 5372 containing the firmware for the WiFi hardware is always expected to 5373 exist, so it is acceptable for the build process to depend upon 5374 finding the package. In this case, assuming the package for the 5375 firmware was called ``wifidriver-firmware``, you would use the 5376 following in the ``.conf`` file for the machine:: 5377 5378 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" 5379 5380 :term:`MACHINE_EXTRA_RRECOMMENDS` 5381 A list of machine-specific packages to install as part of the image 5382 being built that are not essential for booting the machine. The image 5383 being built has no build dependency on this list of packages. 5384 5385 This variable affects only images based on ``packagegroup-base``, 5386 which does not include the ``core-image-minimal`` or 5387 ``core-image-full-cmdline`` images. 5388 5389 This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable 5390 with the exception that the image being built does not have a build 5391 dependency on the variable's list of packages. In other words, the 5392 image will build if a file in this list is not found. 5393 5394 An example is a machine that has WiFi capability but is not essential 5395 For the machine to boot the image. However, if you are building a 5396 more fully-featured image, you want to enable WiFi. In this case, the 5397 package containing the WiFi kernel module will not be produced if the 5398 WiFi driver is built into the kernel, in which case you still want 5399 the build to succeed instead of failing as a result of the package 5400 not being found. To accomplish this, assuming the package for the 5401 module was called ``kernel-module-examplewifi``, you would use the 5402 following in the ``.conf`` file for the machine:: 5403 5404 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" 5405 5406 :term:`MACHINE_FEATURES` 5407 Specifies the list of hardware features the 5408 :term:`MACHINE` is capable of supporting. For related 5409 information on enabling features, see the 5410 :term:`DISTRO_FEATURES`, 5411 :term:`COMBINED_FEATURES`, and 5412 :term:`IMAGE_FEATURES` variables. 5413 5414 For a list of hardware features supported by the Yocto Project as 5415 shipped, see the ":ref:`ref-features-machine`" section. 5416 5417 :term:`MACHINE_FEATURES_BACKFILL` 5418 A list of space-separated features to be added to 5419 :term:`MACHINE_FEATURES` if not also present in 5420 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. 5421 5422 This variable is set in the ``meta/conf/bitbake.conf`` file. It is not 5423 intended to be user-configurable. It is best to just reference the 5424 variable to see which machine features are being 5425 :ref:`backfilled <ref-features-backfill>` for all machine configurations. 5426 5427 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` 5428 A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL` 5429 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added 5430 to :term:`MACHINE_FEATURES`) during the build. 5431 5432 This corresponds to an opt-out mechanism. When new default machine 5433 features are introduced, machine definition maintainers can review 5434 (`consider`) them and decide to exclude them from the 5435 :ref:`backfilled <ref-features-backfill>` features. Therefore, the 5436 combination of :term:`MACHINE_FEATURES_BACKFILL` and 5437 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to 5438 add new default features without breaking existing machine definitions. 5439 5440 :term:`MACHINEOVERRIDES` 5441 A colon-separated list of overrides that apply to the current 5442 machine. By default, this list includes the value of 5443 :term:`MACHINE`. 5444 5445 You can extend :term:`MACHINEOVERRIDES` to add extra overrides that 5446 should apply to a machine. For example, all machines emulated in QEMU 5447 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named 5448 ``meta/conf/machine/include/qemu.inc`` that prepends the following 5449 override to :term:`MACHINEOVERRIDES`:: 5450 5451 MACHINEOVERRIDES =. "qemuall:" 5452 5453 This 5454 override allows variables to be overridden for all machines emulated 5455 in QEMU, like in the following example from the ``connman-conf`` 5456 recipe:: 5457 5458 SRC_URI:append:qemuall = " file://wired.config \ 5459 file://wired-setup \ 5460 " 5461 5462 The underlying mechanism behind 5463 :term:`MACHINEOVERRIDES` is simply that it is included in the default 5464 value of :term:`OVERRIDES`. 5465 5466 :term:`MAINTAINER` 5467 The email address of the distribution maintainer. 5468 5469 :term:`MESON_BUILDTYPE` 5470 Value of the Meson ``--buildtype`` argument used by the 5471 :ref:`ref-classes-meson` class. It defaults to ``debug`` if 5472 :term:`DEBUG_BUILD` is set to "1", and ``plain`` otherwise. 5473 5474 See `Meson build options <https://mesonbuild.com/Builtin-options.html>`__ 5475 for the values you could set in a recipe. Values such as ``plain``, 5476 ``debug``, ``debugoptimized``, ``release`` and ``minsize`` allow 5477 you to specify the inclusion of debugging symbols and the compiler 5478 optimizations (none, performance or size). 5479 5480 :term:`MESON_TARGET` 5481 A variable for the :ref:`ref-classes-meson` class, allowing to choose 5482 a Meson target to build in :ref:`ref-tasks-compile`. Otherwise, the 5483 default targets are built. 5484 5485 :term:`METADATA_BRANCH` 5486 The branch currently checked out for the OpenEmbedded-Core layer (path 5487 determined by :term:`COREBASE`). 5488 5489 :term:`METADATA_REVISION` 5490 The revision currently checked out for the OpenEmbedded-Core layer (path 5491 determined by :term:`COREBASE`). 5492 5493 :term:`MIME_XDG_PACKAGES` 5494 The current implementation of the :ref:`ref-classes-mime-xdg` 5495 class cannot detect ``.desktop`` files installed through absolute 5496 symbolic links. Use this setting to make the class create post-install 5497 and post-remove scripts for these packages anyway, to invoke the 5498 ``update-destop-database`` command. 5499 5500 :term:`MIRRORS` 5501 Specifies additional paths from which the OpenEmbedded build system 5502 gets source code. When the build system searches for source code, it 5503 first tries the local download directory. If that location fails, the 5504 build system tries locations defined by 5505 :term:`PREMIRRORS`, the upstream source, and then 5506 locations specified by :term:`MIRRORS` in that order. 5507 5508 The default value for :term:`MIRRORS` is defined in the 5509 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer. 5510 5511 :term:`MLPREFIX` 5512 Specifies a prefix has been added to :term:`PN` to create a 5513 special version of a recipe or package (i.e. a Multilib version). The 5514 variable is used in places where the prefix needs to be added to or 5515 removed from a name (e.g. the :term:`BPN` variable). 5516 :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`. 5517 5518 .. note:: 5519 5520 The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation 5521 is historical and comes from a time when ":ref:`ref-classes-nativesdk`" 5522 was a suffix rather than a prefix on the recipe name. When 5523 ":ref:`ref-classes-nativesdk`" was turned into a prefix, it made sense 5524 to set :term:`MLPREFIX` for it as well. 5525 5526 To help understand when :term:`MLPREFIX` might be needed, consider when 5527 :term:`BBCLASSEXTEND` is used to provide a :ref:`ref-classes-nativesdk` 5528 version of a recipe in addition to the target version. If that recipe 5529 declares build-time dependencies on tasks in other recipes by using 5530 :term:`DEPENDS`, then a dependency on "foo" will automatically get 5531 rewritten to a dependency on "nativesdk-foo". However, dependencies like 5532 the following will not get rewritten automatically:: 5533 5534 do_foo[depends] += "recipe:do_foo" 5535 5536 If you want such a dependency to also get transformed, you can do the 5537 following:: 5538 5539 do_foo[depends] += "${MLPREFIX}recipe:do_foo" 5540 5541 :term:`module_autoload` 5542 This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD` 5543 variable. You should replace all occurrences of :term:`module_autoload` 5544 with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example:: 5545 5546 module_autoload_rfcomm = "rfcomm" 5547 5548 should now be replaced with:: 5549 5550 KERNEL_MODULE_AUTOLOAD += "rfcomm" 5551 5552 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. 5553 5554 :term:`module_conf` 5555 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__ 5556 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` 5557 file. 5558 5559 You can use this variable anywhere that it can be recognized by the 5560 kernel recipe or out-of-tree kernel module recipe (e.g. a machine 5561 configuration file, a distribution configuration file, an append file 5562 for the recipe, or the recipe itself). If you use this variable, you 5563 must also be sure to list the module name in the 5564 :term:`KERNEL_MODULE_PROBECONF` 5565 variable. 5566 5567 Here is the general syntax:: 5568 5569 module_conf_module_name = "modprobe.d-syntax" 5570 5571 You must use the kernel module name override. 5572 5573 Run ``man modprobe.d`` in the shell to find out more information on 5574 the exact syntax you want to provide with :term:`module_conf`. 5575 5576 Including :term:`module_conf` causes the OpenEmbedded build system to 5577 populate the ``/etc/modprobe.d/modname.conf`` file with 5578 ``modprobe.d`` syntax lines. Here is an example that adds the options 5579 ``arg1`` and ``arg2`` to a module named ``mymodule``:: 5580 5581 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" 5582 5583 For information on how to specify kernel modules to auto-load on 5584 boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable. 5585 5586 :term:`MODULE_TARBALL_DEPLOY` 5587 Controls creation of the ``modules-*.tgz`` file. Set this variable to 5588 "0" to disable creation of this file, which contains all of the 5589 kernel modules resulting from a kernel build. 5590 5591 :term:`MODULE_TARBALL_LINK_NAME` 5592 The link name of the kernel module tarball. This variable is set in 5593 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 5594 5595 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 5596 5597 The value 5598 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the 5599 same file, has the following value:: 5600 5601 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 5602 5603 See the :term:`MACHINE` variable for additional information. 5604 5605 :term:`MODULE_TARBALL_NAME` 5606 The base name of the kernel module tarball. This variable is set in 5607 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 5608 5609 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" 5610 5611 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 5612 5613 :term:`MOUNT_BASE` 5614 On non-systemd systems (where ``udev-extraconf`` is being used), 5615 specifies the base directory for auto-mounting filesystems. The 5616 default value is "/run/media". 5617 5618 :term:`MULTIMACH_TARGET_SYS` 5619 Uniquely identifies the type of the target system for which packages 5620 are being built. This variable allows output for different types of 5621 target systems to be put into different subdirectories of the same 5622 output directory. 5623 5624 The default value of this variable is:: 5625 5626 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} 5627 5628 Some classes (e.g. :ref:`ref-classes-cross-canadian`) modify the 5629 :term:`MULTIMACH_TARGET_SYS` value. 5630 5631 See the :term:`STAMP` variable for an example. See the 5632 :term:`STAGING_DIR_TARGET` variable for more information. 5633 5634 :term:`NATIVELSBSTRING` 5635 A string identifying the host distribution. Strings consist of the 5636 host distributor ID followed by the release, as reported by the 5637 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For 5638 example, when running a build on Ubuntu 12.10, the value is 5639 "Ubuntu-12.10". If this information is unable to be determined, the 5640 value resolves to "Unknown". 5641 5642 This variable is used by default to isolate native shared state 5643 packages for different distributions (e.g. to avoid problems with 5644 ``glibc`` version incompatibilities). Additionally, the variable is 5645 checked against 5646 :term:`SANITY_TESTED_DISTROS` if that 5647 variable is set. 5648 5649 :term:`NM` 5650 The minimal command and arguments to run ``nm``. 5651 5652 :term:`NO_GENERIC_LICENSE` 5653 Avoids QA errors when you use a non-common, non-CLOSED license in a 5654 recipe. There are packages, such as the linux-firmware package, with many 5655 licenses that are not in any way common. Also, new licenses are added 5656 occasionally to avoid introducing a lot of common license files, 5657 which are only applicable to a specific package. 5658 :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does 5659 not exist in common licenses. 5660 5661 The following example shows how to add :term:`NO_GENERIC_LICENSE` to a 5662 recipe:: 5663 5664 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" 5665 5666 Here is an example that 5667 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched 5668 source:: 5669 5670 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" 5671 5672 :term:`NO_RECOMMENDATIONS` 5673 Prevents installation of all "recommended-only" packages. 5674 Recommended-only packages are packages installed only through the 5675 :term:`RRECOMMENDS` variable). Setting the 5676 :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on:: 5677 5678 NO_RECOMMENDATIONS = "1" 5679 5680 You can set this variable globally in your ``local.conf`` file or you 5681 can attach it to a specific image recipe by using the recipe name 5682 override:: 5683 5684 NO_RECOMMENDATIONS:pn-target_image = "1" 5685 5686 It is important to realize that if you choose to not install packages 5687 using this variable and some other packages are dependent on them 5688 (i.e. listed in a recipe's :term:`RDEPENDS` 5689 variable), the OpenEmbedded build system ignores your request and 5690 will install the packages to avoid dependency errors. 5691 5692 .. note:: 5693 5694 Some recommended packages might be required for certain system 5695 functionality, such as kernel modules. It is up to you to add 5696 packages with the :term:`IMAGE_INSTALL` variable. 5697 5698 This variable is only supported when using the IPK and RPM 5699 packaging backends. DEB is not supported. 5700 5701 See the :term:`BAD_RECOMMENDATIONS` and 5702 the :term:`PACKAGE_EXCLUDE` variables for 5703 related information. 5704 5705 :term:`NOAUTOPACKAGEDEBUG` 5706 Disables auto package from splitting ``.debug`` files. If a recipe 5707 requires ``FILES:${PN}-dbg`` to be set manually, the 5708 :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the 5709 content of the debug package. For example:: 5710 5711 NOAUTOPACKAGEDEBUG = "1" 5712 FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" 5713 FILES:${PN}-dbg = "/usr/src/debug/" 5714 FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" 5715 5716 :term:`NON_MULTILIB_RECIPES` 5717 A list of recipes that should not be built for multilib. OE-Core's 5718 ``multilib.conf`` file defines a reasonable starting point for this 5719 list with:: 5720 5721 NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot" 5722 5723 :term:`NVDCVE_API_KEY` 5724 The NVD API key used to retrieve data from the CVE database when 5725 using :ref:`ref-classes-cve-check`. 5726 5727 By default, no API key is used, which results in larger delays between API 5728 requests and limits the number of queries to the public rate limits posted 5729 at the `NVD developer's page <https://nvd.nist.gov/developers/start-here>`__. 5730 5731 NVD API keys can be requested through the 5732 `Request an API Key <https://nvd.nist.gov/developers/request-an-api-key>`__ 5733 page. You can set this variable to the NVD API key in your ``local.conf`` file. 5734 Example:: 5735 5736 NVDCVE_API_KEY = "fe753&7a2-1427-347d-23ff-b2e2b7ca5f3" 5737 5738 :term:`OBJCOPY` 5739 The minimal command and arguments to run ``objcopy``. 5740 5741 :term:`OBJDUMP` 5742 The minimal command and arguments to run ``objdump``. 5743 5744 :term:`OE_BINCONFIG_EXTRA_MANGLE` 5745 When inheriting the :ref:`ref-classes-binconfig` class, 5746 this variable specifies additional arguments passed to the "sed" 5747 command. The sed command alters any paths in configuration scripts 5748 that have been set up during compilation. Inheriting this class 5749 results in all paths in these scripts being changed to point into the 5750 ``sysroots/`` directory so that all builds that use the script will 5751 use the correct directories for the cross compiling layout. 5752 5753 See the ``meta/classes-recipe/binconfig.bbclass`` in the 5754 :term:`Source Directory` for details on how this class 5755 applies these additional sed command arguments. 5756 5757 :term:`OECMAKE_GENERATOR` 5758 A variable for the :ref:`ref-classes-cmake` class, allowing to choose 5759 which back-end will be generated by CMake to build an application. 5760 5761 By default, this variable is set to ``Ninja``, which is faster than GNU 5762 make, but if building is broken with Ninja, a recipe can use this 5763 variable to use GNU make instead:: 5764 5765 OECMAKE_GENERATOR = "Unix Makefiles" 5766 5767 :term:`OE_IMPORTS` 5768 An internal variable used to tell the OpenEmbedded build system what 5769 Python modules to import for every Python function run by the system. 5770 5771 .. note:: 5772 5773 Do not set this variable. It is for internal use only. 5774 5775 :term:`OE_INIT_ENV_SCRIPT` 5776 The name of the build environment setup script for the purposes of 5777 setting up the environment within the extensible SDK. The default 5778 value is "oe-init-build-env". 5779 5780 If you use a custom script to set up your build environment, set the 5781 :term:`OE_INIT_ENV_SCRIPT` variable to its name. 5782 5783 :term:`OE_TERMINAL` 5784 Controls how the OpenEmbedded build system spawns interactive 5785 terminals on the host development system (e.g. using the BitBake 5786 command with the ``-c devshell`` command-line option). For more 5787 information, see the ":ref:`dev-manual/development-shell:using a development shell`" section in 5788 the Yocto Project Development Tasks Manual. 5789 5790 You can use the following values for the :term:`OE_TERMINAL` variable: 5791 5792 - auto 5793 - gnome 5794 - xfce 5795 - rxvt 5796 - screen 5797 - konsole 5798 - none 5799 5800 :term:`OEROOT` 5801 The directory from which the top-level build environment setup script 5802 is sourced. The Yocto Project provides a top-level build environment 5803 setup script: :ref:`structure-core-script`. When you run this 5804 script, the :term:`OEROOT` variable resolves to the directory that 5805 contains the script. 5806 5807 For additional information on how this variable is used, see the 5808 initialization script. 5809 5810 :term:`OEQA_REPRODUCIBLE_TEST_PACKAGE` 5811 Set the package manager(s) for build reproducibility testing. 5812 See :yocto_git:`reproducible.py </poky/tree/meta/lib/oeqa/selftest/cases/reproducible.py>` 5813 and :doc:`/test-manual/reproducible-builds`. 5814 5815 :term:`OEQA_REPRODUCIBLE_TEST_TARGET` 5816 Set build target for build reproducibility testing. By default 5817 all available recipes are compiled with "bitbake world", see also :term:`EXCLUDE_FROM_WORLD` 5818 and :doc:`/test-manual/reproducible-builds`. 5819 5820 :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS` 5821 Set build targets which can be rebuilt using :ref:`shared state <overview-manual/concepts:shared state cache>` 5822 when running build reproducibility tests. See :doc:`/test-manual/reproducible-builds`. 5823 5824 :term:`OLDEST_KERNEL` 5825 Declares the oldest version of the Linux kernel that the produced 5826 binaries must support. This variable is passed into the build of the 5827 Embedded GNU C Library (``glibc``). 5828 5829 The default for this variable comes from the 5830 ``meta/conf/bitbake.conf`` configuration file. You can override this 5831 default by setting the variable in a custom distribution 5832 configuration file. 5833 5834 :term:`OPKG_MAKE_INDEX_EXTRA_PARAMS` 5835 Specifies extra parameters for the ``opkg-make-index`` command. 5836 5837 :term:`OPKGBUILDCMD` 5838 The variable :term:`OPKGBUILDCMD` specifies the command used to build opkg 5839 packages when using the :ref:`ref-classes-package_ipk` class. It is 5840 defined in :ref:`ref-classes-package_ipk` as:: 5841 5842 OPKGBUILDCMD ??= 'opkg-build -Z zstd -a "${ZSTD_DEFAULTS}"' 5843 5844 :term:`OVERLAYFS_ETC_DEVICE` 5845 When the :ref:`ref-classes-overlayfs-etc` class is 5846 inherited, specifies the device to be mounted for the read/write 5847 layer of ``/etc``. There is no default, so you must set this if you 5848 wish to enable :ref:`ref-classes-overlayfs-etc`, for 5849 example, assuming ``/dev/mmcblk0p2`` was the desired device:: 5850 5851 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2" 5852 5853 :term:`OVERLAYFS_ETC_EXPOSE_LOWER` 5854 When the :ref:`ref-classes-overlayfs-etc` class is 5855 inherited, if set to "1" then a read-only access to the original 5856 ``/etc`` content will be provided as a ``lower/`` subdirectory of 5857 :term:`OVERLAYFS_ETC_MOUNT_POINT`. The default value is "0". 5858 5859 :term:`OVERLAYFS_ETC_FSTYPE` 5860 When the :ref:`ref-classes-overlayfs-etc` class is 5861 inherited, specifies the file system type for the read/write 5862 layer of ``/etc``. There is no default, so you must set this if you 5863 wish to enable :ref:`ref-classes-overlayfs-etc`, 5864 for example, assuming the file system is ext4:: 5865 5866 OVERLAYFS_ETC_FSTYPE = "ext4" 5867 5868 :term:`OVERLAYFS_ETC_MOUNT_OPTIONS` 5869 When the :ref:`ref-classes-overlayfs-etc` class is 5870 inherited, specifies the mount options for the read-write layer. 5871 The default value is "defaults". 5872 5873 :term:`OVERLAYFS_ETC_MOUNT_POINT` 5874 When the :ref:`ref-classes-overlayfs-etc` class is 5875 inherited, specifies the parent mount path for the filesystem layers. 5876 There is no default, so you must set this if you wish to enable 5877 :ref:`ref-classes-overlayfs-etc`, for example if the desired path is 5878 "/data":: 5879 5880 OVERLAYFS_ETC_MOUNT_POINT = "/data" 5881 5882 :term:`OVERLAYFS_ETC_USE_ORIG_INIT_NAME` 5883 When the :ref:`ref-classes-overlayfs-etc` class is inherited, controls 5884 how the generated init will be named. For more information, see the 5885 :ref:`ref-classes-overlayfs-etc` class documentation. The default value 5886 is "1". 5887 5888 :term:`OVERLAYFS_MOUNT_POINT` 5889 When inheriting the :ref:`ref-classes-overlayfs` class, 5890 specifies mount point(s) to be used. For example:: 5891 5892 OVERLAYFS_MOUNT_POINT[data] = "/data" 5893 5894 The assumes you have a ``data.mount`` systemd unit defined elsewhere in 5895 your BSP (e.g. in ``systemd-machine-units`` recipe) and it is installed 5896 into the image. For more information see :ref:`ref-classes-overlayfs`. 5897 5898 .. note:: 5899 5900 Although the :ref:`ref-classes-overlayfs` class is 5901 inherited by individual recipes, :term:`OVERLAYFS_MOUNT_POINT` 5902 should be set in your machine configuration. 5903 5904 :term:`OVERLAYFS_QA_SKIP` 5905 When inheriting the :ref:`ref-classes-overlayfs` class, 5906 provides the ability to disable QA checks for particular overlayfs 5907 mounts. For example:: 5908 5909 OVERLAYFS_QA_SKIP[data] = "mount-configured" 5910 5911 .. note:: 5912 5913 Although the :ref:`ref-classes-overlayfs` class is 5914 inherited by individual recipes, :term:`OVERLAYFS_QA_SKIP` 5915 should be set in your machine configuration. 5916 5917 :term:`OVERLAYFS_WRITABLE_PATHS` 5918 When inheriting the :ref:`ref-classes-overlayfs` class, 5919 specifies writable paths used at runtime for the recipe. For 5920 example:: 5921 5922 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" 5923 5924 :term:`OVERRIDES` 5925 A colon-separated list of overrides that currently apply. Overrides 5926 are a BitBake mechanism that allows variables to be selectively 5927 overridden at the end of parsing. The set of overrides in 5928 :term:`OVERRIDES` represents the "state" during building, which includes 5929 the current recipe being built, the machine for which it is being 5930 built, and so forth. 5931 5932 As an example, if the string "an-override" appears as an element in 5933 the colon-separated list in :term:`OVERRIDES`, then the following 5934 assignment will override ``FOO`` with the value "overridden" at the 5935 end of parsing:: 5936 5937 FOO:an-override = "overridden" 5938 5939 See the 5940 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 5941 section in the BitBake User Manual for more information on the 5942 overrides mechanism. 5943 5944 The default value of :term:`OVERRIDES` includes the values of the 5945 :term:`CLASSOVERRIDE`, 5946 :term:`MACHINEOVERRIDES`, and 5947 :term:`DISTROOVERRIDES` variables. Another 5948 important override included by default is ``pn-${PN}``. This override 5949 allows variables to be set for a single recipe within configuration 5950 (``.conf``) files. Here is an example:: 5951 5952 FOO:pn-myrecipe = "myrecipe-specific value" 5953 5954 .. note:: 5955 5956 An easy way to see what overrides apply is to search for :term:`OVERRIDES` 5957 in the output of the ``bitbake -e`` command. See the 5958 ":ref:`dev-manual/debugging:viewing variable values`" section in the Yocto 5959 Project Development Tasks Manual for more information. 5960 5961 :term:`P` 5962 The recipe name and version. :term:`P` is comprised of the following:: 5963 5964 ${PN}-${PV} 5965 5966 :term:`P4DIR` 5967 See :term:`bitbake:P4DIR` in the BitBake manual. 5968 5969 :term:`PACKAGE_ADD_METADATA` 5970 This variable defines additional metadata to add to packages. 5971 5972 You may find you need to inject additional metadata into packages. 5973 This variable allows you to do that by setting the injected data as 5974 the value. Multiple fields can be added by splitting the content with 5975 the literal separator "\n". 5976 5977 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable 5978 to do package type specific settings. It can also be made package 5979 specific by using the package name as a suffix. 5980 5981 You can find out more about applying this variable in the 5982 ":ref:`dev-manual/packages:adding custom metadata to packages`" 5983 section in the Yocto Project Development Tasks Manual. 5984 5985 :term:`PACKAGE_ARCH` 5986 The architecture of the resulting package or packages. 5987 5988 By default, the value of this variable is set to 5989 :term:`TUNE_PKGARCH` when building for the 5990 target, :term:`BUILD_ARCH` when building for the 5991 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the 5992 SDK. 5993 5994 .. note:: 5995 5996 See :term:`SDK_ARCH` for more information. 5997 5998 However, if your recipe's output packages are built specific to the 5999 target machine rather than generally for the architecture of the 6000 machine, you should set :term:`PACKAGE_ARCH` to the value of 6001 :term:`MACHINE_ARCH` in the recipe as follows:: 6002 6003 PACKAGE_ARCH = "${MACHINE_ARCH}" 6004 6005 :term:`PACKAGE_ARCHS` 6006 Specifies a list of architectures compatible with the target machine. 6007 This variable is set automatically and should not normally be 6008 hand-edited. Entries are separated using spaces and listed in order 6009 of priority. The default value for :term:`PACKAGE_ARCHS` is "all any 6010 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". 6011 6012 :term:`PACKAGE_BEFORE_PN` 6013 Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so 6014 that those added packages can pick up files that would normally be 6015 included in the default package. 6016 6017 :term:`PACKAGE_CLASSES` 6018 This variable, which is set in the ``local.conf`` configuration file 6019 found in the ``conf`` folder of the 6020 :term:`Build Directory`, specifies the package manager the 6021 OpenEmbedded build system uses when packaging data. 6022 6023 You can provide one or more of the following arguments for the 6024 variable:: 6025 6026 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" 6027 6028 The build system uses only the first argument in the list as the 6029 package manager when creating your image or SDK. However, packages 6030 will be created using any additional packaging classes you specify. 6031 For example, if you use the following in your ``local.conf`` file:: 6032 6033 PACKAGE_CLASSES ?= "package_ipk" 6034 6035 The OpenEmbedded build system uses 6036 the IPK package manager to create your image or SDK. 6037 6038 For information on packaging and build performance effects as a 6039 result of the package manager in use, see the 6040 ":ref:`ref-classes-package`" section. 6041 6042 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 6043 Determines how to split up and package debug and source information 6044 when creating debugging packages to be used with the GNU Project 6045 Debugger (GDB). In general, based on the value of this variable, 6046 you can combine the source and debug info in a single package, 6047 you can break out the source into a separate package that can be 6048 installed independently, or you can choose to not have the source 6049 packaged at all. 6050 6051 The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable: 6052 6053 - "``.debug``": All debugging and source info is placed in a single 6054 ``*-dbg`` package; debug symbol files are placed next to the 6055 binary in a ``.debug`` directory so that, if a binary is installed 6056 into ``/bin``, the corresponding debug symbol file is installed 6057 in ``/bin/.debug``. Source files are installed in the same ``*-dbg`` 6058 package under ``/usr/src/debug``. 6059 6060 - "``debug-file-directory``": As above, all debugging and source info 6061 is placed in a single ``*-dbg`` package; debug symbol files are 6062 placed entirely under the directory ``/usr/lib/debug`` and separated 6063 by the path from where the binary is installed, so that if a binary 6064 is installed in ``/bin``, the corresponding debug symbols are installed 6065 in ``/usr/lib/debug/bin``, and so on. As above, source is installed 6066 in the same package under ``/usr/src/debug``. 6067 6068 - "``debug-with-srcpkg``": Debugging info is placed in the standard 6069 ``*-dbg`` package as with the ``.debug`` value, while source is 6070 placed in a separate ``*-src`` package, which can be installed 6071 independently. This is the default setting for this variable, 6072 as defined in Poky's ``bitbake.conf`` file. 6073 6074 - "``debug-without-src``": The same behavior as with the ``.debug`` 6075 setting, but no source is packaged at all. 6076 6077 .. note:: 6078 6079 Much of the above package splitting can be overridden via 6080 use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable. 6081 6082 You can find out more about debugging using GDB by reading the 6083 ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section 6084 in the Yocto Project Development Tasks Manual. 6085 6086 :term:`PACKAGE_EXCLUDE` 6087 Lists packages that should not be installed into an image. For 6088 example:: 6089 6090 PACKAGE_EXCLUDE = "package_name package_name package_name ..." 6091 6092 You can set this variable globally in your ``local.conf`` file or you 6093 can attach it to a specific image recipe by using the recipe name 6094 override:: 6095 6096 PACKAGE_EXCLUDE:pn-target_image = "package_name" 6097 6098 If you choose to not install a package using this variable and some 6099 other package is dependent on it (i.e. listed in a recipe's 6100 :term:`RDEPENDS` variable), the OpenEmbedded build 6101 system generates a fatal installation error. Because the build system 6102 halts the process with a fatal error, you can use the variable with 6103 an iterative development process to remove specific components from a 6104 system. 6105 6106 This variable is supported only when using the IPK and RPM 6107 packaging backends. DEB is not supported. 6108 6109 See the :term:`NO_RECOMMENDATIONS` and the 6110 :term:`BAD_RECOMMENDATIONS` variables for 6111 related information. 6112 6113 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` 6114 Prevents specific packages from being installed when you are 6115 installing complementary packages. 6116 6117 You might find that you want to prevent installing certain packages 6118 when you are installing complementary packages. For example, if you 6119 are using :term:`IMAGE_FEATURES` to install 6120 ``dev-pkgs``, you might not want to install all packages from a 6121 particular multilib. If you find yourself in this situation, you can 6122 use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular 6123 expressions to match the packages you want to exclude. 6124 6125 :term:`PACKAGE_EXTRA_ARCHS` 6126 Specifies the list of architectures compatible with the device CPU. 6127 This variable is useful when you build for several different devices 6128 that use miscellaneous processors such as XScale and ARM926-EJS. 6129 6130 :term:`PACKAGE_FEED_ARCHS` 6131 Optionally specifies the package architectures used as part of the 6132 package feed URIs during the build. When used, the 6133 :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed 6134 URI, which is constructed using the 6135 :term:`PACKAGE_FEED_URIS` and 6136 :term:`PACKAGE_FEED_BASE_PATHS` 6137 variables. 6138 6139 .. note:: 6140 6141 You can use the :term:`PACKAGE_FEED_ARCHS` 6142 variable to allow specific package architectures. If you do 6143 not need to allow specific architectures, which is a common 6144 case, you can omit this variable. Omitting the variable results in 6145 all available architectures for the current machine being included 6146 into remote package feeds. 6147 6148 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 6149 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 6150 defined in your ``local.conf`` file:: 6151 6152 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6153 https://example.com/packagerepos/updates" 6154 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 6155 PACKAGE_FEED_ARCHS = "all core2-64" 6156 6157 Given these settings, the resulting package feeds are as follows: 6158 6159 .. code-block:: none 6160 6161 https://example.com/packagerepos/release/rpm/all 6162 https://example.com/packagerepos/release/rpm/core2-64 6163 https://example.com/packagerepos/release/rpm-dev/all 6164 https://example.com/packagerepos/release/rpm-dev/core2-64 6165 https://example.com/packagerepos/updates/rpm/all 6166 https://example.com/packagerepos/updates/rpm/core2-64 6167 https://example.com/packagerepos/updates/rpm-dev/all 6168 https://example.com/packagerepos/updates/rpm-dev/core2-64 6169 6170 :term:`PACKAGE_FEED_BASE_PATHS` 6171 Specifies the base path used when constructing package feed URIs. The 6172 :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a 6173 package feed URI used by the OpenEmbedded build system. The base path 6174 lies between the :term:`PACKAGE_FEED_URIS` 6175 and :term:`PACKAGE_FEED_ARCHS` variables. 6176 6177 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 6178 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 6179 defined in your ``local.conf`` file:: 6180 6181 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6182 https://example.com/packagerepos/updates" 6183 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 6184 PACKAGE_FEED_ARCHS = "all core2-64" 6185 6186 Given these settings, the resulting package feeds are as follows: 6187 6188 .. code-block:: none 6189 6190 https://example.com/packagerepos/release/rpm/all 6191 https://example.com/packagerepos/release/rpm/core2-64 6192 https://example.com/packagerepos/release/rpm-dev/all 6193 https://example.com/packagerepos/release/rpm-dev/core2-64 6194 https://example.com/packagerepos/updates/rpm/all 6195 https://example.com/packagerepos/updates/rpm/core2-64 6196 https://example.com/packagerepos/updates/rpm-dev/all 6197 https://example.com/packagerepos/updates/rpm-dev/core2-64 6198 6199 :term:`PACKAGE_FEED_URIS` 6200 Specifies the front portion of the package feed URI used by the 6201 OpenEmbedded build system. Each final package feed URI is comprised 6202 of :term:`PACKAGE_FEED_URIS`, 6203 :term:`PACKAGE_FEED_BASE_PATHS`, and 6204 :term:`PACKAGE_FEED_ARCHS` variables. 6205 6206 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 6207 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 6208 defined in your ``local.conf`` file:: 6209 6210 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6211 https://example.com/packagerepos/updates" 6212 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 6213 PACKAGE_FEED_ARCHS = "all core2-64" 6214 6215 Given these settings, the resulting package feeds are as follows: 6216 6217 .. code-block:: none 6218 6219 https://example.com/packagerepos/release/rpm/all 6220 https://example.com/packagerepos/release/rpm/core2-64 6221 https://example.com/packagerepos/release/rpm-dev/all 6222 https://example.com/packagerepos/release/rpm-dev/core2-64 6223 https://example.com/packagerepos/updates/rpm/all 6224 https://example.com/packagerepos/updates/rpm/core2-64 6225 https://example.com/packagerepos/updates/rpm-dev/all 6226 https://example.com/packagerepos/updates/rpm-dev/core2-64 6227 6228 :term:`PACKAGE_INSTALL` 6229 The final list of packages passed to the package manager for 6230 installation into the image. 6231 6232 Because the package manager controls actual installation of all 6233 packages, the list of packages passed using :term:`PACKAGE_INSTALL` is 6234 not the final list of packages that are actually installed. This 6235 variable is internal to the image construction code. Consequently, in 6236 general, you should use the 6237 :term:`IMAGE_INSTALL` variable to specify 6238 packages for installation. The exception to this is when working with 6239 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 6240 image. When working with an initial RAM filesystem (:term:`Initramfs`) image, 6241 use the :term:`PACKAGE_INSTALL` variable. For information on creating an 6242 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 6243 in the Yocto Project Development Tasks Manual. 6244 6245 :term:`PACKAGE_INSTALL_ATTEMPTONLY` 6246 Specifies a list of packages the OpenEmbedded build system attempts 6247 to install when creating an image. If a listed package fails to 6248 install, the build system does not generate an error. This variable 6249 is generally not user-defined. 6250 6251 :term:`PACKAGE_PREPROCESS_FUNCS` 6252 Specifies a list of functions run to pre-process the 6253 :term:`PKGD` directory prior to splitting the files out 6254 to individual packages. 6255 6256 :term:`PACKAGE_WRITE_DEPS` 6257 Specifies a list of dependencies for post-installation and 6258 pre-installation scripts on native/cross tools. If your 6259 post-installation or pre-installation script can execute at root filesystem 6260 creation time rather than on the target but depends on a native tool 6261 in order to execute, you need to list the tools in 6262 :term:`PACKAGE_WRITE_DEPS`. 6263 6264 For information on running post-installation scripts, see the 6265 ":ref:`dev-manual/new-recipe:post-installation scripts`" 6266 section in the Yocto Project Development Tasks Manual. 6267 6268 :term:`PACKAGECONFIG` 6269 This variable provides a means of enabling or disabling features of a 6270 recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in 6271 recipes when you specify features and then arguments that define 6272 feature behaviors. Here is the basic block structure (broken over 6273 multiple lines for readability):: 6274 6275 PACKAGECONFIG ??= "f1 f2 f3 ..." 6276 PACKAGECONFIG[f1] = "\ 6277 --with-f1, \ 6278 --without-f1, \ 6279 build-deps-for-f1, \ 6280 runtime-deps-for-f1, \ 6281 runtime-recommends-for-f1, \ 6282 packageconfig-conflicts-for-f1" 6283 PACKAGECONFIG[f2] = "\ 6284 ... and so on and so on ... 6285 6286 The :term:`PACKAGECONFIG` variable itself specifies a space-separated 6287 list of the features to enable. Following the features, you can 6288 determine the behavior of each feature by providing up to six 6289 order-dependent arguments, which are separated by commas. You can 6290 omit any argument you like but must retain the separating commas. The 6291 order is important and specifies the following: 6292 6293 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS` 6294 if the feature is enabled. 6295 6296 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS` 6297 if the feature is disabled. 6298 6299 #. Additional build dependencies (:term:`DEPENDS`) 6300 that should be added if the feature is enabled. 6301 6302 #. Additional runtime dependencies (:term:`RDEPENDS`) 6303 that should be added if the feature is enabled. 6304 6305 #. Additional runtime recommendations 6306 (:term:`RRECOMMENDS`) that should be added if 6307 the feature is enabled. 6308 6309 #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG` 6310 settings for this feature. 6311 6312 Consider the following :term:`PACKAGECONFIG` block taken from the 6313 ``librsvg`` recipe. In this example the feature is ``gtk``, which has 6314 three arguments that determine the feature's behavior:: 6315 6316 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" 6317 6318 The 6319 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is 6320 enabled. In this case, ``--with-gtk3`` is added to the configure 6321 script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the 6322 other hand, if the feature is disabled say through a ``.bbappend`` 6323 file in another layer, then the second argument ``--without-gtk3`` is 6324 added to the configure script instead. 6325 6326 The basic :term:`PACKAGECONFIG` structure previously described holds true 6327 regardless of whether you are creating a block or changing a block. 6328 When creating a block, use the structure inside your recipe. 6329 6330 If you want to change an existing :term:`PACKAGECONFIG` block, you can do 6331 so one of two ways: 6332 6333 - *Append file:* Create an append file named 6334 ``recipename.bbappend`` in your layer and override the value of 6335 :term:`PACKAGECONFIG`. You can either completely override the 6336 variable:: 6337 6338 PACKAGECONFIG = "f4 f5" 6339 6340 Or, you can just append the variable:: 6341 6342 PACKAGECONFIG:append = " f4" 6343 6344 - *Configuration file:* This method is identical to changing the 6345 block through an append file except you edit your ``local.conf`` 6346 or ``mydistro.conf`` file. As with append files previously 6347 described, you can either completely override the variable:: 6348 6349 PACKAGECONFIG:pn-recipename = "f4 f5" 6350 6351 Or, you can just amend the variable:: 6352 6353 PACKAGECONFIG:append:pn-recipename = " f4" 6354 6355 Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service 6356 in which :term:`PACKAGECONFIG` is used to transform the systemd service 6357 into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`:: 6358 6359 example.c 6360 example.service 6361 CMakeLists.txt 6362 6363 The ``CMakeLists.txt`` file contains:: 6364 6365 if(WITH_SYSTEMD) 6366 install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd) 6367 endif(WITH_SYSTEMD) 6368 6369 In order to enable the installation of ``example.service`` we need to 6370 ensure that ``-DWITH_SYSTEMD=ON`` is passed to the ``cmake`` command 6371 execution. Recipes that have ``CMakeLists.txt`` generally inherit the 6372 :ref:`ref-classes-cmake` class, that runs ``cmake`` with 6373 :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be 6374 appended to. Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is 6375 automatically filled with either the first or second element of 6376 :term:`PACKAGECONFIG` flag value, the recipe would be like:: 6377 6378 inherit cmake 6379 PACKAGECONFIG = "systemd" 6380 PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF" 6381 6382 A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER` 6383 or not:: 6384 6385 PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}" 6386 6387 :term:`PACKAGECONFIG_CONFARGS` 6388 A space-separated list of configuration options generated from the 6389 :term:`PACKAGECONFIG` setting. 6390 6391 Classes such as :ref:`ref-classes-autotools` and :ref:`ref-classes-cmake` 6392 use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options 6393 to ``configure`` and ``cmake``, respectively. If you are using 6394 :term:`PACKAGECONFIG` but not a class that handles the 6395 :ref:`ref-tasks-configure` task, then you need to use 6396 :term:`PACKAGECONFIG_CONFARGS` appropriately. 6397 6398 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` 6399 For recipes inheriting the :ref:`ref-classes-packagegroup` class, setting 6400 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the 6401 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) 6402 should not be automatically created by the ``packagegroup`` recipe, 6403 which is the default behavior. 6404 6405 :term:`PACKAGES` 6406 The list of packages the recipe creates. The default value is the 6407 following:: 6408 6409 ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} 6410 6411 During packaging, the :ref:`ref-tasks-package` task 6412 goes through :term:`PACKAGES` and uses the :term:`FILES` 6413 variable corresponding to each package to assign files to the 6414 package. If a file matches the :term:`FILES` variable for more than one 6415 package in :term:`PACKAGES`, it will be assigned to the earliest 6416 (leftmost) package. 6417 6418 Packages in the variable's list that are empty (i.e. where none of 6419 the patterns in ``FILES:``\ pkg match any files installed by the 6420 :ref:`ref-tasks-install` task) are not generated, 6421 unless generation is forced through the 6422 :term:`ALLOW_EMPTY` variable. 6423 6424 :term:`PACKAGES_DYNAMIC` 6425 A promise that your recipe satisfies runtime dependencies for 6426 optional modules that are found in other recipes. 6427 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it 6428 only states that they should be satisfied. For example, if a hard, 6429 runtime dependency (:term:`RDEPENDS`) of another 6430 package is satisfied at build time through the :term:`PACKAGES_DYNAMIC` 6431 variable, but a package with the module name is never actually 6432 produced, then the other package will be broken. Thus, if you attempt 6433 to include that package in an image, you will get a dependency 6434 failure from the packaging system during the 6435 :ref:`ref-tasks-rootfs` task. 6436 6437 Typically, if there is a chance that such a situation can occur and 6438 the package that is not created is valid without the dependency being 6439 satisfied, then you should use :term:`RRECOMMENDS` 6440 (a soft runtime dependency) instead of :term:`RDEPENDS`. 6441 6442 For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when 6443 you are splitting packages, see the 6444 ":ref:`dev-manual/packages:handling optional module packaging`" 6445 section in the Yocto Project Development Tasks Manual. 6446 6447 :term:`PACKAGESPLITFUNCS` 6448 Specifies a list of functions run to perform additional splitting of 6449 files into individual packages. Recipes can either prepend to this 6450 variable or prepend to the ``populate_packages`` function in order to 6451 perform additional package splitting. In either case, the function 6452 should set :term:`PACKAGES`, 6453 :term:`FILES`, :term:`RDEPENDS` and 6454 other packaging variables appropriately in order to perform the 6455 desired splitting. 6456 6457 :term:`PARALLEL_MAKE` 6458 6459 Extra options passed to the build tool command (``make``, 6460 ``ninja`` or more specific build engines, like the Go language one) 6461 during the :ref:`ref-tasks-compile` task, to specify parallel compilation 6462 on the local build host. This variable is usually in the form "-j x", 6463 where x represents the maximum number of parallel threads such engines 6464 can run. 6465 6466 .. note:: 6467 6468 For software compiled by ``make``, in order for :term:`PARALLEL_MAKE` 6469 to be effective, ``make`` must be called with 6470 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 6471 way to ensure this is to use the ``oe_runmake`` function. 6472 6473 By default, the OpenEmbedded build system automatically sets this 6474 variable to be equal to the number of cores the build system uses. 6475 6476 .. note:: 6477 6478 If the software being built experiences dependency issues during 6479 the :ref:`ref-tasks-compile` task that result in race conditions, you can clear 6480 the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For 6481 information on addressing race conditions, see the 6482 ":ref:`dev-manual/debugging:debugging parallel make races`" 6483 section in the Yocto Project Development Tasks Manual. 6484 6485 For single socket systems (i.e. one CPU), you should not have to 6486 override this variable to gain optimal parallelism during builds. 6487 However, if you have very large systems that employ multiple physical 6488 CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is 6489 not set higher than "-j 20". 6490 6491 For more information on speeding up builds, see the 6492 ":ref:`dev-manual/speeding-up-build:speeding up a build`" 6493 section in the Yocto Project Development Tasks Manual. 6494 6495 :term:`PARALLEL_MAKEINST` 6496 Extra options passed to the build tool install command 6497 (``make install``, ``ninja install`` or more specific ones) 6498 during the :ref:`ref-tasks-install` task in order to specify 6499 parallel installation. This variable defaults to the value of 6500 :term:`PARALLEL_MAKE`. 6501 6502 .. note:: 6503 6504 For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST` 6505 to be effective, ``make`` must be called with 6506 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 6507 way to ensure this is to use the ``oe_runmake`` function. 6508 6509 If the software being built experiences dependency issues during 6510 the :ref:`ref-tasks-install` task that result in race conditions, you can 6511 clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a 6512 workaround. For information on addressing race conditions, see the 6513 ":ref:`dev-manual/debugging:debugging parallel make races`" 6514 section in the Yocto Project Development Tasks Manual. 6515 6516 :term:`PATCHRESOLVE` 6517 Determines the action to take when a patch fails. You can set this 6518 variable to one of two values: "noop" and "user". 6519 6520 The default value of "noop" causes the build to simply fail when the 6521 OpenEmbedded build system cannot successfully apply a patch. Setting 6522 the value to "user" causes the build system to launch a shell and 6523 places you in the right location so that you can manually resolve the 6524 conflicts. 6525 6526 Set this variable in your ``local.conf`` file. 6527 6528 :term:`PATCHTOOL` 6529 Specifies the utility used to apply patches for a recipe during the 6530 :ref:`ref-tasks-patch` task. You can specify one of 6531 three utilities: "patch", "quilt", or "git". The default utility used 6532 is "quilt" except for the quilt-native recipe itself. Because the 6533 quilt tool is not available at the time quilt-native is being 6534 patched, it uses "patch". 6535 6536 If you wish to use an alternative patching tool, set the variable in 6537 the recipe using one of the following:: 6538 6539 PATCHTOOL = "patch" 6540 PATCHTOOL = "quilt" 6541 PATCHTOOL = "git" 6542 6543 :term:`PE` 6544 The epoch of the recipe. By default, this variable is unset. The 6545 variable is used to make upgrades possible when the versioning scheme 6546 changes in some backwards incompatible way. 6547 6548 :term:`PE` is the default value of the :term:`PKGE` variable. 6549 6550 :term:`PEP517_WHEEL_PATH` 6551 When used by recipes that inherit the :ref:`ref-classes-python_pep517` 6552 class, denotes the path to ``dist/`` (short for distribution) where the 6553 binary archive ``wheel`` is built. 6554 6555 :term:`PERSISTENT_DIR` 6556 See :term:`bitbake:PERSISTENT_DIR` in the BitBake manual. 6557 6558 :term:`PF` 6559 Specifies the recipe or package name and includes all version and 6560 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and 6561 ``bash-4.2-r1/``). This variable is comprised of the following: 6562 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} 6563 6564 :term:`PIXBUF_PACKAGES` 6565 When inheriting the :ref:`ref-classes-pixbufcache` 6566 class, this variable identifies packages that contain the pixbuf 6567 loaders used with ``gdk-pixbuf``. By default, the 6568 :ref:`ref-classes-pixbufcache` class assumes that 6569 the loaders are in the recipe's main package (i.e. 6570 ``${``\ :term:`PN`\ ``}``). Use this variable if the 6571 loaders you need are in a package other than that main package. 6572 6573 :term:`PKG` 6574 The name of the resulting package created by the OpenEmbedded build 6575 system. 6576 6577 .. note:: 6578 6579 When using the :term:`PKG` variable, you must use a package name override. 6580 6581 For example, when the :ref:`ref-classes-debian` class renames the output 6582 package, it does so by setting ``PKG:packagename``. 6583 6584 :term:`PKG_CONFIG_PATH` 6585 The path to ``pkg-config`` files for the current build context. 6586 ``pkg-config`` reads this variable from the environment. 6587 6588 :term:`PKGD` 6589 Points to the destination directory for files to be packaged before 6590 they are split into individual packages. This directory defaults to 6591 the following:: 6592 6593 ${WORKDIR}/package 6594 6595 Do not change this default. 6596 6597 :term:`PKGDATA_DIR` 6598 Points to a shared, global-state directory that holds data generated 6599 during the packaging process. During the packaging process, the 6600 :ref:`ref-tasks-packagedata` task packages data 6601 for each recipe and installs it into this temporary, shared area. 6602 This directory defaults to the following, which you should not 6603 change:: 6604 6605 ${STAGING_DIR_HOST}/pkgdata 6606 6607 For examples of how this data is used, see the 6608 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6609 section in the Yocto Project Overview and Concepts Manual and the 6610 ":ref:`dev-manual/debugging:viewing package information with \`\`oe-pkgdata-util\`\``" 6611 section in the Yocto Project Development Tasks Manual. For more 6612 information on the shared, global-state directory, see 6613 :term:`STAGING_DIR_HOST`. 6614 6615 :term:`PKGDEST` 6616 Points to the parent directory for files to be packaged after they 6617 have been split into individual packages. This directory defaults to 6618 the following:: 6619 6620 ${WORKDIR}/packages-split 6621 6622 Under this directory, the build system creates directories for each 6623 package specified in :term:`PACKAGES`. Do not change 6624 this default. 6625 6626 :term:`PKGDESTWORK` 6627 Points to a temporary work area where the 6628 :ref:`ref-tasks-package` task saves package metadata. 6629 The :term:`PKGDESTWORK` location defaults to the following:: 6630 6631 ${WORKDIR}/pkgdata 6632 6633 Do not change this default. 6634 6635 The :ref:`ref-tasks-packagedata` task copies the 6636 package metadata from :term:`PKGDESTWORK` to 6637 :term:`PKGDATA_DIR` to make it available globally. 6638 6639 :term:`PKGE` 6640 The epoch of the package(s) built by the recipe. By default, :term:`PKGE` 6641 is set to :term:`PE`. 6642 6643 :term:`PKGR` 6644 The revision of the package(s) built by the recipe. By default, 6645 :term:`PKGR` is set to :term:`PR`. 6646 6647 :term:`PKGV` 6648 The version of the package(s) built by the recipe. By default, 6649 :term:`PKGV` is set to :term:`PV`. 6650 6651 :term:`PN` 6652 This variable can have two separate functions depending on the 6653 context: a recipe name or a resulting package name. 6654 6655 :term:`PN` refers to a recipe name in the context of a file used by the 6656 OpenEmbedded build system as input to create a package. The name is 6657 normally extracted from the recipe file name. For example, if the 6658 recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN` 6659 will be "expat". 6660 6661 The variable refers to a package name in the context of a file 6662 created or produced by the OpenEmbedded build system. 6663 6664 If applicable, the :term:`PN` variable also contains any special suffix 6665 or prefix. For example, using ``bash`` to build packages for the 6666 native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build 6667 packages for the target and for Multilib, :term:`PN` would be ``bash`` 6668 and ``lib64-bash``, respectively. 6669 6670 :term:`POPULATE_SDK_POST_HOST_COMMAND` 6671 Specifies a list of functions to call once the OpenEmbedded build 6672 system has created the host part of the SDK. You can specify 6673 functions separated by spaces:: 6674 6675 POPULATE_SDK_POST_HOST_COMMAND += "function" 6676 6677 If you need to pass the SDK path to a command within a function, you 6678 can use ``${SDK_DIR}``, which points to the parent directory used by 6679 the OpenEmbedded build system when creating SDK output. See the 6680 :term:`SDK_DIR` variable for more information. 6681 6682 :term:`POPULATE_SDK_POST_TARGET_COMMAND` 6683 Specifies a list of functions to call once the OpenEmbedded build 6684 system has created the target part of the SDK. You can specify 6685 functions separated by spaces:: 6686 6687 POPULATE_SDK_POST_TARGET_COMMAND += "function" 6688 6689 If you need to pass the SDK path to a command within a function, you 6690 can use ``${SDK_DIR}``, which points to the parent directory used by 6691 the OpenEmbedded build system when creating SDK output. See the 6692 :term:`SDK_DIR` variable for more information. 6693 6694 :term:`PR` 6695 The revision of the recipe. The default value for this variable is 6696 "r0". Subsequent revisions of the recipe conventionally have the 6697 values "r1", "r2", and so forth. When :term:`PV` increases, 6698 :term:`PR` is conventionally reset to "r0". 6699 6700 .. note:: 6701 6702 The OpenEmbedded build system does not need the aid of :term:`PR` 6703 to know when to rebuild a recipe. The build system uses the task 6704 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the 6705 :ref:`stamp <structure-build-tmp-stamps>` and 6706 :ref:`overview-manual/concepts:shared state cache` 6707 mechanisms. 6708 6709 The :term:`PR` variable primarily becomes significant when a package 6710 manager dynamically installs packages on an already built image. In 6711 this case, :term:`PR`, which is the default value of 6712 :term:`PKGR`, helps the package manager distinguish which 6713 package is the most recent one in cases where many packages have the 6714 same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with 6715 the same :term:`PV` usually means that the packages all install the same 6716 upstream version, but with later (:term:`PR`) version packages including 6717 packaging fixes. 6718 6719 .. note:: 6720 6721 :term:`PR` does not need to be increased for changes that do not change the 6722 package contents or metadata. 6723 6724 Because manually managing :term:`PR` can be cumbersome and error-prone, 6725 an automated solution exists. See the 6726 ":ref:`dev-manual/packages:working with a pr service`" section 6727 in the Yocto Project Development Tasks Manual for more information. 6728 6729 :term:`PREFERRED_PROVIDER` 6730 If multiple recipes provide the same item, this variable determines 6731 which recipe is preferred and thus provides the item (i.e. the 6732 preferred provider). You should always suffix this variable with the 6733 name of the provided item. And, you should define the variable using 6734 the preferred recipe's name (:term:`PN`). Here is a common 6735 example:: 6736 6737 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 6738 6739 In the previous example, multiple recipes are providing "virtual/kernel". 6740 The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of 6741 the recipe you prefer to provide "virtual/kernel". 6742 6743 Here are more examples:: 6744 6745 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" 6746 PREFERRED_PROVIDER_virtual/libgl ?= "mesa" 6747 6748 For more 6749 information, see the ":ref:`dev-manual/new-recipe:using virtual providers`" 6750 section in the Yocto Project Development Tasks Manual. 6751 6752 .. note:: 6753 6754 If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any 6755 recipe that :term:`PROVIDES` that item but is not selected (defined) 6756 by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually 6757 desirable since this mechanism is designed to select between mutually 6758 exclusive alternative providers. 6759 6760 :term:`PREFERRED_PROVIDERS` 6761 See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual. 6762 6763 :term:`PREFERRED_RPROVIDER` 6764 The :term:`PREFERRED_RPROVIDER` variable works like the 6765 :term:`PREFERRED_PROVIDER` variable, but it denotes packages that provide a 6766 *runtime* component. Runtime providers are declared in recipes that set 6767 the :term:`RPROVIDES` variable for a specific package. 6768 6769 For example:: 6770 6771 PREFERRED_RPROVIDER_virtual-x-terminal-emulator = "rxvt-unicode" 6772 6773 This statement sets the runtime provider for the X terminal emulator to 6774 ``rxvt-unicode``. The ``rxvt-unicode`` package is a runtime provider of 6775 this component because the ``rxvt-unicode`` recipe set the following 6776 :term:`RPROVIDES` definition for the ``rxvt-unicode`` (``${PN}``) 6777 package:: 6778 6779 RPROVIDES:${PN} = "virtual-x-terminal-emulator" 6780 6781 For more information on virtual providers, see the 6782 ":ref:`dev-manual/new-recipe:using virtual providers`" section in the 6783 Yocto Project Development Tasks Manual. 6784 6785 :term:`PREFERRED_VERSION` 6786 If there are multiple versions of a recipe available, this variable 6787 determines which version should be given preference. You must always 6788 suffix the variable with the :term:`PN` you want to select (`python` in 6789 the first example below), and you should specify the :term:`PV` 6790 accordingly (`3.4.0` in the example). 6791 6792 The :term:`PREFERRED_VERSION` variable supports limited wildcard use 6793 through the "``%``" character. You can use the character to match any 6794 number of characters, which can be useful when specifying versions 6795 that contain long revision numbers that potentially change. Here are 6796 two examples:: 6797 6798 PREFERRED_VERSION_python = "3.4.0" 6799 PREFERRED_VERSION_linux-yocto = "5.0%" 6800 6801 .. note:: 6802 6803 The use of the "%" character is limited in that it only works at the end of the 6804 string. You cannot use the wildcard character in any other 6805 location of the string. 6806 6807 The specified version is matched against :term:`PV`, which does not 6808 necessarily match the version part of the recipe's filename. 6809 6810 If you want to select a recipe named ``foo_git.bb`` which has :term:`PV` 6811 set to ``1.2.3+git``, you can do so by setting ```PREFERRED_VERSION_foo`` 6812 to ``1.2.3%`` (i.e. simply setting ``PREFERRED_VERSION_foo`` to ``git`` 6813 will not work as the name of the recipe isn't used, but rather its 6814 :term:`PV` definition). 6815 6816 Sometimes the :term:`PREFERRED_VERSION` variable can be set by 6817 configuration files in a way that is hard to change. You can use 6818 :term:`OVERRIDES` to set a machine-specific 6819 override. Here is an example:: 6820 6821 PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%" 6822 6823 Although not recommended, worst case, you can also use the 6824 "forcevariable" override, which is the strongest override possible. 6825 Here is an example:: 6826 6827 PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%" 6828 6829 .. note:: 6830 6831 The ``:forcevariable`` override is not handled specially. This override 6832 only works because the default value of :term:`OVERRIDES` includes "forcevariable". 6833 6834 If a recipe with the specified version is not available, a warning 6835 message will be shown. See :term:`REQUIRED_VERSION` if you want this 6836 to be an error instead. 6837 6838 :term:`PREMIRRORS` 6839 Specifies additional paths from which the OpenEmbedded build system 6840 gets source code. When the build system searches for source code, it 6841 first tries the local download directory. If that location fails, the 6842 build system tries locations defined by :term:`PREMIRRORS`, the upstream 6843 source, and then locations specified by 6844 :term:`MIRRORS` in that order. 6845 6846 The default value for :term:`PREMIRRORS` is defined in the 6847 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer. 6848 6849 Typically, you could add a specific server for the build system to 6850 attempt before any others by adding something like the following to 6851 the ``local.conf`` configuration file in the 6852 :term:`Build Directory`:: 6853 6854 PREMIRRORS:prepend = "\ 6855 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6856 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6857 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6858 https://.*/.* &YOCTO_DL_URL;/mirror/sources/" 6859 6860 These changes cause the 6861 build system to intercept Git, FTP, HTTP, and HTTPS requests and 6862 direct them to the ``http://`` sources mirror. You can use 6863 ``file://`` URLs to point to local directories or network shares as 6864 well. 6865 6866 :term:`PRIORITY` 6867 Indicates the importance of a package. 6868 6869 :term:`PRIORITY` is considered to be part of the distribution policy 6870 because the importance of any given recipe depends on the purpose for 6871 which the distribution is being produced. Thus, :term:`PRIORITY` is not 6872 normally set within recipes. 6873 6874 You can set :term:`PRIORITY` to "required", "standard", "extra", and 6875 "optional", which is the default. 6876 6877 :term:`PRIVATE_LIBS` 6878 Specifies libraries installed within a recipe that should be ignored 6879 by the OpenEmbedded build system's shared library resolver. This 6880 variable is typically used when software being built by a recipe has 6881 its own private versions of a library normally provided by another 6882 recipe. In this case, you would not want the package containing the 6883 private libraries to be set as a dependency on other unrelated 6884 packages that should instead depend on the package providing the 6885 standard version of the library. 6886 6887 Libraries specified in this variable should be specified by their 6888 file name. For example, from the Firefox recipe in meta-browser:: 6889 6890 PRIVATE_LIBS = "libmozjs.so \ 6891 libxpcom.so \ 6892 libnspr4.so \ 6893 libxul.so \ 6894 libmozalloc.so \ 6895 libplc4.so \ 6896 libplds4.so" 6897 6898 For more information, see the 6899 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6900 section in the Yocto Project Overview and Concepts Manual. 6901 6902 :term:`PROVIDES` 6903 A list of aliases by which a particular recipe can be known. By 6904 default, a recipe's own :term:`PN` is implicitly already in its 6905 :term:`PROVIDES` list and therefore does not need to mention that it 6906 provides itself. If a recipe uses :term:`PROVIDES`, the additional 6907 aliases are synonyms for the recipe and can be useful for satisfying 6908 dependencies of other recipes during the build as specified by 6909 :term:`DEPENDS`. 6910 6911 Consider the following example :term:`PROVIDES` statement from the recipe 6912 file ``eudev_3.2.9.bb``:: 6913 6914 PROVIDES += "udev" 6915 6916 The :term:`PROVIDES` statement 6917 results in the "eudev" recipe also being available as simply "udev". 6918 6919 .. note:: 6920 6921 A recipe's own recipe name (:term:`PN`) is always implicitly prepended 6922 to :term:`PROVIDES`, so while using "+=" in the above example may not be 6923 strictly necessary it is recommended to avoid confusion. 6924 6925 In addition to providing recipes under alternate names, the 6926 :term:`PROVIDES` mechanism is also used to implement virtual targets. A 6927 virtual target is a name that corresponds to some particular 6928 functionality (e.g. a Linux kernel). Recipes that provide the 6929 functionality in question list the virtual target in :term:`PROVIDES`. 6930 Recipes that depend on the functionality in question can include the 6931 virtual target in :term:`DEPENDS` to leave the choice of provider open. 6932 6933 Conventionally, virtual targets have names on the form 6934 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part 6935 of the name and has no syntactical significance. 6936 6937 The :term:`PREFERRED_PROVIDER` variable is 6938 used to select which particular recipe provides a virtual target. 6939 6940 .. note:: 6941 6942 A corresponding mechanism for virtual runtime dependencies (packages) 6943 exists. However, the mechanism does not depend on any special 6944 functionality beyond ordinary variable assignments. For example, 6945 :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the 6946 package of the component that manages the ``/dev`` directory. 6947 6948 Setting the "preferred provider" for runtime dependencies is as 6949 simple as using the following assignment in a configuration file:: 6950 6951 VIRTUAL-RUNTIME_dev_manager = "udev" 6952 6953 6954 :term:`PRSERV_HOST` 6955 The network based :term:`PR` service host and port. 6956 6957 The ``conf/templates/default/local.conf.sample.extended`` configuration 6958 file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST` 6959 variable is set:: 6960 6961 PRSERV_HOST = "localhost:0" 6962 6963 You must 6964 set the variable if you want to automatically start a local :ref:`PR 6965 service <dev-manual/packages:working with a pr service>`. You can 6966 set :term:`PRSERV_HOST` to other values to use a remote PR service. 6967 6968 :term:`PRSERV_UPSTREAM` 6969 This variable can be used to specify an upstream PR server for the local 6970 PR server to connect to, in the form of ``host:port``. 6971 6972 This makes it possible to implement local fixes to an upstream package. 6973 6974 :term:`PSEUDO_IGNORE_PATHS` 6975 A comma-separated (without spaces) list of path prefixes that should be ignored 6976 by pseudo when monitoring and recording file operations, in order to avoid 6977 problems with files being written to outside of the pseudo context and 6978 reduce pseudo's overhead. A path is ignored if it matches any prefix in the list 6979 and can include partial directory (or file) names. 6980 6981 6982 :term:`PTEST_ENABLED` 6983 Specifies whether or not :ref:`Package 6984 Test <test-manual/ptest:testing packages with ptest>` (ptest) 6985 functionality is enabled when building a recipe. You should not set 6986 this variable directly. Enabling and disabling building Package Tests 6987 at build time should be done by adding "ptest" to (or removing it 6988 from) :term:`DISTRO_FEATURES`. 6989 6990 :term:`PV` 6991 The version of the recipe. The version is normally extracted from the 6992 recipe filename. For example, if the recipe is named 6993 ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1". 6994 :term:`PV` is generally not overridden within a recipe unless it is 6995 building an unstable (i.e. development) version from a source code 6996 repository (e.g. Git or Subversion). 6997 6998 :term:`PV` is the default value of the :term:`PKGV` variable. 6999 7000 :term:`PYPI_PACKAGE` 7001 When inheriting the :ref:`ref-classes-pypi` class, specifies the 7002 `PyPI <https://pypi.org/>`__ package name to be built. The default value 7003 is set based upon :term:`BPN` (stripping any "python-" or "python3-" 7004 prefix off if present), however for some packages it will need to be set 7005 explicitly if that will not match the package name (e.g. where the 7006 package name has a prefix, underscores, uppercase letters etc.) 7007 7008 :term:`PYPI_PACKAGE_EXT` 7009 When inheriting the :ref:`ref-classes-pypi` class, specifies the 7010 file extension to use when fetching a package from `PyPI 7011 <https://pypi.org/>`__. Default is ``tar.gz``. 7012 7013 :term:`PYPI_SRC_URI` 7014 When inheriting the :ref:`ref-classes-pypi` class, specifies the 7015 full `pythonhosted <https://files.pythonhosted.org/>`__ URI for 7016 fetching the package to be built. The default value is constructed 7017 based upon :term:`PYPI_PACKAGE`, :term:`PYPI_PACKAGE_EXT`, and 7018 :term:`PV`. Most recipes will not need to set this variable unless 7019 they are building an unstable (i.e. development) version. 7020 7021 :term:`PYTHON_ABI` 7022 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7023 class, denotes the Application Binary Interface (ABI) currently in use 7024 for Python. By default, the ABI is "m". You do not have to set this 7025 variable as the OpenEmbedded build system sets it for you. 7026 7027 The OpenEmbedded build system uses the ABI to construct directory 7028 names used when installing the Python headers and libraries in 7029 sysroot (e.g. ``.../python3.3m/...``). 7030 7031 :term:`QA_EMPTY_DIRS` 7032 Specifies a list of directories that are expected to be empty when 7033 packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or 7034 :term:`WARN_QA` these will be checked and an error or warning 7035 (respectively) will be produced. 7036 7037 The default :term:`QA_EMPTY_DIRS` value is set in 7038 :ref:`insane.bbclass <ref-classes-insane>`. 7039 7040 :term:`QA_EMPTY_DIRS_RECOMMENDATION` 7041 Specifies a recommendation for why a directory must be empty, 7042 which will be included in the error message if a specific directory 7043 is found to contain files. Must be overridden with the directory 7044 path to match on. 7045 7046 If no recommendation is specified for a directory, then the default 7047 "but it is expected to be empty" will be used. 7048 7049 An example message shows if files were present in '/dev':: 7050 7051 QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime" 7052 7053 :term:`RANLIB` 7054 The minimal command and arguments to run ``ranlib``. 7055 7056 :term:`RCONFLICTS` 7057 The list of packages that conflict with packages. Note that packages 7058 will not be installed if conflicting packages are not first removed. 7059 7060 Like all package-controlling variables, you must always use them in 7061 conjunction with a package name override. Here is an example:: 7062 7063 RCONFLICTS:${PN} = "another_conflicting_package_name" 7064 7065 BitBake, which the OpenEmbedded build system uses, supports 7066 specifying versioned dependencies. Although the syntax varies 7067 depending on the packaging format, BitBake hides these differences 7068 from you. Here is the general syntax to specify versions with the 7069 :term:`RCONFLICTS` variable:: 7070 7071 RCONFLICTS:${PN} = "package (operator version)" 7072 7073 For ``operator``, you can specify the following: 7074 7075 - = 7076 - < 7077 - > 7078 - <= 7079 - >= 7080 7081 For example, the following sets up a dependency on version 1.2 or 7082 greater of the package ``foo``:: 7083 7084 RCONFLICTS:${PN} = "foo (>= 1.2)" 7085 7086 :term:`RDEPENDS` 7087 Lists runtime dependencies of a package. These dependencies are other 7088 packages that must be installed in order for the package to function 7089 correctly. As an example, the following assignment declares that the 7090 package ``foo`` needs the packages ``bar`` and ``baz`` to be 7091 installed:: 7092 7093 RDEPENDS:foo = "bar baz" 7094 7095 The most common types of package 7096 runtime dependencies are automatically detected and added. Therefore, 7097 most recipes do not need to set :term:`RDEPENDS`. For more information, 7098 see the 7099 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 7100 section in the Yocto Project Overview and Concepts Manual. 7101 7102 The practical effect of the above :term:`RDEPENDS` assignment is that 7103 ``bar`` and ``baz`` will be declared as dependencies inside the 7104 package ``foo`` when it is written out by one of the 7105 :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks. 7106 Exactly how this is done depends on which package format is used, 7107 which is determined by 7108 :term:`PACKAGE_CLASSES`. When the 7109 corresponding package manager installs the package, it will know to 7110 also install the packages on which it depends. 7111 7112 To ensure that the packages ``bar`` and ``baz`` get built, the 7113 previous :term:`RDEPENDS` assignment also causes a task dependency to be 7114 added. This dependency is from the recipe's 7115 :ref:`ref-tasks-build` (not to be confused with 7116 :ref:`ref-tasks-compile`) task to the 7117 :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and 7118 ``baz``. 7119 7120 The names of the packages you list within :term:`RDEPENDS` must be the 7121 names of other packages --- they cannot be recipe names. Although 7122 package names and recipe names usually match, the important point 7123 here is that you are providing package names within the :term:`RDEPENDS` 7124 variable. For an example of the default list of packages created from 7125 a recipe, see the :term:`PACKAGES` variable. 7126 7127 Because the :term:`RDEPENDS` variable applies to packages being built, 7128 you should always use the variable in a form with an attached package 7129 name (remember that a single recipe can build multiple packages). For 7130 example, suppose you are building a development package that depends 7131 on the ``perl`` package. In this case, you would use the following 7132 :term:`RDEPENDS` statement:: 7133 7134 RDEPENDS:${PN}-dev += "perl" 7135 7136 In the example, 7137 the development package depends on the ``perl`` package. Thus, the 7138 :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of 7139 the variable. 7140 7141 .. note:: 7142 7143 ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` 7144 by default. This default is set in the BitBake configuration file 7145 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove 7146 ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator 7147 rather than the "=" operator. 7148 7149 The package names you use with :term:`RDEPENDS` must appear as they would 7150 in the :term:`PACKAGES` variable. The :term:`PKG` variable 7151 allows a different name to be used for the final package (e.g. the 7152 :ref:`ref-classes-debian` class uses this to rename 7153 packages), but this final package name cannot be used with 7154 :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be 7155 independent of the package format used. 7156 7157 BitBake, which the OpenEmbedded build system uses, supports 7158 specifying versioned dependencies. Although the syntax varies 7159 depending on the packaging format, BitBake hides these differences 7160 from you. Here is the general syntax to specify versions with the 7161 :term:`RDEPENDS` variable:: 7162 7163 RDEPENDS:${PN} = "package (operator version)" 7164 7165 For ``operator``, you can specify the following: 7166 7167 - = 7168 - < 7169 - > 7170 - <= 7171 - >= 7172 7173 For version, provide the version number. 7174 7175 .. note:: 7176 7177 You can use :term:`EXTENDPKGV` to provide a full package version 7178 specification. 7179 7180 For example, the following sets up a dependency on version 1.2 or 7181 greater of the package ``foo``:: 7182 7183 RDEPENDS:${PN} = "foo (>= 1.2)" 7184 7185 For information on build-time dependencies, see the :term:`DEPENDS` 7186 variable. You can also see the 7187 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and 7188 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the 7189 BitBake User Manual for additional information on tasks and dependencies. 7190 7191 :term:`RECIPE_MAINTAINER` 7192 This variable defines the name and e-mail address of the maintainer of a 7193 recipe. Such information can be used by human users submitted changes, 7194 and by automated tools to send notifications, for example about 7195 vulnerabilities or source updates. 7196 7197 The variable can be defined in a global distribution :oe_git:`maintainers.inc 7198 </openembedded-core/tree/meta/conf/distro/include/maintainers.inc>` file:: 7199 7200 meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>" 7201 7202 It can also be directly defined in a recipe, 7203 for example in the ``libgpiod`` one:: 7204 7205 RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>" 7206 7207 :term:`RECIPE_NO_UPDATE_REASON` 7208 If a recipe should not be replaced by a more recent upstream version, 7209 putting the reason why in this variable in a recipe allows 7210 ``devtool check-upgrade-status`` command to display it, as explained 7211 in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`" 7212 section. 7213 7214 :term:`RECIPE_SYSROOT` 7215 This variable points to the directory that holds all files populated from 7216 recipes specified in :term:`DEPENDS`. As the name indicates, 7217 think of this variable as a custom root (``/``) for the recipe that will be 7218 used by the compiler in order to find headers and other files needed to complete 7219 its job. 7220 7221 This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET` 7222 according to the type of the recipe and the build target. 7223 7224 To better understand this variable, consider the following examples: 7225 7226 - For ``#include <header.h>``, ``header.h`` should be in ``"${RECIPE_SYSROOT}/usr/include"`` 7227 7228 - For ``-lexample``, ``libexample.so`` should be in ``"${RECIPE_SYSROOT}/lib"`` 7229 or other library sysroot directories. 7230 7231 The default value is ``"${WORKDIR}/recipe-sysroot"``. 7232 Do not modify it. 7233 7234 :term:`RECIPE_SYSROOT_NATIVE` 7235 This is similar to :term:`RECIPE_SYSROOT` but the populated files are from 7236 ``-native`` recipes. This allows a recipe built for the target machine to 7237 use ``native`` tools. 7238 7239 This variable is related to :term:`STAGING_DIR_NATIVE`. 7240 7241 The default value is ``"${WORKDIR}/recipe-sysroot-native"``. 7242 Do not modify it. 7243 7244 :term:`RECIPE_UPGRADE_EXTRA_TASKS` 7245 When upgrading a recipe with ``devtool upgrade``, the variable 7246 :term:`RECIPE_UPGRADE_EXTRA_TASKS` specifies a space-delimited list of 7247 tasks to run after the new sources have been unpacked. 7248 7249 For some recipes, after the new source has been unpacked, additional tasks 7250 may need to be run during an upgrade. A good example of this is recipes 7251 which inherit :ref:`ref-classes-cargo-update-recipe-crates`, where the 7252 `do_update_crates` task needs to be run whenever Cargo.toml/Cargo.lock have 7253 changed in the source. 7254 7255 :term:`REPODIR` 7256 See :term:`bitbake:REPODIR` in the BitBake manual. 7257 7258 :term:`REQUIRED_DISTRO_FEATURES` 7259 When inheriting the :ref:`ref-classes-features_check` 7260 class, this variable identifies distribution features that must exist 7261 in the current configuration in order for the OpenEmbedded build 7262 system to build the recipe. In other words, if the 7263 :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not 7264 appear in :term:`DISTRO_FEATURES` within the current configuration, then 7265 the recipe will be skipped, and if the build system attempts to build 7266 the recipe then an error will be triggered. 7267 7268 :term:`REQUIRED_VERSION` 7269 If there are multiple versions of a recipe available, this variable 7270 determines which version should be given preference. 7271 :term:`REQUIRED_VERSION` works in exactly the same manner as 7272 :term:`PREFERRED_VERSION`, except that if the specified version is not 7273 available then an error message is shown and the build fails 7274 immediately. 7275 7276 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set 7277 for the same recipe, the :term:`REQUIRED_VERSION` value applies. 7278 7279 :term:`RETAIN_DIRS_ALWAYS` 7280 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7281 space-separated recipe-specific directories to always save in a tarball 7282 whether the recipe build has failed or not. 7283 7284 :term:`RETAIN_DIRS_FAILURE` 7285 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7286 space-separated recipe-specific directories to save in a tarball on 7287 failure of the recipe's build. 7288 7289 :term:`RETAIN_DIRS_GLOBAL_ALWAYS` 7290 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7291 space-separated directories that are not specific to a recipe to save in a 7292 tarball whether the build has failed or not. 7293 7294 :term:`RETAIN_DIRS_GLOBAL_FAILURE` 7295 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7296 space-separated directories that are not specific to a recipe to save in a 7297 tarball on build failure. 7298 7299 :term:`RETAIN_ENABLED` 7300 Disables the creation of a tarball of the work directory done by the 7301 :ref:`ref-classes-retain` class. Can be set to specific recipes to disable 7302 the class when the class was inherited globally with :term:`INHERIT`. 7303 7304 :term:`RETAIN_OUTDIR` 7305 When inheriting the :ref:`ref-classes-retain` class, this variable 7306 specifies the directory where to save the tarball of the work directory. 7307 The default directory is ``${TMPDIR}/retain``. 7308 7309 :term:`RETAIN_TARBALL_SUFFIX` 7310 When inheriting the :ref:`ref-classes-retain` class, this variable 7311 specifies the suffix of the tarball of the work directory. The default 7312 suffix is ``${DATETIME}.tar.gz``. 7313 7314 :term:`RM_WORK_EXCLUDE` 7315 With :ref:`ref-classes-rm-work` enabled, this variable 7316 specifies a list of recipes whose work directories should not be removed. 7317 See the ":ref:`ref-classes-rm-work`" section for more details. 7318 7319 :term:`ROOT_HOME` 7320 Defines the root home directory. By default, this directory is set as 7321 follows in the BitBake configuration file:: 7322 7323 ROOT_HOME ??= "/home/root" 7324 7325 .. note:: 7326 7327 This default value is likely used because some embedded solutions 7328 prefer to have a read-only root filesystem and prefer to keep 7329 writeable data in one place. 7330 7331 You can override the default by setting the variable in any layer or 7332 in the ``local.conf`` file. Because the default is set using a "weak" 7333 assignment (i.e. "??="), you can use either of the following forms to 7334 define your override:: 7335 7336 ROOT_HOME = "/root" 7337 ROOT_HOME ?= "/root" 7338 7339 These 7340 override examples use ``/root``, which is probably the most commonly 7341 used override. 7342 7343 :term:`ROOTFS` 7344 Indicates a filesystem image to include as the root filesystem. 7345 7346 The :term:`ROOTFS` variable is an optional variable used with the 7347 :ref:`ref-classes-image-live` class. 7348 7349 :term:`ROOTFS_POSTINSTALL_COMMAND` 7350 Specifies a list of functions to call after the OpenEmbedded build 7351 system has installed packages. You can specify functions separated by 7352 spaces:: 7353 7354 ROOTFS_POSTINSTALL_COMMAND += "function" 7355 7356 If you need to pass the root filesystem path to a command within a 7357 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7358 directory that becomes the root filesystem image. See the 7359 :term:`IMAGE_ROOTFS` variable for more 7360 information. 7361 7362 :term:`ROOTFS_POSTPROCESS_COMMAND` 7363 Specifies a list of functions to call once the OpenEmbedded build 7364 system has created the root filesystem. You can specify functions 7365 separated by spaces:: 7366 7367 ROOTFS_POSTPROCESS_COMMAND += "function" 7368 7369 If you need to pass the root filesystem path to a command within a 7370 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7371 directory that becomes the root filesystem image. See the 7372 :term:`IMAGE_ROOTFS` variable for more 7373 information. 7374 7375 :term:`ROOTFS_POSTUNINSTALL_COMMAND` 7376 Specifies a list of functions to call after the OpenEmbedded build 7377 system has removed unnecessary packages. When runtime package 7378 management is disabled in the image, several packages are removed 7379 including ``base-passwd``, ``shadow``, and ``update-alternatives``. 7380 You can specify functions separated by spaces:: 7381 7382 ROOTFS_POSTUNINSTALL_COMMAND += "function" 7383 7384 If you need to pass the root filesystem path to a command within a 7385 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7386 directory that becomes the root filesystem image. See the 7387 :term:`IMAGE_ROOTFS` variable for more 7388 information. 7389 7390 :term:`ROOTFS_PREPROCESS_COMMAND` 7391 Specifies a list of functions to call before the OpenEmbedded build 7392 system has created the root filesystem. You can specify functions 7393 separated by spaces:: 7394 7395 ROOTFS_PREPROCESS_COMMAND += "function" 7396 7397 If you need to pass the root filesystem path to a command within a 7398 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7399 directory that becomes the root filesystem image. See the 7400 :term:`IMAGE_ROOTFS` variable for more 7401 information. 7402 7403 :term:`RPMBUILD_EXTRA_PARAMS` 7404 Specifies extra user-defined parameters for the ``rpmbuild`` command. 7405 7406 :term:`RPROVIDES` 7407 A list of package name aliases that a package also provides. These 7408 aliases are useful for satisfying runtime dependencies of other 7409 packages both during the build and on the target (as specified by 7410 :term:`RDEPENDS`). 7411 7412 .. note:: 7413 7414 A package's own name is implicitly already in its :term:`RPROVIDES` list. 7415 7416 As with all package-controlling variables, you must always use the 7417 variable in conjunction with a package name override. Here is an 7418 example:: 7419 7420 RPROVIDES:${PN} = "widget-abi-2" 7421 7422 :term:`RRECOMMENDS` 7423 A list of packages that extends the usability of a package being 7424 built. The package being built does not depend on this list of 7425 packages in order to successfully build, but rather uses them for 7426 extended usability. To specify runtime dependencies for packages, see 7427 the :term:`RDEPENDS` variable. 7428 7429 The package manager will automatically install the :term:`RRECOMMENDS` 7430 list of packages when installing the built package. However, you can 7431 prevent listed packages from being installed by using the 7432 :term:`BAD_RECOMMENDATIONS`, 7433 :term:`NO_RECOMMENDATIONS`, and 7434 :term:`PACKAGE_EXCLUDE` variables. 7435 7436 Packages specified in :term:`RRECOMMENDS` need not actually be produced. 7437 However, there must be a recipe providing each package, either 7438 through the :term:`PACKAGES` or 7439 :term:`PACKAGES_DYNAMIC` variables or the 7440 :term:`RPROVIDES` variable, or an error will occur 7441 during the build. If such a recipe does exist and the package is not 7442 produced, the build continues without error. 7443 7444 Because the :term:`RRECOMMENDS` variable applies to packages being built, 7445 you should always attach an override to the variable to specify the 7446 particular package whose usability is being extended. For example, 7447 suppose you are building a development package that is extended to 7448 support wireless functionality. In this case, you would use the 7449 following:: 7450 7451 RRECOMMENDS:${PN}-dev += "wireless_package_name" 7452 7453 In the 7454 example, the package name (``${PN}-dev``) must appear as it would in 7455 the :term:`PACKAGES` namespace before any renaming of the output package 7456 by classes such as :ref:`ref-classes-debian`. 7457 7458 BitBake, which the OpenEmbedded build system uses, supports 7459 specifying versioned recommends. Although the syntax varies depending 7460 on the packaging format, BitBake hides these differences from you. 7461 Here is the general syntax to specify versions with the 7462 :term:`RRECOMMENDS` variable:: 7463 7464 RRECOMMENDS:${PN} = "package (operator version)" 7465 7466 For ``operator``, you can specify the following: 7467 7468 - = 7469 - < 7470 - > 7471 - <= 7472 - >= 7473 7474 For example, the following sets up a recommend on version 1.2 or 7475 greater of the package ``foo``:: 7476 7477 RRECOMMENDS:${PN} = "foo (>= 1.2)" 7478 7479 :term:`RREPLACES` 7480 A list of packages replaced by a package. The package manager uses 7481 this variable to determine which package should be installed to 7482 replace other package(s) during an upgrade. In order to also have the 7483 other package(s) removed at the same time, you must add the name of 7484 the other package to the :term:`RCONFLICTS` variable. 7485 7486 As with all package-controlling variables, you must use this variable 7487 in conjunction with a package name override. Here is an example:: 7488 7489 RREPLACES:${PN} = "other_package_being_replaced" 7490 7491 BitBake, which the OpenEmbedded build system uses, supports 7492 specifying versioned replacements. Although the syntax varies 7493 depending on the packaging format, BitBake hides these differences 7494 from you. Here is the general syntax to specify versions with the 7495 :term:`RREPLACES` variable:: 7496 7497 RREPLACES:${PN} = "package (operator version)" 7498 7499 For ``operator``, you can specify the following: 7500 7501 - = 7502 - < 7503 - > 7504 - <= 7505 - >= 7506 7507 For example, the following sets up a replacement using version 1.2 7508 or greater of the package ``foo``:: 7509 7510 RREPLACES:${PN} = "foo (>= 1.2)" 7511 7512 :term:`RSUGGESTS` 7513 A list of additional packages that you can suggest for installation 7514 by the package manager at the time a package is installed. Not all 7515 package managers support this functionality. 7516 7517 As with all package-controlling variables, you must always use this 7518 variable in conjunction with a package name override. Here is an 7519 example:: 7520 7521 RSUGGESTS:${PN} = "useful_package another_package" 7522 7523 :term:`RUST_CHANNEL` 7524 Specifies which version of Rust to build - "stable", "beta" or "nightly". 7525 The default value is "stable". Set this at your own risk, as values other 7526 than "stable" are not guaranteed to work at a given time. 7527 7528 :term:`S` 7529 The location in the :term:`Build Directory` where 7530 unpacked recipe source code resides. By default, this directory is 7531 ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, 7532 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe 7533 version. If the source tarball extracts the code to a directory named 7534 anything other than ``${BPN}-${PV}``, or if the source code is 7535 fetched from an SCM such as Git or Subversion, then you must set 7536 :term:`S` in the recipe so that the OpenEmbedded build system knows where 7537 to find the unpacked source. 7538 7539 As an example, assume a :term:`Source Directory` 7540 top-level folder named ``poky`` and a default :term:`Build Directory` at 7541 ``poky/build``. In this case, the work directory the build system 7542 uses to keep the unpacked recipe for ``db`` is the following:: 7543 7544 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 7545 7546 The unpacked source code resides in the ``db-5.1.19`` folder. 7547 7548 This next example assumes a Git repository. By default, Git 7549 repositories are cloned to ``${WORKDIR}/git`` during 7550 :ref:`ref-tasks-fetch`. Since this path is different 7551 from the default value of :term:`S`, you must set it specifically so the 7552 source can be located:: 7553 7554 SRC_URI = "git://path/to/repo.git;branch=main" 7555 S = "${WORKDIR}/git" 7556 7557 :term:`SANITY_REQUIRED_UTILITIES` 7558 Specifies a list of command-line utilities that should be checked for 7559 during the initial sanity checking process when running BitBake. If 7560 any of the utilities are not installed on the build host, then 7561 BitBake immediately exits with an error. 7562 7563 :term:`SANITY_TESTED_DISTROS` 7564 A list of the host distribution identifiers that the build system has 7565 been tested against. Identifiers consist of the host distributor ID 7566 followed by the release, as reported by the ``lsb_release`` tool or 7567 as read from ``/etc/lsb-release``. Separate the list items with 7568 explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is 7569 not empty and the current value of 7570 :term:`NATIVELSBSTRING` does not appear in the 7571 list, then the build system reports a warning that indicates the 7572 current host distribution has not been tested as a build host. 7573 7574 :term:`SDK_ARCH` 7575 The target architecture for the SDK. Typically, you do not directly 7576 set this variable. Instead, use :term:`SDKMACHINE`. 7577 7578 :term:`SDK_ARCHIVE_TYPE` 7579 Specifies the type of archive to create for the SDK. Valid values: 7580 7581 - ``tar.xz`` (default) 7582 - ``tar.zst`` 7583 - ``7zip`` 7584 - ``zip`` 7585 7586 Only one archive type can be specified. 7587 7588 :term:`SDK_BUILDINFO_FILE` 7589 When using the :ref:`ref-classes-image-buildinfo` class, 7590 specifies the file in the SDK to write the build information into. The 7591 default value is "``/buildinfo``". 7592 7593 :term:`SDK_CUSTOM_TEMPLATECONF` 7594 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to 7595 "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory` 7596 (:term:`TOPDIR`) then this will be copied into the SDK. 7597 7598 :term:`SDK_DEPLOY` 7599 The directory set up and used by the 7600 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the 7601 SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>` 7602 class defines :term:`SDK_DEPLOY` as follows:: 7603 7604 SDK_DEPLOY = "${TMPDIR}/deploy/sdk" 7605 7606 :term:`SDK_DIR` 7607 The parent directory used by the OpenEmbedded build system when 7608 creating SDK output. The 7609 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines 7610 the variable as follows:: 7611 7612 SDK_DIR = "${WORKDIR}/sdk" 7613 7614 .. note:: 7615 7616 The :term:`SDK_DIR` directory is a temporary directory as it is part of 7617 :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`. 7618 7619 :term:`SDK_EXT_TYPE` 7620 Controls whether or not shared state artifacts are copied into the 7621 extensible SDK. The default value of "full" copies all of the 7622 required shared state artifacts into the extensible SDK. The value 7623 "minimal" leaves these artifacts out of the SDK. 7624 7625 .. note:: 7626 7627 If you set the variable to "minimal", you need to ensure 7628 :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the 7629 artifacts to be fetched as needed. 7630 7631 :term:`SDK_HOST_MANIFEST` 7632 The manifest file for the host part of the SDK. This file lists all 7633 the installed packages that make up the host part of the SDK. The 7634 file contains package information on a line-per-package basis as 7635 follows:: 7636 7637 packagename packagearch version 7638 7639 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7640 defines the manifest file as follows:: 7641 7642 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" 7643 7644 The location is derived using the :term:`SDK_DEPLOY` and 7645 :term:`TOOLCHAIN_OUTPUTNAME` variables. 7646 7647 :term:`SDK_INCLUDE_PKGDATA` 7648 When set to "1", specifies to include the packagedata for all recipes 7649 in the "world" target in the extensible SDK. Including this data 7650 allows the ``devtool search`` command to find these recipes in search 7651 results, as well as allows the ``devtool add`` command to map 7652 dependencies more effectively. 7653 7654 .. note:: 7655 7656 Enabling the :term:`SDK_INCLUDE_PKGDATA` 7657 variable significantly increases build time because all of world 7658 needs to be built. Enabling the variable also slightly increases 7659 the size of the extensible SDK. 7660 7661 :term:`SDK_INCLUDE_TOOLCHAIN` 7662 When set to "1", specifies to include the toolchain in the extensible 7663 SDK. Including the toolchain is useful particularly when 7664 :term:`SDK_EXT_TYPE` is set to "minimal" to keep 7665 the SDK reasonably small but you still want to provide a usable 7666 toolchain. For example, suppose you want to use the toolchain from an 7667 IDE or from other tools and you do not want to perform additional 7668 steps to install the toolchain. 7669 7670 The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if 7671 :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if 7672 :term:`SDK_EXT_TYPE` is set to "full". 7673 7674 :term:`SDK_NAME` 7675 The base name for SDK output files. The default value (as set in 7676 ``meta-poky/conf/distro/poky.conf``) is derived from the 7677 :term:`DISTRO`, 7678 :term:`TCLIBC`, 7679 :term:`SDKMACHINE`, 7680 :term:`IMAGE_BASENAME`, 7681 :term:`TUNE_PKGARCH`, and 7682 :term:`MACHINE` variables:: 7683 7684 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}" 7685 7686 :term:`SDK_OS` 7687 Specifies the operating system for which the SDK will be built. The 7688 default value is the value of :term:`BUILD_OS`. 7689 7690 :term:`SDK_OUTPUT` 7691 The location used by the OpenEmbedded build system when creating SDK 7692 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 7693 class defines the variable as follows:: 7694 7695 SDK_DIR = "${WORKDIR}/sdk" 7696 SDK_OUTPUT = "${SDK_DIR}/image" 7697 SDK_DEPLOY = "${DEPLOY_DIR}/sdk" 7698 7699 .. note:: 7700 7701 The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of 7702 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is 7703 :term:`SDK_DEPLOY`. 7704 7705 :term:`SDK_PACKAGE_ARCHS` 7706 Specifies a list of architectures compatible with the SDK machine. 7707 This variable is set automatically and should not normally be 7708 hand-edited. Entries are separated using spaces and listed in order 7709 of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any 7710 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". 7711 7712 :term:`SDK_POSTPROCESS_COMMAND` 7713 Specifies a list of functions to call once the OpenEmbedded build 7714 system creates the SDK. You can specify functions separated by 7715 spaces: 7716 7717 SDK_POSTPROCESS_COMMAND += "function" 7718 7719 If you need to pass an SDK path to a command within a function, you 7720 can use ``${SDK_DIR}``, which points to the parent directory used by 7721 the OpenEmbedded build system when creating SDK output. See the 7722 :term:`SDK_DIR` variable for more information. 7723 7724 :term:`SDK_PREFIX` 7725 The toolchain binary prefix used for 7726 :ref:`ref-classes-nativesdk` recipes. The 7727 OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the 7728 :term:`TARGET_PREFIX` when building 7729 ``nativesdk`` recipes. The default value is "${SDK_SYS}-". 7730 7731 :term:`SDK_RECRDEP_TASKS` 7732 A list of shared state tasks added to the extensible SDK. By default, 7733 the following tasks are added: 7734 7735 - :ref:`ref-tasks-populate_lic` 7736 - :ref:`ref-tasks-package_qa` 7737 - :ref:`ref-tasks-populate_sysroot` 7738 - :ref:`ref-tasks-deploy` 7739 7740 Despite the default value of "" for the 7741 :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added 7742 to the SDK. To specify tasks beyond these four, you need to use the 7743 :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional 7744 tasks that are needed in order to build 7745 :term:`SDK_TARGETS`). 7746 7747 :term:`SDK_SYS` 7748 Specifies the system, including the architecture and the operating 7749 system, for which the SDK will be built. 7750 7751 The OpenEmbedded build system automatically sets this variable based 7752 on :term:`SDK_ARCH`, 7753 :term:`SDK_VENDOR`, and 7754 :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS` 7755 variable yourself. 7756 7757 :term:`SDK_TARGET_MANIFEST` 7758 The manifest file for the target part of the SDK. This file lists all 7759 the installed packages that make up the target part of the SDK. The 7760 file contains package information on a line-per-package basis as 7761 follows:: 7762 7763 packagename packagearch version 7764 7765 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7766 defines the manifest file as follows:: 7767 7768 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" 7769 7770 The location is derived using the :term:`SDK_DEPLOY` and 7771 :term:`TOOLCHAIN_OUTPUTNAME` variables. 7772 7773 :term:`SDK_TARGETS` 7774 A list of targets to install from shared state as part of the 7775 standard or extensible SDK installation. The default value is "${PN}" 7776 (i.e. the image from which the SDK is built). 7777 7778 The :term:`SDK_TARGETS` variable is an internal variable and typically 7779 would not be changed. 7780 7781 :term:`SDK_TITLE` 7782 The title to be printed when running the SDK installer. By default, 7783 this title is based on the :term:`DISTRO_NAME` or 7784 :term:`DISTRO` variable and is set in the 7785 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7786 follows:: 7787 7788 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" 7789 7790 For the default distribution "poky", 7791 :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)". 7792 7793 For information on how to change this default title, see the 7794 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" 7795 section in the Yocto Project Application Development and the 7796 Extensible Software Development Kit (eSDK) manual. 7797 7798 :term:`SDK_TOOLCHAIN_LANGS` 7799 Specifies programming languages to support in the SDK, as a 7800 space-separated list. Currently supported items are ``rust`` and ``go``. 7801 7802 :term:`SDK_UPDATE_URL` 7803 An optional URL for an update server for the extensible SDK. If set, 7804 the value is used as the default update server when running 7805 ``devtool sdk-update`` within the extensible SDK. 7806 7807 :term:`SDK_VENDOR` 7808 Specifies the name of the SDK vendor. 7809 7810 :term:`SDK_VERSION` 7811 Specifies the version of the SDK. The Poky distribution configuration file 7812 (``/meta-poky/conf/distro/poky.conf``) sets the default 7813 :term:`SDK_VERSION` as follows:: 7814 7815 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}" 7816 7817 For additional information, see the 7818 :term:`DISTRO_VERSION` and 7819 :term:`METADATA_REVISION` variables. 7820 7821 :term:`SDK_ZIP_OPTIONS` 7822 Specifies extra options to pass to the ``zip`` command when zipping the SDK 7823 (i.e. when :term:`SDK_ARCHIVE_TYPE` is set to "zip"). The default value is 7824 "-y". 7825 7826 :term:`SDKEXTPATH` 7827 The default installation directory for the Extensible SDK. By 7828 default, this directory is based on the :term:`DISTRO` 7829 variable and is set in the 7830 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7831 follows:: 7832 7833 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" 7834 7835 For the 7836 default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk". 7837 7838 For information on how to change this default directory, see the 7839 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" 7840 section in the Yocto Project Application Development and the 7841 Extensible Software Development Kit (eSDK) manual. 7842 7843 :term:`SDKIMAGE_FEATURES` 7844 Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to 7845 the SDK generated from an image using the following command:: 7846 7847 $ bitbake -c populate_sdk imagename 7848 7849 :term:`SDKMACHINE` 7850 The machine for which the SDK is built. In other words, the SDK is built 7851 such that it runs on the target you specify with the :term:`SDKMACHINE` 7852 value. The value points to a corresponding ``.conf`` file under 7853 ``conf/machine-sdk/`` in the enabled layers, for example ``aarch64``, 7854 ``i586``, ``i686``, ``ppc64``, ``ppc64le``, and ``x86_64`` are 7855 :oe_git:`available in OpenEmbedded-Core </openembedded-core/tree/meta/conf/machine-sdk>`. 7856 7857 The variable defaults to :term:`BUILD_ARCH` so that SDKs are built for the 7858 architecture of the build machine. 7859 7860 .. note:: 7861 7862 You cannot set the :term:`SDKMACHINE` 7863 variable in your distribution configuration file. If you do, the 7864 configuration will not take effect. 7865 7866 :term:`SDKPATH` 7867 Defines the path used to collect the SDK components and build the 7868 installer. 7869 7870 :term:`SDKPATHINSTALL` 7871 Defines the path offered to the user for installation of the SDK that 7872 is generated by the OpenEmbedded build system. The path appears as 7873 the default location for installing the SDK when you run the SDK's 7874 installation script. You can override the offered path when you run 7875 the script. 7876 7877 :term:`SDKTARGETSYSROOT` 7878 The full path to the sysroot used for cross-compilation within an SDK 7879 as it will be when installed into the default 7880 :term:`SDKPATHINSTALL`. 7881 7882 :term:`SECTION` 7883 The section in which packages should be categorized. Package 7884 management utilities can make use of this variable. 7885 7886 :term:`SELECTED_OPTIMIZATION` 7887 Specifies the optimization flags passed to the C compiler when 7888 building for the target. The flags are passed through the default 7889 value of the :term:`TARGET_CFLAGS` variable. 7890 7891 The :term:`SELECTED_OPTIMIZATION` variable takes the value of 7892 :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which 7893 case the value of :term:`DEBUG_OPTIMIZATION` is used. 7894 7895 :term:`SERIAL_CONSOLES` 7896 Defines a serial console (TTY) to enable using 7897 :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the 7898 baud rate followed by the TTY device name separated by a semicolon. 7899 Use spaces to separate multiple devices:: 7900 7901 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" 7902 7903 :term:`SETUPTOOLS_BUILD_ARGS` 7904 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7905 class, this variable can be used to specify additional arguments to be 7906 passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task. 7907 7908 :term:`SETUPTOOLS_SETUP_PATH` 7909 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7910 class, this variable should be used to specify the directory in which 7911 the ``setup.py`` file is located if it is not at the root of the source 7912 tree (as specified by :term:`S`). For example, in a recipe where the 7913 sources are fetched from a Git repository and ``setup.py`` is in a 7914 ``python/pythonmodule`` subdirectory, you would have this:: 7915 7916 S = "${WORKDIR}/git" 7917 SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule" 7918 7919 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` 7920 A list of recipe dependencies that should not be used to determine 7921 signatures of tasks from one recipe when they depend on tasks from 7922 another recipe. For example:: 7923 7924 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" 7925 7926 In the previous example, ``intone`` depends on ``mplayer2``. 7927 7928 You can use the special token ``"*"`` on the left-hand side of the 7929 dependency to match all recipes except the one on the right-hand 7930 side. Here is an example:: 7931 7932 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" 7933 7934 In the previous example, all recipes except ``quilt-native`` ignore 7935 task signatures from the ``quilt-native`` recipe when determining 7936 their task signatures. 7937 7938 Use of this variable is one mechanism to remove dependencies that 7939 affect task signatures and thus force rebuilds when a recipe changes. 7940 7941 .. note:: 7942 7943 If you add an inappropriate dependency for a recipe relationship, 7944 the software might break during runtime if the interface of the 7945 second recipe was changed after the first recipe had been built. 7946 7947 :term:`SIGGEN_EXCLUDERECIPES_ABISAFE` 7948 A list of recipes that are completely stable and will never change. 7949 The ABI for the recipes in the list are presented by output from the 7950 tasks run to build the recipe. Use of this variable is one way to 7951 remove dependencies from one recipe on another that affect task 7952 signatures and thus force rebuilds when the recipe changes. 7953 7954 .. note:: 7955 7956 If you add an inappropriate variable to this list, the software 7957 might break at runtime if the interface of the recipe was changed 7958 after the other had been built. 7959 7960 :term:`SIGGEN_LOCKEDSIGS` 7961 The list of locked tasks, with the form:: 7962 7963 SIGGEN_LOCKEDSIGS += "<package>:<task>:<signature>" 7964 7965 If ``<signature>`` exists for the specified ``<task>`` and ``<package>`` 7966 in the sstate cache, BitBake will use the cached output instead of 7967 rebuilding the ``<task>``. If it does not exist, BitBake will build the 7968 ``<task>`` and the sstate cache will be used next time. 7969 7970 Example:: 7971 7972 SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0" 7973 7974 You can obtain the signature of all the tasks for the recipe ``bc`` using:: 7975 7976 bitbake -S none bc 7977 7978 Then you can look at files in ``build/tmp/stamps/<arch>/bc`` and look for 7979 files like: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``. 7980 7981 Alternatively, you can also use :doc:`bblock </dev-manual/bblock>` to 7982 generate this line for you. 7983 7984 :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK` 7985 Specifies the debug level of task signature check. 3 levels are supported: 7986 7987 * ``info``: displays a "Note" message to remind the user that a task is locked 7988 and the current signature matches the locked one. 7989 * ``warn``: displays a "Warning" message if a task is locked and the current 7990 signature does not match the locked one. 7991 * ``error``: same as warn but displays an "Error" message and aborts. 7992 7993 :term:`SIGGEN_LOCKEDSIGS_TYPES` 7994 Allowed overrides for :term:`SIGGEN_LOCKEDSIGS`. This is mainly used 7995 for architecture specific locks. A common value for 7996 :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``:: 7997 7998 SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" 7999 8000 SIGGEN_LOCKEDSIGS_core2-64 += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0" 8001 SIGGEN_LOCKEDSIGS_cortexa57 += "bc:do_compile:12178eb6d55ef602a8fe638e49862fd247e07b228f0f08967697b655bfe4bb61" 8002 8003 Here, the ``do_compile`` task from ``bc`` will be locked only for 8004 ``core2-64`` and ``cortexa57`` but not for other architectures such as 8005 ``mips32r2``. 8006 8007 :term:`SITEINFO_BITS` 8008 Specifies the number of bits for the target system CPU. The value 8009 should be either "32" or "64". 8010 8011 :term:`SITEINFO_ENDIANNESS` 8012 Specifies the endian byte order of the target system. The value 8013 should be either "le" for little-endian or "be" for big-endian. 8014 8015 :term:`SKIP_FILEDEPS` 8016 Enables removal of all files from the "Provides" section of an RPM 8017 package. Removal of these files is required for packages containing 8018 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. 8019 8020 To enable file removal, set the variable to "1" in your 8021 ``conf/local.conf`` configuration file in your: 8022 :term:`Build Directory`:: 8023 8024 SKIP_FILEDEPS = "1" 8025 8026 :term:`SKIP_RECIPE` 8027 Used to prevent the OpenEmbedded build system from building a given 8028 recipe. Specify the :term:`PN` value as a variable flag (``varflag``) 8029 and provide a reason, which will be reported when attempting to 8030 build the recipe. 8031 8032 To prevent a recipe from being built, use the :term:`SKIP_RECIPE` 8033 variable in your ``local.conf`` file or distribution configuration. 8034 Here is an example which prevents ``myrecipe`` from being built:: 8035 8036 SKIP_RECIPE[myrecipe] = "Not supported by our organization." 8037 8038 :term:`SOC_FAMILY` 8039 A colon-separated list grouping together machines based upon the same 8040 family of SoC (System On Chip). You typically set this variable in a 8041 common ``.inc`` file that you include in the configuration files of all 8042 the machines. 8043 8044 .. note:: 8045 8046 You must include ``conf/machine/include/soc-family.inc`` for this 8047 variable to appear in :term:`MACHINEOVERRIDES`. 8048 8049 :term:`SOLIBS` 8050 Defines the suffix for shared libraries used on the target platform. 8051 By default, this suffix is ".so.*" for all Linux-based systems and is 8052 defined in the ``meta/conf/bitbake.conf`` configuration file. 8053 8054 You will see this variable referenced in the default values of 8055 ``FILES:${PN}``. 8056 8057 :term:`SOLIBSDEV` 8058 Defines the suffix for the development symbolic link (symlink) for 8059 shared libraries on the target platform. By default, this suffix is 8060 ".so" for Linux-based systems and is defined in the 8061 ``meta/conf/bitbake.conf`` configuration file. 8062 8063 You will see this variable referenced in the default values of 8064 ``FILES:${PN}-dev``. 8065 8066 :term:`SOURCE_DATE_EPOCH` 8067 This defines a date expressed in number of seconds since 8068 the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by 8069 multiple build systems to force a timestamp in built binaries. 8070 Many upstream projects already support this variable. 8071 8072 You will find more details in the `official specifications 8073 <https://reproducible-builds.org/specs/source-date-epoch/>`__. 8074 8075 A value for each recipe is computed from the sources by 8076 :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`. 8077 8078 If a recipe wishes to override the default behavior, it should set its 8079 own :term:`SOURCE_DATE_EPOCH` value:: 8080 8081 SOURCE_DATE_EPOCH = "1613559011" 8082 8083 :term:`SOURCE_MIRROR_FETCH` 8084 When you are fetching files to create a mirror of sources (i.e. 8085 creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in 8086 your ``local.conf`` configuration file ensures the source for all 8087 recipes are fetched regardless of whether or not a recipe is 8088 compatible with the configuration. A recipe is considered 8089 incompatible with the currently configured machine when either or 8090 both the :term:`COMPATIBLE_MACHINE` 8091 variable and :term:`COMPATIBLE_HOST` variables 8092 specify compatibility with a machine other than that of the current 8093 machine or host. 8094 8095 .. note:: 8096 8097 Do not set the :term:`SOURCE_MIRROR_FETCH` 8098 variable unless you are creating a source mirror. In other words, 8099 do not set the variable during a normal build. 8100 8101 :term:`SOURCE_MIRROR_URL` 8102 Defines your own :term:`PREMIRRORS` from which to 8103 first fetch source before attempting to fetch from the upstream 8104 specified in :term:`SRC_URI`. 8105 8106 To use this variable, you must globally inherit the 8107 :ref:`ref-classes-own-mirrors` class and then provide 8108 the URL to your mirrors. Here is the general syntax:: 8109 8110 INHERIT += "own-mirrors" 8111 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" 8112 8113 .. note:: 8114 8115 You can specify only a single URL in :term:`SOURCE_MIRROR_URL`. 8116 8117 .. note:: 8118 8119 If the mirror is protected behind a username and password, the 8120 :term:`build host` needs to be configured so the :term:`build system 8121 <OpenEmbedded Build System>` is able to fetch from the mirror. 8122 8123 The recommended way to do that is by setting the following parameters 8124 in ``$HOME/.netrc`` (``$HOME`` being the :term:`build host` home 8125 directory):: 8126 8127 machine example.com 8128 login <user> 8129 password <password> 8130 8131 This file requires permissions set to ``400`` or ``600`` to prevent 8132 other users from reading the file:: 8133 8134 chmod 600 "$HOME/.netrc" 8135 8136 Another method to configure the username and password is from the URL 8137 in :term:`SOURCE_MIRROR_URL` directly, with the ``user`` and ``pswd`` 8138 parameters:: 8139 8140 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror;user=<user>;pswd=<password>" 8141 8142 :term:`SPDX_ARCHIVE_PACKAGED` 8143 This option allows to add to :term:`SPDX` output compressed archives 8144 of the files in the generated target packages. 8145 8146 Such archives are available in 8147 ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst`` 8148 under the :term:`Build Directory`. 8149 8150 Enable this option as follows:: 8151 8152 SPDX_ARCHIVE_PACKAGED = "1" 8153 8154 According to our tests on release 4.1 "langdale", building 8155 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this 8156 option multiplied the size of the ``tmp/deploy/spdx`` directory by a 8157 factor of 13 (+1.6 GiB for this image), compared to just using the 8158 :ref:`ref-classes-create-spdx` class with no option. 8159 8160 Note that this option doesn't increase the size of :term:`SPDX` 8161 files in ``tmp/deploy/images/MACHINE``. 8162 8163 :term:`SPDX_ARCHIVE_SOURCES` 8164 This option allows to add to :term:`SPDX` output compressed archives 8165 of the sources for packages installed on the target. It currently 8166 only works when :term:`SPDX_INCLUDE_SOURCES` is set. 8167 8168 This is one way of fulfilling "source code access" license 8169 requirements. 8170 8171 Such source archives are available in 8172 ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst`` 8173 under the :term:`Build Directory`. 8174 8175 Enable this option as follows:: 8176 8177 SPDX_INCLUDE_SOURCES = "1" 8178 SPDX_ARCHIVE_SOURCES = "1" 8179 8180 According to our tests on release 4.1 "langdale", building 8181 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling 8182 these options multiplied the size of the ``tmp/deploy/spdx`` 8183 directory by a factor of 11 (+1.4 GiB for this image), 8184 compared to just using the :ref:`ref-classes-create-spdx` 8185 class with no option. 8186 8187 Note that using this option only marginally increases the size 8188 of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/`` 8189 (+ 0.07\% with the tested image), compared to just enabling 8190 :term:`SPDX_INCLUDE_SOURCES`. 8191 8192 :term:`SPDX_CUSTOM_ANNOTATION_VARS` 8193 This option allows to associate `SPDX annotations 8194 <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe, 8195 using the values of variables in the recipe:: 8196 8197 ANNOTATION1 = "First annotation for recipe" 8198 ANNOTATION2 = "Second annotation for recipe" 8199 SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2" 8200 8201 This will add a new block to the recipe ``.sdpx.json`` output:: 8202 8203 "annotations": [ 8204 { 8205 "annotationDate": "2023-04-18T08:32:12Z", 8206 "annotationType": "OTHER", 8207 "annotator": "Tool: oe-spdx-creator - 1.0", 8208 "comment": "ANNOTATION1=First annotation for recipe" 8209 }, 8210 { 8211 "annotationDate": "2023-04-18T08:32:12Z", 8212 "annotationType": "OTHER", 8213 "annotator": "Tool: oe-spdx-creator - 1.0", 8214 "comment": "ANNOTATION2=Second annotation for recipe" 8215 } 8216 ], 8217 8218 :term:`SPDX_INCLUDE_SOURCES` 8219 This option allows to add a description of the source files used to build 8220 the host tools and the target packages, to the ``spdx.json`` files in 8221 ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`. 8222 As a consequence, the ``spdx.json`` files under the ``by-namespace`` and 8223 ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also 8224 modified to include references to such source file descriptions. 8225 8226 Enable this option as follows:: 8227 8228 SPDX_INCLUDE_SOURCES = "1" 8229 8230 According to our tests on release 4.1 "langdale", building 8231 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling 8232 this option multiplied the total size of the ``tmp/deploy/spdx`` 8233 directory by a factor of 3 (+291 MiB for this image), 8234 and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in 8235 ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this 8236 image), compared to just using the :ref:`ref-classes-create-spdx` class 8237 with no option. 8238 8239 :term:`SPDX_NAMESPACE_PREFIX` 8240 This option could be used in order to change the prefix of ``spdxDocument`` 8241 and the prefix of ``documentNamespace``. It is set by default to 8242 ``http://spdx.org/spdxdoc``. 8243 8244 :term:`SPDX_PRETTY` 8245 This option makes the SPDX output more human-readable, using 8246 identation and newlines, instead of the default output in a 8247 single line:: 8248 8249 SPDX_PRETTY = "1" 8250 8251 The generated SPDX files are approximately 20% bigger, but 8252 this option is recommended if you want to inspect the SPDX 8253 output files with a text editor. 8254 8255 :term:`SPDXLICENSEMAP` 8256 Maps commonly used license names to their SPDX counterparts found in 8257 ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` 8258 mappings, see the ``meta/conf/licenses.conf`` file. 8259 8260 For additional information, see the :term:`LICENSE` 8261 variable. 8262 8263 :term:`SPECIAL_PKGSUFFIX` 8264 A list of prefixes for :term:`PN` used by the OpenEmbedded 8265 build system to create variants of recipes or packages. The list 8266 specifies the prefixes to strip off during certain circumstances such 8267 as the generation of the :term:`BPN` variable. 8268 8269 :term:`SPL_BINARY` 8270 The file type for the Secondary Program Loader (SPL). Some devices 8271 use an SPL from which to boot (e.g. the BeagleBone development 8272 board). For such cases, you can declare the file type of the SPL 8273 binary in the ``u-boot.inc`` include file, which is used in the 8274 U-Boot recipe. 8275 8276 The SPL file type is set to "null" by default in the ``u-boot.inc`` 8277 file as follows:: 8278 8279 # Some versions of u-boot build an SPL (Second Program Loader) image that 8280 # should be packaged along with the u-boot binary as well as placed in the 8281 # deploy directory. For those versions they can set the following variables 8282 # to allow packaging the SPL. 8283 SPL_BINARY ?= "" 8284 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}" 8285 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" 8286 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" 8287 8288 The :term:`SPL_BINARY` variable helps form 8289 various ``SPL_*`` variables used by the OpenEmbedded build system. 8290 8291 See the BeagleBone machine configuration example in the 8292 ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" 8293 section in the Yocto Project Board Support Package Developer's Guide 8294 for additional information. 8295 8296 :term:`SPL_MKIMAGE_DTCOPTS` 8297 Options for the device tree compiler passed to ``mkimage -D`` feature 8298 while creating a FIT image with the :ref:`ref-classes-uboot-sign` 8299 class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the 8300 :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option 8301 to ``mkimage``. 8302 8303 The default value is set to "" by the :ref:`ref-classes-uboot-config` 8304 class. 8305 8306 :term:`SPL_SIGN_ENABLE` 8307 Enable signing of the U-Boot FIT image. The default value is "0". 8308 This variable is used by the :ref:`ref-classes-uboot-sign` class. 8309 8310 :term:`SPL_SIGN_KEYDIR` 8311 Location of the directory containing the RSA key and certificate used for 8312 signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign` 8313 class. 8314 8315 :term:`SPL_SIGN_KEYNAME` 8316 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class 8317 for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR` 8318 directory. If we have for example a ``dev.key`` key and a ``dev.crt`` 8319 certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will 8320 have to set :term:`SPL_SIGN_KEYNAME` to ``dev``. 8321 8322 :term:`SPLASH` 8323 This variable, used by the :ref:`ref-classes-image` class, allows 8324 to choose splashscreen applications. Set it to the names of packages 8325 for such applications to use. This variable is set by default to 8326 ``psplash``. 8327 8328 :term:`SPLASH_IMAGES` 8329 This variable, used by the ``psplash`` recipe, allows to customize 8330 the default splashscreen image. 8331 8332 Specified images in PNG format are converted to ``.h`` files by the recipe, 8333 and are included in the ``psplash`` binary, so you won't find them in 8334 the root filesystem. 8335 8336 To make such a change, it is recommended to customize the 8337 ``psplash`` recipe in a custom layer. Here is an example structure for 8338 an ``ACME`` board:: 8339 8340 meta-acme/recipes-core/psplash 8341 ├── files 8342 │ └── logo-acme.png 8343 └── psplash_%.bbappend 8344 8345 And here are the contents of the ``psplash_%.bbappend`` file in 8346 this example:: 8347 8348 SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default" 8349 FILESEXTRAPATHS:prepend := "${THISDIR}/files:" 8350 8351 You could even add specific configuration options for ``psplash``, 8352 for example:: 8353 8354 EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen" 8355 8356 For information on append files, see the 8357 ":ref:`dev-manual/layers:appending other layers metadata with your layer`" 8358 section. 8359 8360 :term:`SRCREV_FORMAT` 8361 See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual. 8362 8363 :term:`SRC_URI` 8364 8365 See the BitBake manual for the initial description for this variable: 8366 :term:`bitbake:SRC_URI`. 8367 8368 The following features are added by OpenEmbedded and the Yocto Project. 8369 8370 There are standard and recipe-specific options. Here are standard ones: 8371 8372 - ``apply`` --- whether to apply the patch or not. The default 8373 action is to apply the patch. 8374 8375 - ``striplevel`` --- which striplevel to use when applying the 8376 patch. The default level is 1. 8377 8378 - ``patchdir`` --- specifies the directory in which the patch should 8379 be applied. The default is ``${``\ :term:`S`\ ``}``. 8380 8381 Here are options specific to recipes building code from a revision 8382 control system: 8383 8384 - ``mindate`` --- apply the patch only if 8385 :term:`SRCDATE` is equal to or greater than 8386 ``mindate``. 8387 8388 - ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later 8389 than ``maxdate``. 8390 8391 - ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or 8392 greater than ``minrev``. 8393 8394 - ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later 8395 than ``maxrev``. 8396 8397 - ``rev`` --- apply the patch only if :term:`SRCREV` is equal to 8398 ``rev``. 8399 8400 - ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to 8401 ``rev``. 8402 8403 .. note:: 8404 8405 If you want the build system to pick up files specified through 8406 a :term:`SRC_URI` statement from your append file, you need to be 8407 sure to extend the :term:`FILESPATH` variable by also using the 8408 :term:`FILESEXTRAPATHS` variable from within your append file. 8409 8410 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` 8411 By default, the OpenEmbedded build system automatically detects 8412 whether :term:`SRC_URI` contains files that are machine-specific. If so, 8413 the build system automatically changes :term:`PACKAGE_ARCH`. Setting this 8414 variable to "0" disables this behavior. 8415 8416 :term:`SRCDATE` 8417 The date of the source code used to build the package. This variable 8418 applies only if the source was fetched from a Source Code Manager 8419 (SCM). 8420 8421 :term:`SRCPV` 8422 The variable :term:`SRCPV` is deprecated. It was previously used to 8423 include source control information in :term:`PV` for :term:`bitbake` to 8424 work correctly but this is no longer a requirement. Source control 8425 information will be automatically included by :term:`bitbake` in the 8426 variable :term:`PKGV` during packaging if the ``+`` sign is present in 8427 :term:`PV`. 8428 8429 .. note:: 8430 8431 The :term:`SRCPV` variable used to be defined in the 8432 ``meta/conf/bitbake.conf`` configuration file in the :term:`Source 8433 Directory` as follows:: 8434 8435 SRCPV = "${@bb.fetch2.get_srcrev(d)}" 8436 8437 The ``get_srcrev`` function can still be used to include source control 8438 information in variables manually. 8439 8440 :term:`SRCREV` 8441 The revision of the source code used to build the package. This 8442 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note 8443 that if you want to build a fixed revision and you want to avoid 8444 performing a query on the remote repository every time BitBake parses 8445 your recipe, you should specify a :term:`SRCREV` that is a full revision 8446 identifier (e.g. the full SHA hash in git) and not just a tag. 8447 8448 .. note:: 8449 8450 For information on limitations when inheriting the latest revision 8451 of software using :term:`SRCREV`, see the :term:`AUTOREV` variable 8452 description and the 8453 ":ref:`dev-manual/packages:automatically incrementing a package version number`" 8454 section, which is in the Yocto Project Development Tasks Manual. 8455 8456 :term:`SRCTREECOVEREDTASKS` 8457 A list of tasks that are typically not relevant (and therefore skipped) 8458 when building using the :ref:`ref-classes-externalsrc` 8459 class. The default value as set in that class file is the set of tasks 8460 that are rarely needed when using external source:: 8461 8462 SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch" 8463 8464 The notable exception is when processing external kernel source as 8465 defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for 8466 aesthetics):: 8467 8468 SRCTREECOVEREDTASKS += "\ 8469 do_validate_branches \ 8470 do_kernel_configcheck \ 8471 do_kernel_checkout \ 8472 do_fetch \ 8473 do_unpack \ 8474 do_patch \ 8475 " 8476 8477 See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` 8478 variables for more information. 8479 8480 :term:`SSTATE_DIR` 8481 The directory for the shared state cache. 8482 8483 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` 8484 This variable allows to specify indirect dependencies to exclude 8485 from sysroots, for example to avoid the situations when a dependency on 8486 any ``-native`` recipe will pull in all dependencies of that recipe 8487 in the recipe sysroot. This behaviour might not always be wanted, 8488 for example when that ``-native`` recipe depends on build tools 8489 that are not relevant for the current recipe. 8490 8491 This way, irrelevant dependencies are ignored, which could have 8492 prevented the reuse of prebuilt artifacts stored in the Shared 8493 State Cache. 8494 8495 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` is evaluated as two regular 8496 expressions of recipe and dependency to ignore. An example 8497 is the rule in :oe_git:`meta/conf/layer.conf </openembedded-core/tree/meta/conf/layer.conf>`:: 8498 8499 # Nothing needs to depend on libc-initial 8500 # base-passwd/shadow-sysroot don't need their dependencies 8501 SSTATE_EXCLUDEDEPS_SYSROOT += "\ 8502 .*->.*-initial.* \ 8503 .*(base-passwd|shadow-sysroot)->.* \ 8504 " 8505 8506 The ``->`` substring represents the dependency between 8507 the two regular expressions. 8508 8509 :term:`SSTATE_MIRROR_ALLOW_NETWORK` 8510 If set to "1", allows fetches from mirrors that are specified in 8511 :term:`SSTATE_MIRRORS` to work even when 8512 fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to 8513 "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if 8514 you have set :term:`SSTATE_MIRRORS` to point to an internal server for 8515 your shared state cache, but you want to disable any other fetching 8516 from the network. 8517 8518 :term:`SSTATE_MIRRORS` 8519 Configures the OpenEmbedded build system to search other mirror 8520 locations for prebuilt cache data objects before building out the 8521 data. This variable works like fetcher :term:`MIRRORS` 8522 and :term:`PREMIRRORS` and points to the cache 8523 locations to check for the shared state (sstate) objects. 8524 8525 You can specify a filesystem directory or a remote URL such as HTTP 8526 or FTP. The locations you specify need to contain the shared state 8527 cache (sstate-cache) results from previous builds. The sstate-cache 8528 you point to can also be from builds on other machines. 8529 8530 When pointing to sstate build artifacts on another machine that uses 8531 a different GCC version for native builds, you must configure 8532 :term:`SSTATE_MIRRORS` with a regular expression that maps local search 8533 paths to server paths. The paths need to take into account 8534 :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class. 8535 For example, the following maps the local search path ``universal-4.9`` 8536 to the server-provided path server_url_sstate_path:: 8537 8538 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) https://server_url_sstate_path/universal-4.8/\1" 8539 8540 If a mirror uses the same structure as 8541 :term:`SSTATE_DIR`, you need to add "PATH" at the 8542 end as shown in the examples below. The build system substitutes the 8543 correct path within the directory structure:: 8544 8545 SSTATE_MIRRORS ?= "\ 8546 file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \ 8547 file://.* file:///some-local-dir/sstate/PATH" 8548 8549 .. note:: 8550 8551 If the mirror is protected behind a username and password, the 8552 :term:`build host` needs to be configured so the :term:`build system 8553 <OpenEmbedded Build System>` is able to download the sstate cache using 8554 authentication. 8555 8556 The recommended way to do that is by setting the following parameters 8557 in ``$HOME/.netrc`` (``$HOME`` being the :term:`build host` home 8558 directory):: 8559 8560 machine someserver.tld 8561 login <user> 8562 password <password> 8563 8564 This file requires permissions set to ``400`` or ``600`` to prevent 8565 other users from reading the file:: 8566 8567 chmod 600 "$HOME/.netrc" 8568 8569 Another method to configure the username and password is from the 8570 URL in :term:`SSTATE_MIRRORS` directly, with the ``user`` and ``pswd`` 8571 parameters:: 8572 8573 SSTATE_MIRRORS ?= "\ 8574 file://.* https://someserver.tld/share/sstate/PATH;user=<user>;pswd=<password>;downloadfilename=PATH \ 8575 " 8576 8577 The Yocto Project actually shares the cache data objects built by its 8578 autobuilder:: 8579 8580 SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH" 8581 8582 As such binary artifacts are built for the generic QEMU machines 8583 supported by the various Poky releases, they are less likely to be 8584 reusable in real projects building binaries optimized for a specific 8585 CPU family. 8586 8587 :term:`SSTATE_SCAN_FILES` 8588 Controls the list of files the OpenEmbedded build system scans for 8589 hardcoded installation paths. The variable uses a space-separated 8590 list of filenames (not paths) with standard wildcard characters 8591 allowed. 8592 8593 During a build, the OpenEmbedded build system creates a shared state 8594 (sstate) object during the first stage of preparing the sysroots. 8595 That object is scanned for hardcoded paths for original installation 8596 locations. The list of files that are scanned for paths is controlled 8597 by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files 8598 they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather 8599 than the variable being comprehensively set. The 8600 :ref:`ref-classes-sstate` class specifies the default list of files. 8601 8602 For details on the process, see the :ref:`ref-classes-staging` class. 8603 8604 :term:`STAGING_BASE_LIBDIR_NATIVE` 8605 Specifies the path to the ``/lib`` subdirectory of the sysroot 8606 directory for the build host. 8607 8608 :term:`STAGING_BASELIBDIR` 8609 Specifies the path to the ``/lib`` subdirectory of the sysroot 8610 directory for the target for which the current recipe is being built 8611 (:term:`STAGING_DIR_HOST`). 8612 8613 :term:`STAGING_BINDIR` 8614 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 8615 directory for the target for which the current recipe is being built 8616 (:term:`STAGING_DIR_HOST`). 8617 8618 :term:`STAGING_BINDIR_CROSS` 8619 Specifies the path to the directory containing binary configuration 8620 scripts. These scripts provide configuration information for other 8621 software that wants to make use of libraries or include files 8622 provided by the software associated with the script. 8623 8624 .. note:: 8625 8626 This style of build configuration has been largely replaced by 8627 ``pkg-config``. Consequently, if ``pkg-config`` is supported by the 8628 library to which you are linking, it is recommended you use 8629 ``pkg-config`` instead of a provided configuration script. 8630 8631 :term:`STAGING_BINDIR_NATIVE` 8632 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 8633 directory for the build host. 8634 8635 :term:`STAGING_DATADIR` 8636 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 8637 directory for the target for which the current recipe is being built 8638 (:term:`STAGING_DIR_HOST`). 8639 8640 :term:`STAGING_DATADIR_NATIVE` 8641 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 8642 directory for the build host. 8643 8644 :term:`STAGING_DIR` 8645 Helps construct the ``recipe-sysroots`` directory, which is used 8646 during packaging. 8647 8648 For information on how staging for recipe-specific sysroots occurs, 8649 see the :ref:`ref-tasks-populate_sysroot` 8650 task, the ":ref:`dev-manual/devtool:sharing files between recipes`" 8651 section in the Yocto Project Development Tasks Manual, the 8652 ":ref:`overview-manual/concepts:configuration, compilation, and staging`" 8653 section in the Yocto Project Overview and Concepts Manual, and the 8654 :term:`SYSROOT_DIRS` variable. 8655 8656 .. note:: 8657 8658 Recipes should never write files directly under the :term:`STAGING_DIR` 8659 directory because the OpenEmbedded build system manages the 8660 directory automatically. Instead, files should be installed to 8661 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` 8662 task and then the OpenEmbedded build system will stage a subset of 8663 those files into the sysroot. 8664 8665 :term:`STAGING_DIR_HOST` 8666 Specifies the path to the sysroot directory for the system on which 8667 the component is built to run (the system that hosts the component). 8668 For most recipes, this sysroot is the one in which that recipe's 8669 :ref:`ref-tasks-populate_sysroot` task copies 8670 files. Exceptions include ``-native`` recipes, where the 8671 :ref:`ref-tasks-populate_sysroot` task instead uses 8672 :term:`STAGING_DIR_NATIVE`. Depending on 8673 the type of recipe and the build target, :term:`STAGING_DIR_HOST` can 8674 have the following values: 8675 8676 - For recipes building for the target machine, the value is 8677 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}". 8678 8679 - For native recipes building for the build host, the value is empty 8680 given the assumption that when building for the build host, the 8681 build host's own directories should be used. 8682 8683 .. note:: 8684 8685 ``-native`` recipes are not installed into host paths like such 8686 as ``/usr``. Rather, these recipes are installed into 8687 :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes, 8688 standard build environment variables such as 8689 :term:`CPPFLAGS` and 8690 :term:`CFLAGS` are set up so that both host paths 8691 and :term:`STAGING_DIR_NATIVE` are searched for libraries and 8692 headers using, for example, GCC's ``-isystem`` option. 8693 8694 Thus, the emphasis is that the ``STAGING_DIR*`` variables 8695 should be viewed as input variables by tasks such as 8696 :ref:`ref-tasks-configure`, 8697 :ref:`ref-tasks-compile`, and 8698 :ref:`ref-tasks-install`. Having the real system 8699 root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense 8700 for ``-native`` recipes, as they make use of host headers and 8701 libraries. 8702 8703 Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`. 8704 8705 :term:`STAGING_DIR_NATIVE` 8706 Specifies the path to the sysroot directory used when building 8707 components that run on the build host itself. 8708 8709 The default value is ``"${RECIPE_SYSROOT_NATIVE}"``, 8710 check :term:`RECIPE_SYSROOT_NATIVE`. 8711 8712 :term:`STAGING_DIR_TARGET` 8713 Specifies the path to the sysroot used for the system for which the 8714 component generates code. For components that do not generate code, 8715 which is the majority, :term:`STAGING_DIR_TARGET` is set to match 8716 :term:`STAGING_DIR_HOST`. 8717 8718 Some recipes build binaries that can run on the target system but those 8719 binaries in turn generate code for another different system (e.g. 8720 :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU, 8721 the primary system is referred to as the "HOST" and the secondary, or 8722 different, system is referred to as the "TARGET". Thus, the binaries 8723 run on the "HOST" system and generate binaries for the "TARGET" 8724 system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used 8725 for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the 8726 sysroot used for the "TARGET" system. 8727 8728 :term:`STAGING_ETCDIR_NATIVE` 8729 Specifies the path to the ``/etc`` subdirectory of the sysroot 8730 directory for the build host. 8731 8732 :term:`STAGING_EXECPREFIXDIR` 8733 Specifies the path to the ``/usr`` subdirectory of the sysroot 8734 directory for the target for which the current recipe is being built 8735 (:term:`STAGING_DIR_HOST`). 8736 8737 :term:`STAGING_INCDIR` 8738 Specifies the path to the ``/usr/include`` subdirectory of the 8739 sysroot directory for the target for which the current recipe being 8740 built (:term:`STAGING_DIR_HOST`). 8741 8742 :term:`STAGING_INCDIR_NATIVE` 8743 Specifies the path to the ``/usr/include`` subdirectory of the 8744 sysroot directory for the build host. 8745 8746 :term:`STAGING_KERNEL_BUILDDIR` 8747 Points to the directory containing the kernel build artifacts. 8748 Recipes building software that needs to access kernel build artifacts 8749 (e.g. ``systemtap-uprobes``) can look in the directory specified with 8750 the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts 8751 after the kernel has been built. 8752 8753 :term:`STAGING_KERNEL_DIR` 8754 The directory with kernel headers that are required to build 8755 out-of-tree modules. 8756 8757 :term:`STAGING_LIBDIR` 8758 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 8759 directory for the target for which the current recipe is being built 8760 (:term:`STAGING_DIR_HOST`). 8761 8762 :term:`STAGING_LIBDIR_NATIVE` 8763 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 8764 directory for the build host. 8765 8766 :term:`STAMP` 8767 Specifies the base path used to create recipe stamp files. The path 8768 to an actual stamp file is constructed by evaluating this string and 8769 then appending additional information. Currently, the default 8770 assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf`` 8771 file is:: 8772 8773 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" 8774 8775 For information on how BitBake uses stamp files to determine if a 8776 task should be rerun, see the 8777 ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`" 8778 section in the Yocto Project Overview and Concepts Manual. 8779 8780 See :term:`STAMPS_DIR`, 8781 :term:`MULTIMACH_TARGET_SYS`, 8782 :term:`PN`, :term:`EXTENDPE`, 8783 :term:`PV`, and :term:`PR` for related variable 8784 information. 8785 8786 :term:`STAMPCLEAN` 8787 See :term:`bitbake:STAMPCLEAN` in the BitBake manual. 8788 8789 :term:`STAMPS_DIR` 8790 Specifies the base directory in which the OpenEmbedded build system 8791 places stamps. The default directory is ``${TMPDIR}/stamps``. 8792 8793 :term:`STRIP` 8794 The minimal command and arguments to run ``strip``, which is used to 8795 strip symbols. 8796 8797 :term:`SUMMARY` 8798 The short (72 characters or less) summary of the binary package for 8799 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, 8800 :term:`SUMMARY` is used to define the 8801 :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is 8802 not set in the recipe. 8803 8804 :term:`SVNDIR` 8805 The directory in which files checked out of a Subversion system are 8806 stored. 8807 8808 :term:`SYSLINUX_DEFAULT_CONSOLE` 8809 Specifies the kernel boot default console. If you want to use a 8810 console other than the default, set this variable in your recipe as 8811 follows where "X" is the console number you want to use:: 8812 8813 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" 8814 8815 The :ref:`ref-classes-syslinux` class initially sets 8816 this variable to null but then checks for a value later. 8817 8818 :term:`SYSLINUX_OPTS` 8819 Lists additional options to add to the syslinux file. You need to set 8820 this variable in your recipe. If you want to list multiple options, 8821 separate the options with a semicolon character (``;``). 8822 8823 The :ref:`ref-classes-syslinux` class uses this variable 8824 to create a set of options. 8825 8826 :term:`SYSLINUX_SERIAL` 8827 Specifies the alternate serial port or turns it off. To turn off 8828 serial, set this variable to an empty string in your recipe. The 8829 variable's default value is set in the 8830 :ref:`ref-classes-syslinux` class as follows:: 8831 8832 SYSLINUX_SERIAL ?= "0 115200" 8833 8834 The class checks for and uses the variable as needed. 8835 8836 :term:`SYSLINUX_SERIAL_TTY` 8837 Specifies the alternate console=tty... kernel boot argument. The 8838 variable's default value is set in the :ref:`ref-classes-syslinux` 8839 class as follows:: 8840 8841 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" 8842 8843 The class checks for and uses the variable as needed. 8844 8845 :term:`SYSLINUX_SPLASH` 8846 An ``.LSS`` file used as the background for the VGA boot menu when 8847 you use the boot menu. You need to set this variable in your recipe. 8848 8849 The :ref:`ref-classes-syslinux` class checks for this 8850 variable and if found, the OpenEmbedded build system installs the 8851 splash screen. 8852 8853 :term:`SYSROOT_DESTDIR` 8854 Points to the temporary directory under the work directory (default 8855 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``") 8856 where the files populated into the sysroot are assembled during the 8857 :ref:`ref-tasks-populate_sysroot` task. 8858 8859 :term:`SYSROOT_DIRS` 8860 Directories that are staged into the sysroot by the 8861 :ref:`ref-tasks-populate_sysroot` task. By 8862 default, the following directories are staged:: 8863 8864 SYSROOT_DIRS = " \ 8865 ${includedir} \ 8866 ${libdir} \ 8867 ${base_libdir} \ 8868 ${nonarch_base_libdir} \ 8869 ${datadir} \ 8870 /sysroot-only \ 8871 " 8872 8873 Consider the following example in which you need to manipulate this variable. 8874 Assume you have a recipe ``A`` that provides a shared library ``.so.*`` that is 8875 installed into a custom folder other than "``${libdir}``" 8876 or "``${base_libdir}``", let's say "``/opt/lib``". 8877 8878 .. note:: 8879 8880 This is not a recommended way to deal with shared libraries, but this 8881 is just to show the usefulness of setting :term:`SYSROOT_DIRS`. 8882 8883 When a recipe ``B`` :term:`DEPENDS` on ``A``, it means what is in 8884 :term:`SYSROOT_DIRS` will be copied from :term:`D` of the recipe ``A`` 8885 into ``B``'s :term:`SYSROOT_DESTDIR` that is "``${WORKDIR}/sysroot-destdir``". 8886 8887 Now, since ``/opt/lib`` is not in :term:`SYSROOT_DIRS`, it will never be copied to 8888 ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So, 8889 the linking process will fail. 8890 8891 To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`:: 8892 8893 SYSROOT_DIRS:append = " /opt/lib" 8894 8895 .. note:: 8896 Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail 8897 because the linker does not know that location, since :term:`TARGET_LDFLAGS` 8898 doesn't contain it (if your recipe is for the target). Therefore, so you should add:: 8899 8900 TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib" 8901 8902 :term:`SYSROOT_DIRS_IGNORE` 8903 Directories that are not staged into the sysroot by the 8904 :ref:`ref-tasks-populate_sysroot` task. You 8905 can use this variable to exclude certain subdirectories of 8906 directories listed in :term:`SYSROOT_DIRS` from 8907 staging. By default, the following directories are not staged:: 8908 8909 SYSROOT_DIRS_IGNORE = " \ 8910 ${mandir} \ 8911 ${docdir} \ 8912 ${infodir} \ 8913 ${datadir}/X11/locale \ 8914 ${datadir}/applications \ 8915 ${datadir}/bash-completion \ 8916 ${datadir}/fonts \ 8917 ${datadir}/gtk-doc/html \ 8918 ${datadir}/installed-tests \ 8919 ${datadir}/locale \ 8920 ${datadir}/pixmaps \ 8921 ${datadir}/terminfo \ 8922 ${libdir}/${BPN}/ptest \ 8923 " 8924 8925 :term:`SYSROOT_DIRS_NATIVE` 8926 Extra directories staged into the sysroot by the 8927 :ref:`ref-tasks-populate_sysroot` task for 8928 ``-native`` recipes, in addition to those specified in 8929 :term:`SYSROOT_DIRS`. By default, the following 8930 extra directories are staged:: 8931 8932 SYSROOT_DIRS_NATIVE = " \ 8933 ${bindir} \ 8934 ${sbindir} \ 8935 ${base_bindir} \ 8936 ${base_sbindir} \ 8937 ${libexecdir} \ 8938 ${sysconfdir} \ 8939 ${localstatedir} \ 8940 " 8941 8942 .. note:: 8943 8944 Programs built by ``-native`` recipes run directly from the sysroot 8945 (:term:`STAGING_DIR_NATIVE`), which is why additional directories 8946 containing program executables and supporting files need to be staged. 8947 8948 :term:`SYSROOT_PREPROCESS_FUNCS` 8949 A list of functions to execute after files are staged into the 8950 sysroot. These functions are usually used to apply additional 8951 processing on the staged files, or to stage additional files. 8952 8953 :term:`SYSTEMD_AUTO_ENABLE` 8954 When inheriting the :ref:`ref-classes-systemd` class, 8955 this variable specifies whether the specified service in 8956 :term:`SYSTEMD_SERVICE` should start 8957 automatically or not. By default, the service is enabled to 8958 automatically start at boot time. The default setting is in the 8959 :ref:`ref-classes-systemd` class as follows:: 8960 8961 SYSTEMD_AUTO_ENABLE ??= "enable" 8962 8963 You can disable the service by setting the variable to "disable". 8964 8965 :term:`SYSTEMD_BOOT_CFG` 8966 When :term:`EFI_PROVIDER` is set to 8967 "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the 8968 configuration file that should be used. By default, the 8969 :ref:`ref-classes-systemd-boot` class sets the 8970 :term:`SYSTEMD_BOOT_CFG` as follows:: 8971 8972 SYSTEMD_BOOT_CFG ?= "${S}/loader.conf" 8973 8974 For information on Systemd-boot, see the `Systemd-boot 8975 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8976 8977 :term:`SYSTEMD_BOOT_ENTRIES` 8978 When :term:`EFI_PROVIDER` is set to 8979 "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a 8980 list of entry files (``*.conf``) to install that contain one boot 8981 entry per file. By default, the :ref:`ref-classes-systemd-boot` class 8982 sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows:: 8983 8984 SYSTEMD_BOOT_ENTRIES ?= "" 8985 8986 For information on Systemd-boot, see the `Systemd-boot 8987 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8988 8989 :term:`SYSTEMD_BOOT_TIMEOUT` 8990 When :term:`EFI_PROVIDER` is set to 8991 "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the 8992 boot menu timeout in seconds. By default, the 8993 :ref:`ref-classes-systemd-boot` class sets the 8994 :term:`SYSTEMD_BOOT_TIMEOUT` as follows:: 8995 8996 SYSTEMD_BOOT_TIMEOUT ?= "10" 8997 8998 For information on Systemd-boot, see the `Systemd-boot 8999 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 9000 9001 :term:`SYSTEMD_DEFAULT_TARGET` 9002 9003 This variable allows to set the default unit that systemd starts at bootup. 9004 Usually, this is either ``multi-user.target`` or ``graphical.target``. 9005 This works by creating a ``default.target`` symbolic link to the chosen systemd 9006 target file. 9007 9008 See `systemd's documentation 9009 <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__ 9010 for details. 9011 9012 For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb 9013 </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>` 9014 recipe:: 9015 9016 SYSTEMD_DEFAULT_TARGET = "graphical.target" 9017 9018 :term:`SYSTEMD_PACKAGES` 9019 When inheriting the :ref:`ref-classes-systemd` class, 9020 this variable locates the systemd unit files when they are not found 9021 in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES` 9022 variable is set such that the systemd unit files are assumed to 9023 reside in the recipes main package:: 9024 9025 SYSTEMD_PACKAGES ?= "${PN}" 9026 9027 If these unit files are not in this recipe's main package, you need 9028 to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which 9029 the build system can find the systemd unit files. 9030 9031 :term:`SYSTEMD_SERVICE` 9032 When inheriting the :ref:`ref-classes-systemd` class, 9033 this variable specifies the systemd service name for a package. 9034 9035 Multiple services can be specified, each one separated by a space. 9036 9037 When you specify this file in your recipe, use a package name 9038 override to indicate the package to which the value applies. Here is 9039 an example from the connman recipe:: 9040 9041 SYSTEMD_SERVICE:${PN} = "connman.service" 9042 9043 The package overrides that can be specified are directly related to the value of 9044 :term:`SYSTEMD_PACKAGES`. Overrides not included in :term:`SYSTEMD_PACKAGES` 9045 will be silently ignored. 9046 9047 :term:`SYSVINIT_ENABLED_GETTYS` 9048 When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, 9049 specifies a space-separated list of the virtual terminals that should 9050 run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming 9051 :term:`USE_VT` is not set to "0". 9052 9053 The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only 9054 run a getty on the first virtual terminal). 9055 9056 :term:`T` 9057 This variable points to a directory were BitBake places temporary 9058 files, which consist mostly of task logs and scripts, when building a 9059 particular recipe. The variable is typically set as follows:: 9060 9061 T = "${WORKDIR}/temp" 9062 9063 The :term:`WORKDIR` is the directory into which 9064 BitBake unpacks and builds the recipe. The default ``bitbake.conf`` 9065 file sets this variable. 9066 9067 The :term:`T` variable is not to be confused with the 9068 :term:`TMPDIR` variable, which points to the root of 9069 the directory tree where BitBake places the output of an entire 9070 build. 9071 9072 :term:`TARGET_ARCH` 9073 The target machine's architecture. The OpenEmbedded build system 9074 supports many architectures. Here is an example list of architectures 9075 supported. This list is by no means complete as the architecture is 9076 configurable: 9077 9078 - arm 9079 - i586 9080 - x86_64 9081 - powerpc 9082 - powerpc64 9083 - mips 9084 - mipsel 9085 9086 For additional information on machine architectures, see the 9087 :term:`TUNE_ARCH` variable. 9088 9089 :term:`TARGET_AS_ARCH` 9090 Specifies architecture-specific assembler flags for the target 9091 system. :term:`TARGET_AS_ARCH` is initialized from 9092 :term:`TUNE_ASARGS` by default in the BitBake 9093 configuration file (``meta/conf/bitbake.conf``):: 9094 9095 TARGET_AS_ARCH = "${TUNE_ASARGS}" 9096 9097 :term:`TARGET_CC_ARCH` 9098 Specifies architecture-specific C compiler flags for the target 9099 system. :term:`TARGET_CC_ARCH` is initialized from 9100 :term:`TUNE_CCARGS` by default. 9101 9102 .. note:: 9103 9104 It is a common workaround to append :term:`LDFLAGS` to 9105 :term:`TARGET_CC_ARCH` in recipes that build software for the target that 9106 would not otherwise respect the exported :term:`LDFLAGS` variable. 9107 9108 :term:`TARGET_CC_KERNEL_ARCH` 9109 This is a specific kernel compiler flag for a CPU or Application 9110 Binary Interface (ABI) tune. The flag is used rarely and only for 9111 cases where a userspace :term:`TUNE_CCARGS` is not 9112 compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH` 9113 variable allows the kernel (and associated modules) to use a 9114 different configuration. See the 9115 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the 9116 :term:`Source Directory` for an example. 9117 9118 :term:`TARGET_CFLAGS` 9119 Specifies the flags to pass to the C compiler when building for the 9120 target. When building in the target context, 9121 :term:`CFLAGS` is set to the value of this variable by 9122 default. 9123 9124 Additionally, the SDK's environment setup script sets the :term:`CFLAGS` 9125 variable in the environment to the :term:`TARGET_CFLAGS` value so that 9126 executables built using the SDK also have the flags applied. 9127 9128 :term:`TARGET_CPPFLAGS` 9129 Specifies the flags to pass to the C pre-processor (i.e. to both the 9130 C and the C++ compilers) when building for the target. When building 9131 in the target context, :term:`CPPFLAGS` is set to the 9132 value of this variable by default. 9133 9134 Additionally, the SDK's environment setup script sets the 9135 :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS` 9136 value so that executables built using the SDK also have the flags 9137 applied. 9138 9139 :term:`TARGET_CXXFLAGS` 9140 Specifies the flags to pass to the C++ compiler when building for the 9141 target. When building in the target context, 9142 :term:`CXXFLAGS` is set to the value of this variable 9143 by default. 9144 9145 Additionally, the SDK's environment setup script sets the 9146 :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS` 9147 value so that executables built using the SDK also have the flags 9148 applied. 9149 9150 :term:`TARGET_DBGSRC_DIR` 9151 Specifies the target path to debug source files. The default is 9152 ``/usr/src/debug/${PN}/${PV}``. 9153 9154 :term:`TARGET_FPU` 9155 Specifies the method for handling FPU code. For FPU-less targets, 9156 which include most ARM CPUs, the variable must be set to "soft". If 9157 not, the kernel emulation gets used, which results in a performance 9158 penalty. 9159 9160 :term:`TARGET_LD_ARCH` 9161 Specifies architecture-specific linker flags for the target system. 9162 :term:`TARGET_LD_ARCH` is initialized from 9163 :term:`TUNE_LDARGS` by default in the BitBake 9164 configuration file (``meta/conf/bitbake.conf``):: 9165 9166 TARGET_LD_ARCH = "${TUNE_LDARGS}" 9167 9168 :term:`TARGET_LDFLAGS` 9169 Specifies the flags to pass to the linker when building for the 9170 target. When building in the target context, 9171 :term:`LDFLAGS` is set to the value of this variable 9172 by default. 9173 9174 Additionally, the SDK's environment setup script sets the 9175 :term:`LDFLAGS` variable in the environment to the 9176 :term:`TARGET_LDFLAGS` value so that executables built using the SDK also 9177 have the flags applied. 9178 9179 :term:`TARGET_OS` 9180 Specifies the target's operating system. The variable can be set to 9181 "linux" for glibc-based systems (GNU C Library) and to "linux-musl" 9182 for musl libc. For ARM/EABI targets, the possible values are 9183 "linux-gnueabi" and "linux-musleabi". 9184 9185 :term:`TARGET_PREFIX` 9186 Specifies the prefix used for the toolchain binary target tools. 9187 9188 Depending on the type of recipe and the build target, 9189 :term:`TARGET_PREFIX` is set as follows: 9190 9191 - For recipes building for the target machine, the value is 9192 "${:term:`TARGET_SYS`}-". 9193 9194 - For native recipes, the build system sets the variable to the 9195 value of :term:`BUILD_PREFIX`. 9196 9197 - For native SDK recipes (:ref:`ref-classes-nativesdk`), 9198 the build system sets the variable to the value of :term:`SDK_PREFIX`. 9199 9200 :term:`TARGET_SYS` 9201 Specifies the system, including the architecture and the operating 9202 system, for which the build is occurring in the context of the 9203 current recipe. 9204 9205 The OpenEmbedded build system automatically sets this variable based 9206 on :term:`TARGET_ARCH`, 9207 :term:`TARGET_VENDOR`, and 9208 :term:`TARGET_OS` variables. 9209 9210 .. note:: 9211 9212 You do not need to set the :term:`TARGET_SYS` variable yourself. 9213 9214 Consider these two examples: 9215 9216 - Given a native recipe on a 32-bit, x86 machine running Linux, the 9217 value is "i686-linux". 9218 9219 - Given a recipe being built for a little-endian, MIPS target 9220 running Linux, the value might be "mipsel-linux". 9221 9222 :term:`TARGET_VENDOR` 9223 Specifies the name of the target vendor. 9224 9225 :term:`TCLIBC` 9226 Specifies the GNU standard C library (``libc``) variant to use during 9227 the build process. 9228 9229 You can select "glibc", "musl", "newlib", or "baremetal". 9230 9231 :term:`TCMODE` 9232 Specifies the toolchain selector. :term:`TCMODE` controls the 9233 characteristics of the generated packages and images by telling the 9234 OpenEmbedded build system which toolchain profile to use. By default, 9235 the OpenEmbedded build system builds its own internal toolchain. The 9236 variable's default value is "default", which uses that internal 9237 toolchain. 9238 9239 .. note:: 9240 9241 If :term:`TCMODE` is set to a value other than "default", then it is your 9242 responsibility to ensure that the toolchain is compatible with the 9243 default toolchain. Using older or newer versions of these 9244 components might cause build problems. See 9245 :doc:`Release Information </migration-guides/index>` for your 9246 version of the Yocto Project, to find the specific components with 9247 which the toolchain must be compatible. 9248 9249 The :term:`TCMODE` variable is similar to :term:`TCLIBC`, 9250 which controls the variant of the GNU standard C library (``libc``) 9251 used during the build process: ``glibc`` or ``musl``. 9252 9253 With additional layers, it is possible to use a pre-compiled external 9254 toolchain. One example is the Sourcery G++ Toolchain. The support for 9255 this toolchain resides in the separate Mentor Graphics 9256 ``meta-sourcery`` layer at 9257 https://github.com/MentorEmbedded/meta-sourcery/. 9258 9259 The layer's ``README`` file contains information on how to use the 9260 Sourcery G++ Toolchain as an external toolchain. You will have to 9261 add the layer to your ``bblayers.conf`` file and then set the 9262 :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to 9263 the location of the toolchain. 9264 9265 The fundamentals used for this example apply to any external 9266 toolchain. You can use ``meta-sourcery`` as a template for adding 9267 support for other external toolchains. 9268 9269 In addition to toolchain configuration, you will also need a 9270 corresponding toolchain recipe file. This recipe file needs to package 9271 up any pre-built objects in the toolchain such as ``libgcc``, 9272 ``libstdcc++``, any locales, and ``libc``. 9273 9274 :term:`TC_CXX_RUNTIME` 9275 Specifies the C/C++ STL and runtime variant to use during 9276 the build process. Default value is 'gnu' 9277 9278 You can select "gnu", "llvm", or "android". 9279 9280 :term:`TEMPLATECONF` 9281 Specifies the directory used by the build system to find templates 9282 from which to build the ``bblayers.conf`` and ``local.conf`` files. 9283 Use this variable if you wish to customize such files, and the default 9284 BitBake targets shown when sourcing the ``oe-init-build-env`` script. 9285 9286 For details, see the 9287 :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory` 9288 section in the Yocto Project Development Tasks manual. 9289 9290 .. note:: 9291 9292 You must set this variable in the external environment in order 9293 for it to work. 9294 9295 :term:`TEST_EXPORT_DIR` 9296 The location the OpenEmbedded build system uses to export tests when 9297 the :term:`TEST_EXPORT_ONLY` variable is set 9298 to "1". 9299 9300 The :term:`TEST_EXPORT_DIR` variable defaults to 9301 ``"${TMPDIR}/testimage/${PN}"``. 9302 9303 :term:`TEST_EXPORT_ONLY` 9304 Specifies to export the tests only. Set this variable to "1" if you 9305 do not want to run the tests but you want them to be exported in a 9306 manner that you to run them outside of the build system. 9307 9308 :term:`TEST_LOG_DIR` 9309 Holds the SSH log and the boot log for QEMU machines. The 9310 :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``. 9311 9312 .. note:: 9313 9314 Actual test results reside in the task log (``log.do_testimage``), 9315 which is in the ``${WORKDIR}/temp/`` directory. 9316 9317 :term:`TEST_POWERCONTROL_CMD` 9318 For automated hardware testing, specifies the command to use to 9319 control the power of the target machine under test. Typically, this 9320 command would point to a script that performs the appropriate action 9321 (e.g. interacting with a web-enabled power strip). The specified 9322 command should expect to receive as the last argument "off", "on" or 9323 "cycle" specifying to power off, on, or cycle (power off and then 9324 power on) the device, respectively. 9325 9326 :term:`TEST_POWERCONTROL_EXTRA_ARGS` 9327 For automated hardware testing, specifies additional arguments to 9328 pass through to the command specified in 9329 :term:`TEST_POWERCONTROL_CMD`. Setting 9330 :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you 9331 wish, for example, to separate the machine-specific and 9332 non-machine-specific parts of the arguments. 9333 9334 :term:`TEST_QEMUBOOT_TIMEOUT` 9335 The time in seconds allowed for an image to boot before automated 9336 runtime tests begin to run against an image. The default timeout 9337 period to allow the boot process to reach the login prompt is 500 9338 seconds. You can specify a different value in the ``local.conf`` 9339 file. 9340 9341 For more information on testing images, see the 9342 ":ref:`test-manual/runtime-testing:performing automated runtime testing`" 9343 section in the Yocto Project Test Environment Manual. 9344 9345 :term:`TEST_SERIALCONTROL_CMD` 9346 For automated hardware testing, specifies the command to use to 9347 connect to the serial console of the target machine under test. This 9348 command simply needs to connect to the serial console and forward 9349 that connection to standard input and output as any normal terminal 9350 program does. 9351 9352 For example, to use the Picocom terminal program on serial device 9353 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: 9354 9355 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" 9356 9357 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` 9358 For automated hardware testing, specifies additional arguments to 9359 pass through to the command specified in 9360 :term:`TEST_SERIALCONTROL_CMD`. Setting 9361 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you 9362 wish, for example, to separate the machine-specific and 9363 non-machine-specific parts of the command. 9364 9365 :term:`TEST_SERVER_IP` 9366 The IP address of the build machine (host machine). This IP address 9367 is usually automatically detected. However, if detection fails, this 9368 variable needs to be set to the IP address of the build machine (i.e. 9369 where the build is taking place). 9370 9371 .. note:: 9372 9373 The :term:`TEST_SERVER_IP` variable is only used for a small number of 9374 tests such as the "dnf" test suite, which needs to download packages 9375 from ``WORKDIR/oe-rootfs-repo``. 9376 9377 :term:`TEST_SUITES` 9378 An ordered list of tests (modules) to run against an image when 9379 performing automated runtime testing. 9380 9381 The OpenEmbedded build system provides a core set of tests that can 9382 be used against images. 9383 9384 .. note:: 9385 9386 Currently, there is only support for running these tests under 9387 QEMU. 9388 9389 Tests include ``ping``, ``ssh``, ``df`` among others. You can add 9390 your own tests to the list of tests by appending :term:`TEST_SUITES` as 9391 follows:: 9392 9393 TEST_SUITES:append = " mytest" 9394 9395 Alternatively, you can 9396 provide the "auto" option to have all applicable tests run against 9397 the image:: 9398 9399 TEST_SUITES:append = " auto" 9400 9401 Using this option causes the 9402 build system to automatically run tests that are applicable to the 9403 image. Tests that are not applicable are skipped. 9404 9405 The order in which tests are run is important. Tests that depend on 9406 another test must appear later in the list than the test on which 9407 they depend. For example, if you append the list of tests with two 9408 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on 9409 ``test_A``, then you must order the tests as follows:: 9410 9411 TEST_SUITES = "test_A test_B" 9412 9413 For more information on testing images, see the 9414 ":ref:`test-manual/runtime-testing:performing automated runtime testing`" 9415 section in the Yocto Project Test Environment Manual. 9416 9417 :term:`TEST_TARGET` 9418 Specifies the target controller to use when running tests against a 9419 test image. The default controller to use is "qemu":: 9420 9421 TEST_TARGET = "qemu" 9422 9423 A target controller is a class that defines how an image gets 9424 deployed on a target and how a target is started. A layer can extend 9425 the controllers by adding a module in the layer's 9426 ``/lib/oeqa/controllers`` directory and by inheriting the 9427 ``BaseTarget`` class, which is an abstract class that cannot be used 9428 as a value of :term:`TEST_TARGET`. 9429 9430 You can provide the following arguments with :term:`TEST_TARGET`: 9431 9432 - *"qemu":* Boots a QEMU image and runs the tests. See the 9433 ":ref:`test-manual/runtime-testing:enabling runtime tests on qemu`" section 9434 in the Yocto Project Test Environment Manual for more 9435 information. 9436 9437 - *"simpleremote":* Runs the tests on target hardware that is 9438 already up and running. The hardware can be on the network or it 9439 can be a device running an image on QEMU. You must also set 9440 :term:`TEST_TARGET_IP` when you use 9441 "simpleremote". 9442 9443 .. note:: 9444 9445 This argument is defined in 9446 ``meta/lib/oeqa/controllers/simpleremote.py``. 9447 9448 For information on running tests on hardware, see the 9449 ":ref:`test-manual/runtime-testing:enabling runtime tests on hardware`" 9450 section in the Yocto Project Test Environment Manual. 9451 9452 :term:`TEST_TARGET_IP` 9453 The IP address of your hardware under test. The :term:`TEST_TARGET_IP` 9454 variable has no effect when :term:`TEST_TARGET` is 9455 set to "qemu". 9456 9457 When you specify the IP address, you can also include a port. Here is 9458 an example:: 9459 9460 TEST_TARGET_IP = "192.168.1.4:2201" 9461 9462 Specifying a port is 9463 useful when SSH is started on a non-standard port or in cases when 9464 your hardware under test is behind a firewall or network that is not 9465 directly accessible from your host and you need to do port address 9466 translation. 9467 9468 :term:`TESTIMAGE_AUTO` 9469 Automatically runs the series of automated tests for images when an 9470 image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes 9471 any image that successfully builds to automatically boot under QEMU. 9472 Using the variable also adds in dependencies so that any SDK for 9473 which testing is requested is automatically built first. 9474 9475 These tests are written in Python making use of the ``unittest`` 9476 module, and the majority of them run commands on the target system 9477 over ``ssh``. You can set this variable to "1" in your ``local.conf`` 9478 file in the :term:`Build Directory` to have the 9479 OpenEmbedded build system automatically run these tests after an 9480 image successfully builds: 9481 9482 TESTIMAGE_AUTO = "1" 9483 9484 For more information 9485 on enabling, running, and writing these tests, see the 9486 ":ref:`test-manual/runtime-testing:performing automated runtime testing`" 9487 section in the Yocto Project Test Environment Manual and the 9488 ":ref:`ref-classes-testimage`" section. 9489 9490 :term:`TESTIMAGE_FAILED_QA_ARTIFACTS` 9491 When using the :ref:`ref-classes-testimage` class, the variable 9492 :term:`TESTIMAGE_FAILED_QA_ARTIFACTS` lists space-separated paths on the 9493 target to retrieve onto the host. 9494 9495 :term:`THISDIR` 9496 The directory in which the file BitBake is currently parsing is 9497 located. Do not manually set this variable. 9498 9499 :term:`TIME` 9500 The time the build was started. Times appear using the hour, minute, 9501 and second (HMS) format (e.g. "140159" for one minute and fifty-nine 9502 seconds past 1400 hours). 9503 9504 :term:`TMPDIR` 9505 This variable is the base directory the OpenEmbedded build system 9506 uses for all build output and intermediate files (other than the 9507 shared state cache). By default, the :term:`TMPDIR` variable points to 9508 ``tmp`` within the :term:`Build Directory`. 9509 9510 If you want to establish this directory in a location other than the 9511 default, you can uncomment and edit the following statement in the 9512 ``conf/local.conf`` file in the :term:`Source Directory`:: 9513 9514 #TMPDIR = "${TOPDIR}/tmp" 9515 9516 An example use for this scenario is to set :term:`TMPDIR` to a local disk, 9517 which does not use NFS, while having the :term:`Build Directory` use NFS. 9518 9519 The filesystem used by :term:`TMPDIR` must have standard filesystem 9520 semantics (i.e. mixed-case files are unique, POSIX file locking, and 9521 persistent inodes). Due to various issues with NFS and bugs in some 9522 implementations, NFS does not meet this minimum requirement. 9523 Consequently, :term:`TMPDIR` cannot be on NFS. 9524 9525 :term:`TOOLCHAIN_HOST_TASK` 9526 This variable lists packages the OpenEmbedded build system uses when 9527 building an SDK, which contains a cross-development environment. The 9528 packages specified by this variable are part of the toolchain set 9529 that runs on the :term:`SDKMACHINE`, and each 9530 package should usually have the prefix ``nativesdk-``. For example, 9531 consider the following command when building an SDK:: 9532 9533 $ bitbake -c populate_sdk imagename 9534 9535 In this case, a default list of packages is 9536 set in this variable, but you can add additional packages to the 9537 list. See the 9538 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section 9539 in the Yocto Project Application Development and the Extensible 9540 Software Development Kit (eSDK) manual for more information. 9541 9542 For background information on cross-development toolchains in the 9543 Yocto Project development environment, see the 9544 ":ref:`sdk-manual/intro:the cross-development toolchain`" 9545 section in the Yocto Project Overview and Concepts Manual. For 9546 information on setting up a cross-development environment, see the 9547 :doc:`/sdk-manual/index` manual. 9548 9549 Note that this variable applies to building an SDK, not an eSDK, 9550 in which case the :term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be 9551 used instead. 9552 9553 :term:`TOOLCHAIN_HOST_TASK_ESDK` 9554 This variable allows to extend what is installed in the host 9555 portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK` 9556 applying to SDKs. 9557 9558 :term:`TOOLCHAIN_OPTIONS` 9559 This variable holds extra options passed to the compiler and the linker 9560 for non ``-native`` recipes as they have to point to their custom 9561 ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`:: 9562 9563 TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}" 9564 9565 Native recipes don't need this variable to be set, as they are 9566 built for the host machine with the native compiler. 9567 9568 :term:`TOOLCHAIN_OUTPUTNAME` 9569 This variable defines the name used for the toolchain output. The 9570 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets 9571 the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:: 9572 9573 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" 9574 9575 See 9576 the :term:`SDK_NAME` and 9577 :term:`SDK_VERSION` variables for additional 9578 information. 9579 9580 :term:`TOOLCHAIN_TARGET_TASK` 9581 This variable lists packages the OpenEmbedded build system uses when 9582 it creates the target part of an SDK (i.e. the part built for the 9583 target hardware), which includes libraries and headers. Use this 9584 variable to add individual packages to the part of the SDK that runs 9585 on the target. See the 9586 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section 9587 in the Yocto Project Application Development and the Extensible 9588 Software Development Kit (eSDK) manual for more information. 9589 9590 For background information on cross-development toolchains in the 9591 Yocto Project development environment, see the 9592 ":ref:`sdk-manual/intro:the cross-development toolchain`" 9593 section in the Yocto Project Overview and Concepts Manual. For 9594 information on setting up a cross-development environment, see the 9595 :doc:`/sdk-manual/index` manual. 9596 9597 :term:`TOPDIR` 9598 See :term:`bitbake:TOPDIR` in the BitBake manual. 9599 9600 :term:`TRANSLATED_TARGET_ARCH` 9601 A sanitized version of :term:`TARGET_ARCH`. This 9602 variable is used where the architecture is needed in a value where 9603 underscores are not allowed, for example within package filenames. In 9604 this case, dash characters replace any underscore characters used in 9605 :term:`TARGET_ARCH`. 9606 9607 Do not edit this variable. 9608 9609 :term:`TUNE_ARCH` 9610 The GNU canonical architecture for a specific architecture (i.e. 9611 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses 9612 this value to setup configuration. 9613 9614 :term:`TUNE_ARCH` definitions are specific to a given architecture. The 9615 definitions can be a single static definition, or can be dynamically 9616 adjusted. You can see details for a given CPU family by looking at 9617 the architecture's ``README`` file. For example, the 9618 ``meta/conf/machine/include/mips/README`` file in the 9619 :term:`Source Directory` provides information for 9620 :term:`TUNE_ARCH` specific to the ``mips`` architecture. 9621 9622 :term:`TUNE_ARCH` is tied closely to 9623 :term:`TARGET_ARCH`, which defines the target 9624 machine's architecture. The BitBake configuration file 9625 (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:: 9626 9627 TARGET_ARCH = "${TUNE_ARCH}" 9628 9629 The following list, which is by no means complete since architectures 9630 are configurable, shows supported machine architectures: 9631 9632 - arm 9633 - i586 9634 - x86_64 9635 - powerpc 9636 - powerpc64 9637 - mips 9638 - mipsel 9639 9640 :term:`TUNE_ASARGS` 9641 Specifies architecture-specific assembler flags for the target 9642 system. The set of flags is based on the selected tune features. 9643 :term:`TUNE_ASARGS` is set using the tune include files, which are 9644 typically under ``meta/conf/machine/include/`` and are influenced 9645 through :term:`TUNE_FEATURES`. For example, the 9646 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9647 for the x86 architecture as follows:: 9648 9649 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" 9650 9651 .. note:: 9652 9653 Board Support Packages (BSPs) select the tune. The selected tune, 9654 in turn, affects the tune variables themselves (i.e. the tune can 9655 supply its own set of flags). 9656 9657 :term:`TUNE_CCARGS` 9658 Specifies architecture-specific C compiler flags for the target 9659 system. The set of flags is based on the selected tune features. 9660 :term:`TUNE_CCARGS` is set using the tune include files, which are 9661 typically under ``meta/conf/machine/include/`` and are influenced 9662 through :term:`TUNE_FEATURES`. 9663 9664 .. note:: 9665 9666 Board Support Packages (BSPs) select the tune. The selected tune, 9667 in turn, affects the tune variables themselves (i.e. the tune can 9668 supply its own set of flags). 9669 9670 :term:`TUNE_FEATURES` 9671 Features used to "tune" a compiler for optimal use given a specific 9672 processor. The features are defined within the tune files and allow 9673 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on 9674 the features. 9675 9676 The OpenEmbedded build system verifies the features to be sure they 9677 are not conflicting and that they are supported. 9678 9679 The BitBake configuration file (``meta/conf/bitbake.conf``) defines 9680 :term:`TUNE_FEATURES` as follows:: 9681 9682 TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}" 9683 9684 See the :term:`DEFAULTTUNE` variable for more information. 9685 9686 :term:`TUNE_LDARGS` 9687 Specifies architecture-specific linker flags for the target system. 9688 The set of flags is based on the selected tune features. 9689 :term:`TUNE_LDARGS` is set using the tune include files, which are 9690 typically under ``meta/conf/machine/include/`` and are influenced 9691 through :term:`TUNE_FEATURES`. For example, the 9692 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9693 for the x86 architecture as follows:: 9694 9695 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" 9696 9697 .. note:: 9698 9699 Board Support Packages (BSPs) select the tune. The selected tune, 9700 in turn, affects the tune variables themselves (i.e. the tune can 9701 supply its own set of flags). 9702 9703 :term:`TUNE_PKGARCH` 9704 The package architecture understood by the packaging system to define 9705 the architecture, ABI, and tuning of output packages. The specific 9706 tune is defined using the "_tune" override as follows:: 9707 9708 TUNE_PKGARCH:tune-tune = "tune" 9709 9710 These tune-specific package architectures are defined in the machine 9711 include files. Here is an example of the "core2-32" tuning as used in 9712 the ``meta/conf/machine/include/x86/tune-core2.inc`` file:: 9713 9714 TUNE_PKGARCH:tune-core2-32 = "core2-32" 9715 9716 :term:`TUNECONFLICTS[feature]` 9717 Specifies CPU or Application Binary Interface (ABI) tuning features 9718 that conflict with feature. 9719 9720 Known tuning conflicts are specified in the machine include files in 9721 the :term:`Source Directory`. Here is an example from 9722 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file 9723 that lists the "o32" and "n64" features as conflicting with the "n32" 9724 feature:: 9725 9726 TUNECONFLICTS[n32] = "o32 n64" 9727 9728 :term:`TUNEVALID[feature]` 9729 Specifies a valid CPU or Application Binary Interface (ABI) tuning 9730 feature. The specified feature is stored as a flag. Valid features 9731 are specified in the machine include files (e.g. 9732 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example 9733 from that file:: 9734 9735 TUNEVALID[bigendian] = "Enable big-endian mode." 9736 9737 See the machine include files in the :term:`Source Directory` 9738 for these features. 9739 9740 :term:`UBOOT_BINARY` 9741 Specifies the name of the binary build by U-Boot. 9742 9743 :term:`UBOOT_CONFIG` 9744 Configures one or more U-Boot configurations to build. Each 9745 configuration can define the :term:`UBOOT_MACHINE` and optionally the 9746 :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`. 9747 9748 Here is an example from the ``meta-freescale`` layer. :: 9749 9750 UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor" 9751 UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig" 9752 UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig,,u-boot-with-spl-pbl.bin" 9753 UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin" 9754 UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig" 9755 UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig" 9756 UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig" 9757 UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig,,u-boot-with-spl-pbl.bin" 9758 9759 In this example, all possible seven configurations are selected. Each 9760 configuration specifies "..._defconfig" as :term:`UBOOT_MACHINE`, and 9761 the "sd..." configurations define an individual name for 9762 :term:`UBOOT_BINARY`. No configuration defines a second parameter for 9763 :term:`IMAGE_FSTYPES` to use for the U-Boot image. 9764 9765 For more information on how the :term:`UBOOT_CONFIG` is handled, see the 9766 :ref:`ref-classes-uboot-config` class. 9767 9768 :term:`UBOOT_DTB_LOADADDRESS` 9769 Specifies the load address for the dtb image used by U-Boot. During FIT 9770 image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in 9771 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be 9772 used in creating the dtb sections of Image Tree Source for the FIT image. 9773 9774 :term:`UBOOT_DTBO_LOADADDRESS` 9775 Specifies the load address for the dtbo image used by U-Boot. During FIT 9776 image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in 9777 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be 9778 used in creating the dtbo sections of Image Tree Source for the FIT image. 9779 9780 :term:`UBOOT_ENTRYPOINT` 9781 Specifies the entry point for the U-Boot image. During U-Boot image 9782 creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a 9783 command-line parameter to the ``uboot-mkimage`` utility. 9784 9785 To pass a 64 bit address for FIT image creation, you will need to set: 9786 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. 9787 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. 9788 9789 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9790 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, 9791 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9792 classes. 9793 9794 :term:`UBOOT_FIT_ADDRESS_CELLS` 9795 Specifies the value of the ``#address-cells`` value for the 9796 description of the U-Boot FIT image. 9797 9798 The default value is set to "1" by the :ref:`ref-classes-uboot-sign` 9799 class, which corresponds to 32 bit addresses. 9800 9801 For platforms that need to set 64 bit addresses in 9802 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to 9803 set this value to "2", as two 32 bit values (cells) will be needed 9804 to represent such addresses. 9805 9806 Here is an example setting "0x400000000" as a load address:: 9807 9808 UBOOT_FIT_ADDRESS_CELLS = "2" 9809 UBOOT_LOADADDRESS= "0x04 0x00000000" 9810 9811 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. 9812 9813 :term:`UBOOT_FIT_DESC` 9814 Specifies the description string encoded into a U-Boot fitImage. The default 9815 value is set by the :ref:`ref-classes-uboot-sign` class as follows:: 9816 9817 UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" 9818 9819 :term:`UBOOT_FIT_GENERATE_KEYS` 9820 Decides whether to generate the keys for signing the U-Boot fitImage if 9821 they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`. 9822 The default value is "0". 9823 9824 Enable this as follows:: 9825 9826 UBOOT_FIT_GENERATE_KEYS = "1" 9827 9828 This variable is used in the :ref:`ref-classes-uboot-sign` class. 9829 9830 :term:`UBOOT_FIT_HASH_ALG` 9831 Specifies the hash algorithm used in creating the U-Boot FIT Image. 9832 It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign` 9833 class. 9834 9835 :term:`UBOOT_FIT_KEY_GENRSA_ARGS` 9836 Arguments to ``openssl genrsa`` for generating a RSA private key for 9837 signing the U-Boot FIT image. The default value of this variable 9838 is set to "-F4" by the :ref:`ref-classes-uboot-sign` class. 9839 9840 :term:`UBOOT_FIT_KEY_REQ_ARGS` 9841 Arguments to ``openssl req`` for generating a certificate for signing 9842 the U-Boot FIT image. The default value is "-batch -new" by the 9843 :ref:`ref-classes-uboot-sign` class, "batch" for 9844 non interactive mode and "new" for generating new keys. 9845 9846 :term:`UBOOT_FIT_KEY_SIGN_PKCS` 9847 Format for the public key certificate used for signing the U-Boot FIT 9848 image. The default value is set to "x509" by the 9849 :ref:`ref-classes-uboot-sign` class. 9850 9851 :term:`UBOOT_FIT_SIGN_ALG` 9852 Specifies the signature algorithm used in creating the U-Boot FIT Image. 9853 This variable is set by default to "rsa2048" by the 9854 :ref:`ref-classes-uboot-sign` class. 9855 9856 :term:`UBOOT_FIT_SIGN_NUMBITS` 9857 Size of the private key used in signing the U-Boot FIT image, in number 9858 of bits. The default value for this variable is set to "2048" 9859 by the :ref:`ref-classes-uboot-sign` class. 9860 9861 :term:`UBOOT_FITIMAGE_ENABLE` 9862 This variable allows to generate a FIT image for U-Boot, which is one 9863 of the ways to implement a verified boot process. 9864 9865 Its default value is "0", so set it to "1" to enable this functionality:: 9866 9867 UBOOT_FITIMAGE_ENABLE = "1" 9868 9869 See the :ref:`ref-classes-uboot-sign` class for details. 9870 9871 :term:`UBOOT_LOADADDRESS` 9872 Specifies the load address for the U-Boot image. During U-Boot image 9873 creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a 9874 command-line parameter to the ``uboot-mkimage`` utility. 9875 9876 To pass a 64 bit address, you will also need to set: 9877 9878 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. 9879 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. 9880 9881 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9882 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, 9883 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9884 classes. 9885 9886 :term:`UBOOT_LOCALVERSION` 9887 Appends a string to the name of the local version of the U-Boot 9888 image. For example, assuming the version of the U-Boot image built 9889 was "2013.10", the full version string reported by U-Boot would be 9890 "2013.10-yocto" given the following statement:: 9891 9892 UBOOT_LOCALVERSION = "-yocto" 9893 9894 :term:`UBOOT_MACHINE` 9895 Specifies the value passed on the ``make`` command line when building 9896 a U-Boot image. The value indicates the target platform 9897 configuration. You typically set this variable from the machine 9898 configuration file (i.e. ``conf/machine/machine_name.conf``). 9899 9900 Please see the "Selection of Processor Architecture and Board Type" 9901 section in the U-Boot README for valid values for this variable. 9902 9903 :term:`UBOOT_MAKE_TARGET` 9904 Specifies the target called in the ``Makefile``. The default target 9905 is "all". 9906 9907 :term:`UBOOT_MKIMAGE` 9908 Specifies the name of the mkimage command as used by the 9909 :ref:`ref-classes-kernel-fitimage` class to assemble 9910 the FIT image. This can be used to substitute an alternative command, wrapper 9911 script or function if desired. The default is "uboot-mkimage". 9912 9913 :term:`UBOOT_MKIMAGE_DTCOPTS` 9914 Options for the device tree compiler passed to ``mkimage -D`` feature 9915 while creating a FIT image with the :ref:`ref-classes-kernel-fitimage` 9916 class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the 9917 :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option 9918 to ``mkimage``. 9919 9920 This variable is also used by the :ref:`ref-classes-uboot-sign` class. 9921 9922 :term:`UBOOT_MKIMAGE_KERNEL_TYPE` 9923 Specifies the type argument for the kernel as passed to ``uboot-mkimage``. 9924 The default value is "kernel". 9925 9926 :term:`UBOOT_MKIMAGE_SIGN` 9927 Specifies the name of the mkimage command as used by the 9928 :ref:`ref-classes-kernel-fitimage` class to sign 9929 the FIT image after it has been assembled (if enabled). This can be used 9930 to substitute an alternative command, wrapper script or function if 9931 desired. The default is "${:term:`UBOOT_MKIMAGE`}". 9932 9933 :term:`UBOOT_MKIMAGE_SIGN_ARGS` 9934 Optionally specifies additional arguments for the 9935 :ref:`ref-classes-kernel-fitimage` class to pass to the 9936 mkimage command when signing the FIT image. 9937 9938 :term:`UBOOT_RD_ENTRYPOINT` 9939 Specifies the entrypoint for the RAM disk image. During FIT image 9940 creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in 9941 :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be 9942 used in creating the Image Tree Source for the FIT image. 9943 9944 :term:`UBOOT_RD_LOADADDRESS` 9945 Specifies the load address for the RAM disk image. During FIT image 9946 creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in 9947 :ref:`ref-classes-kernel-fitimage` class to specify the load address to 9948 be used in creating the Image Tree Source for the FIT image. 9949 9950 :term:`UBOOT_SIGN_ENABLE` 9951 Enable signing of FIT image. The default value is "0". 9952 9953 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9954 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9955 classes. 9956 9957 :term:`UBOOT_SIGN_KEYDIR` 9958 Location of the directory containing the RSA key and certificate used for 9959 signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and 9960 :ref:`ref-classes-uboot-sign` classes. 9961 9962 :term:`UBOOT_SIGN_KEYNAME` 9963 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class 9964 for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR` 9965 directory. If we have for example a ``dev.key`` key and a ``dev.crt`` 9966 certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will 9967 have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``. 9968 9969 :term:`UBOOT_SUFFIX` 9970 Points to the generated U-Boot extension. For example, ``u-boot.sb`` 9971 has a ``.sb`` extension. 9972 9973 The default U-Boot extension is ``.bin`` 9974 9975 :term:`UBOOT_TARGET` 9976 Specifies the target used for building U-Boot. The target is passed 9977 directly as part of the "make" command (e.g. SPL and AIS). If you do 9978 not specifically set this variable, the OpenEmbedded build process 9979 passes and uses "all" for the target during the U-Boot building 9980 process. 9981 9982 :term:`UKIFY_CMD` 9983 When inheriting the :ref:`ref-classes-uki` class, 9984 `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build 9985 `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 9986 Defaults to ``ukify build``. 9987 9988 :term:`UKI_CMDLINE` 9989 When inheriting the :ref:`ref-classes-uki` class, the kernel command line 9990 to use when booting the `Unified Kernel Image (UKI) 9991 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 9992 Defaults to ``rootwait root=LABEL=root console=${KERNEL_CONSOLE}``. 9993 9994 :term:`UKI_CONFIG_FILE` 9995 When inheriting the :ref:`ref-classes-uki` class, an optional config 9996 file for the `ukify 9997 <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ 9998 command. 9999 10000 :term:`UKI_FILENAME` 10001 When inheriting the :ref:`ref-classes-uki` class, the output file name 10002 for the generated `Unified Kernel Image (UKI) 10003 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 10004 Defaults to ``uki.efi``. 10005 10006 :term:`UKI_KERNEL_FILENAME` 10007 When inheriting the :ref:`ref-classes-uki` class, the kernel image file 10008 name to use as input. Defaults to :term:`KERNEL_IMAGETYPE`. 10009 10010 :term:`UKI_SB_CERT` 10011 When inheriting the :ref:`ref-classes-uki` class, optional UEFI 10012 secureboot certificate matching the private key in :term:`UKI_SB_KEY`. 10013 10014 :term:`UKI_SB_KEY` 10015 When inheriting the :ref:`ref-classes-uki` class, optional UEFI 10016 secureboot private key to sign the `Unified Kernel Image (UKI) 10017 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 10018 10019 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` 10020 Specifies a list of options that, if reported by the configure script 10021 as being invalid, should not generate a warning during the 10022 :ref:`ref-tasks-configure` task. Normally, invalid 10023 configure options are simply not passed to the configure script (e.g. 10024 should be removed from :term:`EXTRA_OECONF` or 10025 :term:`PACKAGECONFIG_CONFARGS`). 10026 However, there are common options that are passed to all 10027 configure scripts at a class level, but might not be valid for some 10028 configure scripts. Therefore warnings about these options are useless. 10029 For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`. 10030 10031 The configure arguments check that uses 10032 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the 10033 :ref:`ref-classes-insane` class and is only enabled if the 10034 recipe inherits the :ref:`ref-classes-autotools` class. 10035 10036 :term:`UNPACKDIR` 10037 This variable, used by the :ref:`ref-classes-base` class, 10038 specifies where fetches sources should be unpacked by the 10039 :ref:`ref-tasks-unpack` task. 10040 10041 :term:`UPDATERCPN` 10042 For recipes inheriting the 10043 :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN` 10044 specifies the package that contains the initscript that is enabled. 10045 10046 The default value is "${PN}". Given that almost all recipes that 10047 install initscripts package them in the main package for the recipe, 10048 you rarely need to set this variable in individual recipes. 10049 10050 :term:`UPSTREAM_CHECK_COMMITS` 10051 You can perform a per-recipe check for what the latest upstream 10052 source code version is by calling ``devtool latest-version recipe``. If 10053 the recipe source code is provided from Git repositories, but 10054 releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS` 10055 to ``1`` in the recipe, and the OpenEmbedded build system 10056 will compare the latest commit with the one currently specified 10057 by the recipe (:term:`SRCREV`):: 10058 10059 UPSTREAM_CHECK_COMMITS = "1" 10060 10061 :term:`UPSTREAM_CHECK_GITTAGREGEX` 10062 You can perform a per-recipe check for what the latest upstream 10063 source code version is by calling ``devtool latest-version recipe``. If 10064 the recipe source code is provided from Git repositories, the 10065 OpenEmbedded build system determines the latest upstream version by 10066 picking the latest tag from the list of all repository tags. 10067 10068 You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a 10069 regular expression to filter only the relevant tags should the 10070 default filter not work correctly:: 10071 10072 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" 10073 10074 :term:`UPSTREAM_CHECK_REGEX` 10075 Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different 10076 regular expression instead of the default one when the package 10077 checking system is parsing the page found using 10078 :term:`UPSTREAM_CHECK_URI`:: 10079 10080 UPSTREAM_CHECK_REGEX = "package_regex" 10081 10082 :term:`UPSTREAM_CHECK_URI` 10083 You can perform a per-recipe check for what the latest upstream 10084 source code version is by calling ``devtool latest-version recipe``. If 10085 the source code is provided from tarballs, the latest version is 10086 determined by fetching the directory listing where the tarball is and 10087 attempting to find a later tarball. When this approach does not work, 10088 you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that 10089 contains the link to the latest tarball:: 10090 10091 UPSTREAM_CHECK_URI = "recipe_url" 10092 10093 :term:`UPSTREAM_VERSION_UNKNOWN` 10094 You can perform a per-recipe check for what the latest upstream 10095 source code version is by calling ``devtool latest-version recipe``. 10096 If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`, 10097 :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in 10098 the recipe allows to determine what the latest upstream version is, 10099 you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe 10100 to acknowledge that the check cannot be performed:: 10101 10102 UPSTREAM_VERSION_UNKNOWN = "1" 10103 10104 :term:`USE_DEVFS` 10105 Determines if ``devtmpfs`` is used for ``/dev`` population. The 10106 default value used for :term:`USE_DEVFS` is "1" when no value is 10107 specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a 10108 statically populated ``/dev`` directory. 10109 10110 See the ":ref:`dev-manual/device-manager:selecting a device manager`" section in 10111 the Yocto Project Development Tasks Manual for information on how to 10112 use this variable. 10113 10114 :term:`USE_VT` 10115 When using 10116 :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, 10117 determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>` 10118 on any virtual terminals in order to enable logging in through those 10119 terminals. 10120 10121 The default value used for :term:`USE_VT` is "1" when no default value is 10122 specifically set. Typically, you would set :term:`USE_VT` to "0" in the 10123 machine configuration file for machines that do not have a graphical 10124 display attached and therefore do not need virtual terminal 10125 functionality. 10126 10127 :term:`USER_CLASSES` 10128 A list of classes to globally inherit. These classes are used by the 10129 OpenEmbedded build system to enable extra features. 10130 10131 Classes inherited using :term:`USER_CLASSES` must be located in the 10132 ``classes-global/`` or ``classes/`` subdirectories. 10133 10134 The default list is set in your ``local.conf`` file:: 10135 10136 USER_CLASSES ?= "buildstats" 10137 10138 For more information, see 10139 ``meta-poky/conf/templates/default/local.conf.sample`` in the 10140 :term:`Source Directory`. 10141 10142 :term:`USERADD_DEPENDS` 10143 Specifies a list of recipes that create users / groups (via 10144 :term:`USERADD_PARAM` / :term:`GROUPADD_PARAM`) which a recipe 10145 depends upon. This ensures that those users / groups are available 10146 when building a recipe. 10147 10148 :term:`USERADD_ERROR_DYNAMIC` 10149 If set to ``error``, forces the OpenEmbedded build system to produce 10150 an error if the user identification (``uid``) and group 10151 identification (``gid``) values are not defined in any of the files 10152 listed in :term:`USERADD_UID_TABLES` and 10153 :term:`USERADD_GID_TABLES`. If set to 10154 ``warn``, a warning will be issued instead. 10155 10156 The default behavior for the build system is to dynamically apply 10157 ``uid`` and ``gid`` values. Consequently, the 10158 :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan 10159 on using statically assigned ``gid`` and ``uid`` values, you should 10160 set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` 10161 file as follows:: 10162 10163 USERADD_ERROR_DYNAMIC = "error" 10164 10165 Overriding the 10166 default behavior implies you are going to also take steps to set 10167 static ``uid`` and ``gid`` values through use of the 10168 :term:`USERADDEXTENSION`, 10169 :term:`USERADD_UID_TABLES`, and 10170 :term:`USERADD_GID_TABLES` variables. 10171 10172 .. note:: 10173 10174 There is a difference in behavior between setting 10175 :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``. 10176 When it is set to ``warn``, the build system will report a warning for 10177 every undefined ``uid`` and ``gid`` in any recipe. But when it is set 10178 to ``error``, it will only report errors for recipes that are actually 10179 built. 10180 This saves you from having to add static IDs for recipes that you 10181 know will never be built. 10182 10183 :term:`USERADD_GID_TABLES` 10184 Specifies a password file to use for obtaining static group 10185 identification (``gid``) values when the OpenEmbedded build system 10186 adds a group to the system during package installation. 10187 10188 When applying static group identification (``gid``) values, the 10189 OpenEmbedded build system looks in :term:`BBPATH` for a 10190 ``files/group`` file and then applies those ``uid`` values. Set the 10191 variable as follows in your ``local.conf`` file:: 10192 10193 10194 USERADD_GID_TABLES = "files/group" 10195 10196 .. note:: 10197 10198 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" 10199 causes the build system to use static ``gid`` values. 10200 10201 :term:`USERADD_PACKAGES` 10202 When inheriting the :ref:`ref-classes-useradd` class, 10203 this variable specifies the individual packages within the recipe 10204 that require users and/or groups to be added. 10205 10206 You must set this variable if the recipe inherits the class. For 10207 example, the following enables adding a user for the main package in 10208 a recipe:: 10209 10210 USERADD_PACKAGES = "${PN}" 10211 10212 .. note:: 10213 10214 It follows that if you are going to use the :term:`USERADD_PACKAGES` 10215 variable, you need to set one or more of the :term:`USERADD_PARAM`, 10216 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. 10217 10218 :term:`USERADD_PARAM` 10219 When inheriting the :ref:`ref-classes-useradd` class, 10220 this variable specifies for a package what parameters should pass to 10221 the ``useradd`` command if you add a user to the system when the 10222 package is installed. 10223 10224 Here is an example from the ``dbus`` recipe:: 10225 10226 USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \ 10227 --no-create-home --shell /bin/false \ 10228 --user-group messagebus" 10229 10230 For information on the 10231 standard Linux shell command ``useradd``, see 10232 https://linux.die.net/man/8/useradd. 10233 10234 :term:`USERADD_UID_TABLES` 10235 Specifies a password file to use for obtaining static user 10236 identification (``uid``) values when the OpenEmbedded build system 10237 adds a user to the system during package installation. 10238 10239 When applying static user identification (``uid``) values, the 10240 OpenEmbedded build system looks in :term:`BBPATH` for a 10241 ``files/passwd`` file and then applies those ``uid`` values. Set the 10242 variable as follows in your ``local.conf`` file:: 10243 10244 USERADD_UID_TABLES = "files/passwd" 10245 10246 .. note:: 10247 10248 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" 10249 causes the build system to use static ``uid`` values. 10250 10251 :term:`USERADDEXTENSION` 10252 When set to "useradd-staticids", causes the OpenEmbedded build system 10253 to base all user and group additions on a static ``passwd`` and 10254 ``group`` files found in :term:`BBPATH`. 10255 10256 To use static user identification (``uid``) and group identification 10257 (``gid``) values, set the variable as follows in your ``local.conf`` 10258 file: USERADDEXTENSION = "useradd-staticids" 10259 10260 .. note:: 10261 10262 Setting this variable to use static ``uid`` and ``gid`` 10263 values causes the OpenEmbedded build system to employ the 10264 :ref:`ref-classes-useradd` class. 10265 10266 If you use static ``uid`` and ``gid`` information, you must also 10267 specify the ``files/passwd`` and ``files/group`` files by setting the 10268 :term:`USERADD_UID_TABLES` and 10269 :term:`USERADD_GID_TABLES` variables. 10270 Additionally, you should also set the 10271 :term:`USERADD_ERROR_DYNAMIC` variable. 10272 10273 :term:`VIRTUAL-RUNTIME` 10274 :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual 10275 packages for runtime usage, typically for use in :term:`RDEPENDS` 10276 or in image definitions. 10277 10278 An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible 10279 to either use BusyBox based utilities:: 10280 10281 VIRTUAL-RUNTIME_base-utils = "busybox" 10282 10283 or their full featured implementations from GNU Coreutils 10284 and other projects:: 10285 10286 VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils" 10287 10288 Here are two examples using this virtual runtime package. The 10289 first one is in :yocto_git:`initramfs-framework_1.0.bb 10290 </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`:: 10291 10292 RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}" 10293 10294 The second example is in the :yocto_git:`core-image-initramfs-boot 10295 </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>` 10296 image definition:: 10297 10298 PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd" 10299 10300 :term:`WARN_QA` 10301 Specifies the quality assurance checks whose failures are reported as 10302 warnings by the OpenEmbedded build system. You set this variable in 10303 your distribution configuration file. For a list of the checks you 10304 can control with this variable, see the 10305 ":ref:`ref-classes-insane`" section. 10306 10307 :term:`WATCHDOG_TIMEOUT` 10308 Specifies the timeout in seconds used by the ``watchdog`` recipe and 10309 also by ``systemd`` during reboot. The default is 60 seconds. 10310 10311 :term:`WIC_SECTOR_SIZE` 10312 The variable :term:`WIC_SECTOR_SIZE` controls the sector size of Wic 10313 images. In the background, this controls the value of the 10314 ``PARTED_SECTOR_SIZE`` environment variable passed to the ``parted`` 10315 command-line utility, used to generated the images. The default value is 10316 ``512``. 10317 10318 For more information on how to create Wic images, see the 10319 ":ref:`dev-manual/wic:creating partitioned images using wic`" section in 10320 the Yocto Project Development Tasks Manual. 10321 10322 :term:`WIRELESS_DAEMON` 10323 For ``connman`` and ``packagegroup-base``, specifies the wireless 10324 daemon to use. The default is "wpa-supplicant" (note that the value 10325 uses a dash and not an underscore). 10326 10327 :term:`WKS_FILE` 10328 Specifies the location of the Wic kickstart file that is used by the 10329 OpenEmbedded build system to create a partitioned image 10330 (``image.wic``). For information on how to create a partitioned 10331 image, see the 10332 ":ref:`dev-manual/wic:creating partitioned images using wic`" 10333 section in the Yocto Project Development Tasks Manual. For details on 10334 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. 10335 10336 :term:`WKS_FILE_DEPENDS` 10337 When placed in the recipe that builds your image, this variable lists 10338 build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only 10339 applicable when Wic images are active (i.e. when 10340 :term:`IMAGE_FSTYPES` contains entries related 10341 to Wic). If your recipe does not create Wic images, the variable has 10342 no effect. 10343 10344 The :term:`WKS_FILE_DEPENDS` variable is similar to the 10345 :term:`DEPENDS` variable. When you use the variable in 10346 your recipe that builds the Wic image, dependencies you list in the 10347 :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable. 10348 10349 With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to 10350 specify a list of additional dependencies (e.g. native tools, 10351 bootloaders, and so forth), that are required to build Wic images. 10352 Here is an example:: 10353 10354 WKS_FILE_DEPENDS = "some-native-tool" 10355 10356 In the 10357 previous example, some-native-tool would be replaced with an actual 10358 native tool on which the build would depend. 10359 10360 :term:`WKS_FILES` 10361 Specifies a list of candidate Wic kickstart files to be used by the 10362 OpenEmbedded build system to create a partitioned image. Only the 10363 first one that is found, from left to right, will be used. 10364 10365 This is only useful when there are multiple ``.wks`` files that can be 10366 used to produce an image. A typical case is when multiple layers are 10367 used for different hardware platforms, each supplying a different 10368 ``.wks`` file. In this case, you specify all possible ones through 10369 :term:`WKS_FILES`. 10370 10371 If only one ``.wks`` file is used, set :term:`WKS_FILE` instead. 10372 10373 :term:`WORKDIR` 10374 The pathname of the work directory in which the OpenEmbedded build 10375 system builds a recipe. This directory is located within the 10376 :term:`TMPDIR` directory structure and is specific to 10377 the recipe being built and the system for which it is being built. 10378 10379 The :term:`WORKDIR` directory is defined as follows:: 10380 10381 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} 10382 10383 The actual directory depends on several things: 10384 10385 - :term:`TMPDIR`: The top-level build output directory 10386 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier 10387 - :term:`PN`: The recipe name 10388 - :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which 10389 is usually the case for most recipes, then :term:`EXTENDPE` is blank. 10390 - :term:`PV`: The recipe version 10391 - :term:`PR`: The recipe revision 10392 10393 As an example, assume a Source Directory top-level folder name 10394 ``poky``, a default :term:`Build Directory` at ``poky/build``, and a 10395 ``qemux86-poky-linux`` machine target system. Furthermore, suppose 10396 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work 10397 directory the build system uses to build the package would be as 10398 follows:: 10399 10400 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 10401 10402 :term:`XSERVER` 10403 Specifies the packages that should be installed to provide an X 10404 server and drivers for the current machine, assuming your image 10405 directly includes ``packagegroup-core-x11-xserver`` or, perhaps 10406 indirectly, includes "x11-base" in 10407 :term:`IMAGE_FEATURES`. 10408 10409 The default value of :term:`XSERVER`, if not specified in the machine 10410 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". 10411 10412 :term:`XZ_THREADS` 10413 Specifies the number of parallel threads that should be used when 10414 using xz compression. 10415 10416 By default this scales with core count, but is never set less than 2 10417 to ensure that multi-threaded mode is always used so that the output 10418 file contents are deterministic. Builds will work with a value of 1 10419 but the output will differ compared to the output from the compression 10420 generated when more than one thread is used. 10421 10422 On systems where many tasks run in parallel, setting a limit to this 10423 can be helpful in controlling system resource usage. 10424 10425 :term:`XZ_MEMLIMIT` 10426 Specifies the maximum memory the xz compression should use as a percentage 10427 of system memory. If unconstrained the xz compressor can use large amounts of 10428 memory and become problematic with parallelism elsewhere in the build. 10429 "50%" has been found to be a good value. 10430 10431 :term:`ZSTD_COMPRESSION_LEVEL` 10432 Specifies the compression level to be used with ZStandard compression 10433 (from ``1`` to ``19``, set to ``3`` by default, following upstream choice). 10434 Higher levels produce smaller files, but take longer to complete. 10435 10436 :term:`ZSTD_THREADS` 10437 Specifies the number of parallel threads that should be used when 10438 using ZStandard compression. 10439 10440 By default this scales with core count, but is never set less than 2 10441 to ensure that multi-threaded mode is always used so that the output 10442 file contents are deterministic. Builds will work with a value of 1 10443 but the output will differ compared to the output from the compression 10444 generated when more than one thread is used. 10445 10446 On systems where many tasks run in parallel, setting a limit to this 10447 can be helpful in controlling system resource usage. 10448
