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 be sure :term:`PV` contains 213 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you have a kernel 214 recipe that inherits the :ref:`ref-classes-kernel` class and you 215 use the previous statement. In this example, ``${SRCPV}`` does not 216 automatically get into :term:`PV`. Consequently, you need to change 217 :term:`PV` in your recipe so that it does contain ``${SRCPV}``. 218 219 For more information see the 220 ":ref:`dev-manual/packages:automatically incrementing a package version number`" 221 section in the Yocto Project Development Tasks Manual. 222 223 :term:`AUTO_SYSLINUXMENU` 224 Enables creating an automatic menu for the syslinux bootloader. You 225 must set this variable in your recipe. The 226 :ref:`ref-classes-syslinux` class checks this variable. 227 228 :term:`AVAILTUNES` 229 The list of defined CPU and Application Binary Interface (ABI) 230 tunings (i.e. "tunes") available for use by the OpenEmbedded build 231 system. 232 233 The list simply presents the tunes that are available. Not all tunes 234 may be compatible with a particular machine configuration, or with 235 each other in a 236 :ref:`Multilib <dev-manual/libraries:combining multiple versions of library files into one image>` 237 configuration. 238 239 To add a tune to the list, be sure to append it with spaces using the 240 "+=" BitBake operator. Do not simply replace the list by using the 241 "=" operator. See the 242 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake 243 User Manual for more information. 244 245 :term:`AZ_SAS` 246 Azure Storage Shared Access Signature, when using the 247 :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` 248 This variable can be defined to be used by the fetcher to authenticate 249 and gain access to non-public artifacts:: 250 251 AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>"" 252 253 For more information see Microsoft's Azure Storage documentation at 254 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview 255 256 :term:`B` 257 The directory within the :term:`Build Directory` in which the 258 OpenEmbedded build system places generated objects during a recipe's 259 build process. By default, this directory is the same as the 260 :term:`S` directory, which is defined as:: 261 262 S = "${WORKDIR}/${BP}" 263 264 You can separate the (:term:`S`) directory and the directory pointed to 265 by the :term:`B` variable. Most Autotools-based recipes support 266 separating these directories. The build system defaults to using 267 separate directories for ``gcc`` and some kernel recipes. 268 269 :term:`BAD_RECOMMENDATIONS` 270 Lists "recommended-only" packages to not install. Recommended-only 271 packages are packages installed only through the 272 :term:`RRECOMMENDS` variable. You can prevent any 273 of these "recommended" packages from being installed by listing them 274 with the :term:`BAD_RECOMMENDATIONS` variable:: 275 276 BAD_RECOMMENDATIONS = "package_name package_name package_name ..." 277 278 You can set this variable globally in your ``local.conf`` file or you 279 can attach it to a specific image recipe by using the recipe name 280 override:: 281 282 BAD_RECOMMENDATIONS:pn-target_image = "package_name" 283 284 It is important to realize that if you choose to not install packages 285 using this variable and some other packages are dependent on them 286 (i.e. listed in a recipe's :term:`RDEPENDS` 287 variable), the OpenEmbedded build system ignores your request and 288 will install the packages to avoid dependency errors. 289 290 This variable is supported only when using the IPK and RPM 291 packaging backends. DEB is not supported. 292 293 See the :term:`NO_RECOMMENDATIONS` and the 294 :term:`PACKAGE_EXCLUDE` variables for related 295 information. 296 297 :term:`BASE_LIB` 298 The library directory name for the CPU or Application Binary 299 Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib 300 context. See the ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`" 301 section in the Yocto Project Development Tasks Manual for information 302 on Multilib. 303 304 The :term:`BASE_LIB` variable is defined in the machine include files in 305 the :term:`Source Directory`. If Multilib is not 306 being used, the value defaults to "lib". 307 308 :term:`BASE_WORKDIR` 309 Points to the base of the work directory for all recipes. The default 310 value is "${TMPDIR}/work". 311 312 :term:`BB_ALLOWED_NETWORKS` 313 Specifies a space-delimited list of hosts that the fetcher is allowed 314 to use to obtain the required source code. Here are 315 considerations surrounding this variable: 316 317 - This host list is only used if :term:`BB_NO_NETWORK` is either not set 318 or set to "0". 319 320 - There is limited support for wildcard matching against the beginning of 321 host names. For example, the following setting matches 322 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``:: 323 324 BB_ALLOWED_NETWORKS = "*.gnu.org" 325 326 .. note:: 327 328 The use of the "``*``" character only works at the beginning of 329 a host name and it must be isolated from the remainder of the 330 host name. You cannot use the wildcard character in any other 331 location of the name or combined with the front part of the 332 name. 333 334 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` 335 is not. 336 337 - Mirrors not in the host list are skipped and logged in debug. 338 339 - Attempts to access networks not in the host list cause a failure. 340 341 Using :term:`BB_ALLOWED_NETWORKS` in conjunction with 342 :term:`PREMIRRORS` is very useful. Adding the host 343 you want to use to :term:`PREMIRRORS` results in the source code being 344 fetched from an allowed location and avoids raising an error when a 345 host that is not allowed is in a :term:`SRC_URI` 346 statement. This is because the fetcher does not attempt to use the 347 host listed in :term:`SRC_URI` after a successful fetch from the 348 :term:`PREMIRRORS` occurs. 349 350 :term:`BB_BASEHASH_IGNORE_VARS` 351 See :term:`bitbake:BB_BASEHASH_IGNORE_VARS` in the BitBake manual. 352 353 :term:`BB_CACHEDIR` 354 See :term:`bitbake:BB_CACHEDIR` in the BitBake manual. 355 356 :term:`BB_CHECK_SSL_CERTS` 357 See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual. 358 359 :term:`BB_CONSOLELOG` 360 See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual. 361 362 :term:`BB_CURRENTTASK` 363 See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual. 364 365 :term:`BB_DANGLINGAPPENDS_WARNONLY` 366 Defines how BitBake handles situations where an append file 367 (``.bbappend``) has no corresponding recipe file (``.bb``). This 368 condition often occurs when layers get out of sync (e.g. ``oe-core`` 369 bumps a recipe version and the old recipe no longer exists and the 370 other layer has not been updated to the new version of the recipe 371 yet). 372 373 The default fatal behavior is safest because it is the sane reaction 374 given something is out of sync. It is important to realize when your 375 changes are no longer being applied. 376 377 You can change the default behavior by setting this variable to "1", 378 "yes", or "true" in your ``local.conf`` file, which is located in the 379 :term:`Build Directory`: Here is an example:: 380 381 BB_DANGLINGAPPENDS_WARNONLY = "1" 382 383 :term:`BB_DEFAULT_TASK` 384 See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual. 385 386 :term:`BB_DEFAULT_UMASK` 387 See :term:`bitbake:BB_DEFAULT_UMASK` in the BitBake manual. 388 389 :term:`BB_DISKMON_DIRS` 390 Monitors disk space and available inodes during the build and allows 391 you to control the build based on these parameters. 392 393 Disk space monitoring is disabled by default. To enable monitoring, 394 add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file 395 found in the :term:`Build Directory`. Use the 396 following form: 397 398 .. code-block:: none 399 400 BB_DISKMON_DIRS = "action,dir,threshold [...]" 401 402 where: 403 404 action is: 405 ABORT: Immediately stop the build when 406 a threshold is broken. 407 STOPTASKS: Stop the build after the currently 408 executing tasks have finished when 409 a threshold is broken. 410 WARN: Issue a warning but continue the 411 build when a threshold is broken. 412 Subsequent warnings are issued as 413 defined by the BB_DISKMON_WARNINTERVAL 414 variable, which must be defined in 415 the conf/local.conf file. 416 417 dir is: 418 Any directory you choose. You can specify one or 419 more directories to monitor by separating the 420 groupings with a space. If two directories are 421 on the same device, only the first directory 422 is monitored. 423 424 threshold is: 425 Either the minimum available disk space, 426 the minimum number of free inodes, or 427 both. You must specify at least one. To 428 omit one or the other, simply omit the value. 429 Specify the threshold using G, M, K for Gbytes, 430 Mbytes, and Kbytes, respectively. If you do 431 not specify G, M, or K, Kbytes is assumed by 432 default. Do not use GB, MB, or KB. 433 434 Here are some examples:: 435 436 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" 437 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" 438 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" 439 440 The first example works only if you also provide the 441 :term:`BB_DISKMON_WARNINTERVAL` 442 variable in the ``conf/local.conf``. This example causes the build 443 system to immediately stop when either the disk space in 444 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops 445 below 100 Kbytes. Because two directories are provided with the 446 variable, the build system also issue a warning when the disk space 447 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number 448 of free inodes drops below 100 Kbytes. Subsequent warnings are issued 449 during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL` 450 variable. 451 452 The second example stops the build after all currently executing 453 tasks complete when the minimum disk space in the ``${TMPDIR}`` 454 directory drops below 1 Gbyte. No disk monitoring occurs for the free 455 inodes in this case. 456 457 The final example immediately stops the build when the number of 458 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No 459 disk space monitoring for the directory itself occurs in this case. 460 461 :term:`BB_DISKMON_WARNINTERVAL` 462 Defines the disk space and free inode warning intervals. To set these 463 intervals, define the variable in your ``conf/local.conf`` file in 464 the :term:`Build Directory`. 465 466 If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you 467 must also use the :term:`BB_DISKMON_DIRS` 468 variable and define its action as "WARN". During the build, 469 subsequent warnings are issued each time disk space or number of free 470 inodes further reduces by the respective interval. 471 472 If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you 473 do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk 474 monitoring interval defaults to the following:: 475 476 BB_DISKMON_WARNINTERVAL = "50M,5K" 477 478 When specifying the variable in your configuration file, use the 479 following form: 480 481 .. code-block:: none 482 483 BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval" 484 485 where: 486 487 disk_space_interval is: 488 An interval of memory expressed in either 489 G, M, or K for Gbytes, Mbytes, or Kbytes, 490 respectively. You cannot use GB, MB, or KB. 491 492 disk_inode_interval is: 493 An interval of free inodes expressed in either 494 G, M, or K for Gbytes, Mbytes, or Kbytes, 495 respectively. You cannot use GB, MB, or KB. 496 497 Here is an example:: 498 499 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 500 BB_DISKMON_WARNINTERVAL = "50M,5K" 501 502 These variables cause the 503 OpenEmbedded build system to issue subsequent warnings each time the 504 available disk space further reduces by 50 Mbytes or the number of 505 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` 506 directory. Subsequent warnings based on the interval occur each time 507 a respective interval is reached beyond the initial warning (i.e. 1 508 Gbytes and 100 Kbytes). 509 510 :term:`BB_ENV_PASSTHROUGH` 511 See :term:`bitbake:BB_ENV_PASSTHROUGH` in the BitBake manual. 512 513 :term:`BB_ENV_PASSTHROUGH_ADDITIONS` 514 See :term:`bitbake:BB_ENV_PASSTHROUGH_ADDITIONS` in the BitBake manual. 515 516 :term:`BB_FETCH_PREMIRRORONLY` 517 See :term:`bitbake:BB_FETCH_PREMIRRORONLY` in the BitBake manual. 518 519 :term:`BB_FILENAME` 520 See :term:`bitbake:BB_FILENAME` in the BitBake manual. 521 522 :term:`BB_GENERATE_MIRROR_TARBALLS` 523 Causes tarballs of the source control repositories (e.g. Git 524 repositories), including metadata, to be placed in the 525 :term:`DL_DIR` directory. 526 527 For performance reasons, creating and placing tarballs of these 528 repositories is not the default action by the OpenEmbedded build 529 system:: 530 531 BB_GENERATE_MIRROR_TARBALLS = "1" 532 533 Set this variable in your 534 ``local.conf`` file in the :term:`Build Directory`. 535 536 Once you have the tarballs containing your source files, you can 537 clean up your :term:`DL_DIR` directory by deleting any Git or other 538 source control work directories. 539 540 :term:`BB_GENERATE_SHALLOW_TARBALLS` 541 See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual. 542 543 :term:`BB_GIT_SHALLOW` 544 See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual. 545 546 :term:`BB_GIT_SHALLOW_DEPTH` 547 See :term:`bitbake:BB_GIT_SHALLOW_DEPTH` in the BitBake manual. 548 549 :term:`BB_HASHCHECK_FUNCTION` 550 See :term:`bitbake:BB_HASHCHECK_FUNCTION` in the BitBake manual. 551 552 :term:`BB_HASHCONFIG_IGNORE_VARS` 553 See :term:`bitbake:BB_HASHCONFIG_IGNORE_VARS` in the BitBake manual. 554 555 :term:`BB_HASHSERVE` 556 See :term:`bitbake:BB_HASHSERVE` in the BitBake manual. 557 558 :term:`BB_HASHSERVE_UPSTREAM` 559 See :term:`bitbake:BB_HASHSERVE_UPSTREAM` in the BitBake manual. 560 561 :term:`BB_INVALIDCONF` 562 See :term:`bitbake:BB_INVALIDCONF` in the BitBake manual. 563 564 :term:`BB_LOADFACTOR_MAX` 565 The system load threshold above which BitBake will stop runnig extra 566 tasks. 567 568 :term:`BB_LOGCONFIG` 569 See :term:`bitbake:BB_LOGCONFIG` in the BitBake manual. 570 571 :term:`BB_LOGFMT` 572 See :term:`bitbake:BB_LOGFMT` in the BitBake manual. 573 574 :term:`BB_MULTI_PROVIDER_ALLOWED` 575 See :term:`bitbake:BB_MULTI_PROVIDER_ALLOWED` in the BitBake manual. 576 577 :term:`BB_NICE_LEVEL` 578 See :term:`bitbake:BB_NICE_LEVEL` in the BitBake manual. 579 580 :term:`BB_NO_NETWORK` 581 See :term:`bitbake:BB_NO_NETWORK` in the BitBake manual. 582 583 :term:`BB_NUMBER_PARSE_THREADS` 584 See :term:`bitbake:BB_NUMBER_PARSE_THREADS` in the BitBake manual. 585 586 :term:`BB_NUMBER_THREADS` 587 The maximum number of tasks BitBake should run in parallel at any one 588 time. The OpenEmbedded build system automatically configures this 589 variable to be equal to the number of cores on the build system. For 590 example, a system with a dual core processor that also uses 591 hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default 592 to "4". 593 594 For single socket systems (i.e. one CPU), you should not have to 595 override this variable to gain optimal parallelism during builds. 596 However, if you have very large systems that employ multiple physical 597 CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable 598 is not set higher than "20". 599 600 For more information on speeding up builds, see the 601 ":ref:`dev-manual/speeding-up-build:speeding up a build`" 602 section in the Yocto Project Development Tasks Manual. 603 604 On the other hand, if your goal is to limit the amount of system 605 resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS` 606 to a number lower than the number of CPU threads in your machine 607 won't be sufficient. That's because each package will still be built 608 and installed through a number of parallel jobs specified by the 609 :term:`PARALLEL_MAKE` variable, which is by default the number of CPU 610 threads in your system, and is not impacted by the 611 :term:`BB_NUMBER_THREADS` value. 612 613 So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set 614 :term:`PARALLEL_MAKE`, most of your system resources will be consumed 615 anyway. 616 617 Therefore, if you intend to reduce the load of your build system by 618 setting :term:`BB_NUMBER_THREADS` to a relatively low value compared 619 to the number of CPU threads on your system, you should also set 620 :term:`PARALLEL_MAKE` to a similarly low value. 621 622 An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage 623 of build system resources under control is to use the smarter 624 :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or 625 :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake 626 from starting new tasks as long as thresholds are exceeded. Anyway, 627 as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the 628 tasks already being run from using all CPU threads on the system 629 if :term:`PARALLEL_MAKE` is not set to a low value. 630 631 :term:`BB_ORIGENV` 632 See :term:`bitbake:BB_ORIGENV` in the BitBake manual. 633 634 :term:`BB_PRESERVE_ENV` 635 See :term:`bitbake:BB_PRESERVE_ENV` in the BitBake manual. 636 637 :term:`BB_PRESSURE_MAX_CPU` 638 See :term:`bitbake:BB_PRESSURE_MAX_CPU` in the BitBake manual. 639 640 :term:`BB_PRESSURE_MAX_IO` 641 See :term:`bitbake:BB_PRESSURE_MAX_IO` in the BitBake manual. 642 643 :term:`BB_PRESSURE_MAX_MEMORY` 644 See :term:`bitbake:BB_PRESSURE_MAX_MEMORY` in the BitBake manual. 645 646 :term:`BB_RUNFMT` 647 See :term:`bitbake:BB_RUNFMT` in the BitBake manual. 648 649 :term:`BB_RUNTASK` 650 See :term:`bitbake:BB_RUNTASK` in the BitBake manual. 651 652 :term:`BB_SCHEDULER` 653 See :term:`bitbake:BB_SCHEDULER` in the BitBake manual. 654 655 :term:`BB_SCHEDULERS` 656 See :term:`bitbake:BB_SCHEDULERS` in the BitBake manual. 657 658 :term:`BB_SERVER_TIMEOUT` 659 Specifies the time (in seconds) after which to unload the BitBake 660 server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how 661 long the BitBake server stays resident between invocations. 662 663 For example, the following statement in your ``local.conf`` file 664 instructs the server to be unloaded after 20 seconds of inactivity:: 665 666 BB_SERVER_TIMEOUT = "20" 667 668 If you want the server to never be unloaded, 669 set :term:`BB_SERVER_TIMEOUT` to "-1". 670 671 :term:`BB_SETSCENE_DEPVALID` 672 See :term:`bitbake:BB_SETSCENE_DEPVALID` in the BitBake manual. 673 674 :term:`BB_SIGNATURE_EXCLUDE_FLAGS` 675 See :term:`bitbake:BB_SIGNATURE_EXCLUDE_FLAGS` in the BitBake manual. 676 677 :term:`BB_SIGNATURE_HANDLER` 678 See :term:`bitbake:BB_SIGNATURE_HANDLER` in the BitBake manual. 679 680 :term:`BB_SRCREV_POLICY` 681 See :term:`bitbake:BB_SRCREV_POLICY` in the BitBake manual. 682 683 :term:`BB_STRICT_CHECKSUM` 684 See :term:`bitbake:BB_STRICT_CHECKSUM` in the BitBake manual. 685 686 :term:`BB_TASK_IONICE_LEVEL` 687 See :term:`bitbake:BB_TASK_IONICE_LEVEL` in the BitBake manual. 688 689 :term:`BB_TASK_NICE_LEVEL` 690 See :term:`bitbake:BB_TASK_NICE_LEVEL` in the BitBake manual. 691 692 :term:`BB_TASKHASH` 693 See :term:`bitbake:BB_TASKHASH` in the BitBake manual. 694 695 :term:`BB_VERBOSE_LOGS` 696 See :term:`bitbake:BB_VERBOSE_LOGS` in the BitBake manual. 697 698 :term:`BB_WORKERCONTEXT` 699 See :term:`bitbake:BB_WORKERCONTEXT` in the BitBake manual. 700 701 :term:`BBCLASSEXTEND` 702 Allows you to extend a recipe so that it builds variants of the 703 software. There are common variants for recipes as "natives" like 704 ``quilt-native``, which is a copy of Quilt built to run on the build 705 system; "crosses" such as ``gcc-cross``, which is a compiler built to 706 run on the build machine but produces binaries that run on the target 707 :term:`MACHINE`; ":ref:`ref-classes-nativesdk`", which 708 targets the SDK machine instead of :term:`MACHINE`; and "mulitlibs" in 709 the form "``multilib:``\ multilib_name". 710 711 To build a different variant of the recipe with a minimal amount of 712 code, it usually is as simple as adding the following to your recipe:: 713 714 BBCLASSEXTEND =+ "native nativesdk" 715 BBCLASSEXTEND =+ "multilib:multilib_name" 716 717 .. note:: 718 719 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe 720 variants by rewriting variable values and applying overrides such 721 as ``:class-native``. For example, to generate a native version of 722 a recipe, a :term:`DEPENDS` on "foo" is rewritten 723 to a :term:`DEPENDS` on "foo-native". 724 725 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. 726 Parsing once adds some limitations. For example, it is not 727 possible to include a different file depending on the variant, 728 since ``include`` statements are processed when the recipe is 729 parsed. 730 731 :term:`BBDEBUG` 732 See :term:`bitbake:BBDEBUG` in the BitBake manual. 733 734 :term:`BBFILE_COLLECTIONS` 735 Lists the names of configured layers. These names are used to find 736 the other ``BBFILE_*`` variables. Typically, each layer will append 737 its name to this variable in its ``conf/layer.conf`` file. 738 739 :term:`BBFILE_PATTERN` 740 Variable that expands to match files from 741 :term:`BBFILES` in a particular layer. This variable 742 is used in the ``conf/layer.conf`` file and must be suffixed with the 743 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). 744 745 :term:`BBFILE_PRIORITY` 746 Assigns the priority for recipe files in each layer. 747 748 This variable is useful in situations where the same recipe appears 749 in more than one layer. Setting this variable allows you to 750 prioritize a layer against other layers that contain the same recipe 751 --- effectively letting you control the precedence for the multiple 752 layers. The precedence established through this variable stands 753 regardless of a recipe's version (:term:`PV` variable). For 754 example, a layer that has a recipe with a higher :term:`PV` value but for 755 which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still 756 has a lower precedence. 757 758 A larger value for the :term:`BBFILE_PRIORITY` variable results in a 759 higher precedence. For example, the value 6 has a higher precedence 760 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable 761 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable 762 for more information. The default priority, if unspecified for a 763 layer with no dependencies, is the lowest defined priority + 1 (or 1 764 if no priorities are defined). 765 766 .. tip:: 767 768 You can use the command ``bitbake-layers show-layers`` 769 to list all configured layers along with their priorities. 770 771 :term:`BBFILES` 772 A space-separated list of recipe files BitBake uses to build 773 software. 774 775 When specifying recipe files, you can pattern match using Python's 776 `glob <https://docs.python.org/3/library/glob.html>`__ syntax. 777 For details on the syntax, see the documentation by following the 778 previous link. 779 780 :term:`BBFILES_DYNAMIC` 781 Activates content when identified layers are present. You identify 782 the layers by the collections that the layers define. 783 784 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files 785 whose corresponding ``.bb`` file is in a layer that attempts to 786 modify other layers through ``.bbappend`` but does not want to 787 introduce a hard dependency on those other layers. 788 789 Use the following form for :term:`BBFILES_DYNAMIC`: 790 ``collection_name:filename_pattern``. 791 792 The following example identifies two collection names and two 793 filename patterns:: 794 795 BBFILES_DYNAMIC += " \ 796 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ 797 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ 798 " 799 800 This next example shows an error message that occurs because invalid 801 entries are found, which cause parsing to fail: 802 803 .. code-block:: none 804 805 ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not: 806 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend 807 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend 808 809 :term:`BBINCLUDED` 810 See :term:`bitbake:BBINCLUDED` in the BitBake manual. 811 812 :term:`BBINCLUDELOGS` 813 Variable that controls how BitBake displays logs on build failure. 814 815 :term:`BBINCLUDELOGS_LINES` 816 If :term:`BBINCLUDELOGS` is set, specifies the 817 maximum number of lines from the task log file to print when 818 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, 819 the entire log is printed. 820 821 :term:`BBLAYERS` 822 Lists the layers to enable during the build. This variable is defined 823 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. 824 Here is an example:: 825 826 BBLAYERS = " \ 827 /home/scottrif/poky/meta \ 828 /home/scottrif/poky/meta-poky \ 829 /home/scottrif/poky/meta-yocto-bsp \ 830 /home/scottrif/poky/meta-mykernel \ 831 " 832 833 This example enables four layers, one of which is a custom, 834 user-defined layer named ``meta-mykernel``. 835 836 :term:`BBLAYERS_FETCH_DIR` 837 See :term:`bitbake:BBLAYERS_FETCH_DIR` in the BitBake manual. 838 839 :term:`BBMASK` 840 Prevents BitBake from processing recipes and recipe append files. 841 842 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and 843 ``.bbappend`` files. BitBake ignores any recipe or recipe append 844 files that match any of the expressions. It is as if BitBake does not 845 see them at all. Consequently, matching files are not parsed or 846 otherwise used by BitBake. 847 848 The values you provide are passed to Python's regular expression 849 compiler. Consequently, the syntax follows Python's Regular 850 Expression (re) syntax. The expressions are compared against the full 851 paths to the files. For complete syntax information, see Python's 852 documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax. 853 854 The following example uses a complete regular expression to tell 855 BitBake to ignore all recipe and recipe append files in the 856 ``meta-ti/recipes-misc/`` directory:: 857 858 BBMASK = "meta-ti/recipes-misc/" 859 860 If you want to mask out multiple directories or recipes, you can 861 specify multiple regular expression fragments. This next example 862 masks out multiple directories and individual recipes:: 863 864 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" 865 BBMASK += "/meta-oe/recipes-support/" 866 BBMASK += "/meta-foo/.*/openldap" 867 BBMASK += "opencv.*\.bbappend" 868 BBMASK += "lzma" 869 870 .. note:: 871 872 When specifying a directory name, use the trailing slash character 873 to ensure you match just that directory name. 874 875 :term:`BBMULTICONFIG` 876 Specifies each additional separate configuration when you are 877 building targets with multiple configurations. Use this variable in 878 your ``conf/local.conf`` configuration file. Specify a 879 multiconfigname for each configuration file you are using. For 880 example, the following line specifies three configuration files:: 881 882 BBMULTICONFIG = "configA configB configC" 883 884 Each configuration file you use must reside in a ``multiconfig`` 885 subdirectory of a configuration directory within a layer, or 886 within the :term:`Build Directory` (e.g. 887 ``build_directory/conf/multiconfig/configA.conf`` or 888 ``mylayer/conf/multiconfig/configB.conf``). 889 890 For information on how to use :term:`BBMULTICONFIG` in an environment 891 that supports building targets with multiple configurations, see the 892 ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" 893 section in the Yocto Project Development Tasks Manual. 894 895 :term:`BBPATH` 896 See :term:`bitbake:BBPATH` in the BitBake manual. 897 898 :term:`BBSERVER` 899 If defined in the BitBake environment, :term:`BBSERVER` points to the 900 BitBake remote server. 901 902 Use the following format to export the variable to the BitBake 903 environment:: 904 905 export BBSERVER=localhost:$port 906 907 By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`. 908 Consequently, :term:`BBSERVER` is excluded from checksum and dependency 909 data. 910 911 :term:`BBTARGETS` 912 See :term:`bitbake:BBTARGETS` in the BitBake manual. 913 914 :term:`BINCONFIG` 915 When inheriting the :ref:`ref-classes-binconfig-disabled` class, this 916 variable specifies binary configuration scripts to disable in favor of 917 using ``pkg-config`` to query the information. The 918 :ref:`ref-classes-binconfig-disabled` class will modify the specified 919 scripts to return an error so that calls to them can be easily found 920 and replaced. 921 922 To add multiple scripts, separate them by spaces. Here is an example 923 from the ``libpng`` recipe:: 924 925 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" 926 927 :term:`BINCONFIG_GLOB` 928 When inheriting the :ref:`ref-classes-binconfig` class, 929 this variable specifies a wildcard for configuration scripts that 930 need editing. The scripts are edited to correct any paths that have 931 been set up during compilation so that they are correct for use when 932 installed into the sysroot and called by the build processes of other 933 recipes. 934 935 .. note:: 936 937 The :term:`BINCONFIG_GLOB` variable uses 938 `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, 939 which is recognition and expansion of wildcards during pattern 940 matching. Shell globbing is very similar to 941 `fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__ 942 and `glob <https://docs.python.org/3/library/glob.html>`__. 943 944 For more information on how this variable works, see 945 ``meta/classes-recipe/binconfig.bbclass`` in the :term:`Source Directory`. 946 You can also find general 947 information on the class in the 948 ":ref:`ref-classes-binconfig`" section. 949 950 :term:`BITBAKE_UI` 951 See :term:`bitbake:BITBAKE_UI` in the BitBake manual. 952 953 :term:`BP` 954 The base recipe name and version but without any special recipe name 955 suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is 956 comprised of the following:: 957 958 ${BPN}-${PV} 959 960 :term:`BPN` 961 This variable is a version of the :term:`PN` variable with 962 common prefixes and suffixes removed, such as ``nativesdk-``, 963 ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``. 964 The exact lists of prefixes and suffixes removed are specified by the 965 :term:`MLPREFIX` and 966 :term:`SPECIAL_PKGSUFFIX` variables, 967 respectively. 968 969 :term:`BUGTRACKER` 970 Specifies a URL for an upstream bug tracking website for a recipe. 971 The OpenEmbedded build system does not use this variable. Rather, the 972 variable is a useful pointer in case a bug in the software being 973 built needs to be manually reported. 974 975 :term:`BUILD_ARCH` 976 Specifies the architecture of the build host (e.g. ``i686``). The 977 OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the 978 machine name reported by the ``uname`` command. 979 980 :term:`BUILD_AS_ARCH` 981 Specifies the architecture-specific assembler flags for the build 982 host. By default, the value of :term:`BUILD_AS_ARCH` is empty. 983 984 :term:`BUILD_CC_ARCH` 985 Specifies the architecture-specific C compiler flags for the build 986 host. By default, the value of :term:`BUILD_CC_ARCH` is empty. 987 988 :term:`BUILD_CCLD` 989 Specifies the linker command to be used for the build host when the C 990 compiler is being used as the linker. By default, :term:`BUILD_CCLD` 991 points to GCC and passes as arguments the value of 992 :term:`BUILD_CC_ARCH`, assuming 993 :term:`BUILD_CC_ARCH` is set. 994 995 :term:`BUILD_CFLAGS` 996 Specifies the flags to pass to the C compiler when building for the 997 build host. When building in the ``-native`` context, 998 :term:`CFLAGS` is set to the value of this variable by 999 default. 1000 1001 :term:`BUILD_CPPFLAGS` 1002 Specifies the flags to pass to the C preprocessor (i.e. to both the C 1003 and the C++ compilers) when building for the build host. When 1004 building in the ``-native`` context, :term:`CPPFLAGS` 1005 is set to the value of this variable by default. 1006 1007 :term:`BUILD_CXXFLAGS` 1008 Specifies the flags to pass to the C++ compiler when building for the 1009 build host. When building in the ``-native`` context, 1010 :term:`CXXFLAGS` is set to the value of this variable 1011 by default. 1012 1013 :term:`BUILD_FC` 1014 Specifies the Fortran compiler command for the build host. By 1015 default, :term:`BUILD_FC` points to Gfortran and passes as arguments the 1016 value of :term:`BUILD_CC_ARCH`, assuming 1017 :term:`BUILD_CC_ARCH` is set. 1018 1019 :term:`BUILD_LD` 1020 Specifies the linker command for the build host. By default, 1021 :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments 1022 the value of :term:`BUILD_LD_ARCH`, assuming 1023 :term:`BUILD_LD_ARCH` is set. 1024 1025 :term:`BUILD_LD_ARCH` 1026 Specifies architecture-specific linker flags for the build host. By 1027 default, the value of :term:`BUILD_LD_ARCH` is empty. 1028 1029 :term:`BUILD_LDFLAGS` 1030 Specifies the flags to pass to the linker when building for the build 1031 host. When building in the ``-native`` context, 1032 :term:`LDFLAGS` is set to the value of this variable 1033 by default. 1034 1035 :term:`BUILD_OPTIMIZATION` 1036 Specifies the optimization flags passed to the C compiler when 1037 building for the build host or the SDK. The flags are passed through 1038 the :term:`BUILD_CFLAGS` and 1039 :term:`BUILDSDK_CFLAGS` default values. 1040 1041 The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2 1042 -pipe". 1043 1044 :term:`BUILD_OS` 1045 Specifies the operating system in use on the build host (e.g. 1046 "linux"). The OpenEmbedded build system sets the value of 1047 :term:`BUILD_OS` from the OS reported by the ``uname`` command --- the 1048 first word, converted to lower-case characters. 1049 1050 :term:`BUILD_PREFIX` 1051 The toolchain binary prefix used for native recipes. The OpenEmbedded 1052 build system uses the :term:`BUILD_PREFIX` value to set the 1053 :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes. 1054 1055 :term:`BUILD_STRIP` 1056 Specifies the command to be used to strip debugging symbols from 1057 binaries produced for the build host. By default, :term:`BUILD_STRIP` 1058 points to 1059 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. 1060 1061 :term:`BUILD_SYS` 1062 Specifies the system, including the architecture and the operating 1063 system, to use when building for the build host (i.e. when building 1064 :ref:`ref-classes-native` recipes). 1065 1066 The OpenEmbedded build system automatically sets this variable based 1067 on :term:`BUILD_ARCH`, 1068 :term:`BUILD_VENDOR`, and 1069 :term:`BUILD_OS`. You do not need to set the 1070 :term:`BUILD_SYS` variable yourself. 1071 1072 :term:`BUILD_VENDOR` 1073 Specifies the vendor name to use when building for the build host. 1074 The default value is an empty string (""). 1075 1076 :term:`BUILDDIR` 1077 Points to the location of the :term:`Build Directory`. You can define 1078 this directory indirectly through the :ref:`structure-core-script` script 1079 by passing in a :term:`Build Directory` path when you run the script. If 1080 you run the script and do not provide a :term:`Build Directory` path, the 1081 :term:`BUILDDIR` defaults to ``build`` in the current directory. 1082 1083 :term:`BUILDHISTORY_COMMIT` 1084 When inheriting the :ref:`ref-classes-buildhistory` class, this variable 1085 specifies whether or not to commit the build history output in a local 1086 Git repository. If set to "1", this local repository will be maintained 1087 automatically by the :ref:`ref-classes-buildhistory` class and a commit 1088 will be created on every build for changes to each top-level subdirectory 1089 of the build history output (images, packages, and sdk). If you want to 1090 track changes to build history over time, you should set this value to 1091 "1". 1092 1093 By default, the :ref:`ref-classes-buildhistory` class 1094 enables committing the buildhistory output in a local Git repository:: 1095 1096 BUILDHISTORY_COMMIT ?= "1" 1097 1098 :term:`BUILDHISTORY_COMMIT_AUTHOR` 1099 When inheriting the :ref:`ref-classes-buildhistory` 1100 class, this variable specifies the author to use for each Git commit. 1101 In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the 1102 :term:`BUILDHISTORY_COMMIT` variable must 1103 be set to "1". 1104 1105 Git requires that the value you provide for the 1106 :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name 1107 email@host". Providing an email address or host that is not valid 1108 does not produce an error. 1109 1110 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1111 as follows:: 1112 1113 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" 1114 1115 :term:`BUILDHISTORY_DIR` 1116 When inheriting the :ref:`ref-classes-buildhistory` 1117 class, this variable specifies the directory in which build history 1118 information is kept. For more information on how the variable works, 1119 see the :ref:`ref-classes-buildhistory` class. 1120 1121 By default, the :ref:`ref-classes-buildhistory` class sets the directory 1122 as follows:: 1123 1124 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" 1125 1126 :term:`BUILDHISTORY_FEATURES` 1127 When inheriting the :ref:`ref-classes-buildhistory` 1128 class, this variable specifies the build history features to be 1129 enabled. For more information on how build history works, see the 1130 ":ref:`dev-manual/build-quality:maintaining build output quality`" 1131 section in the Yocto Project Development Tasks Manual. 1132 1133 You can specify these features in the form of a space-separated list: 1134 1135 - *image:* Analysis of the contents of images, which includes the 1136 list of installed packages among other things. 1137 1138 - *package:* Analysis of the contents of individual packages. 1139 1140 - *sdk:* Analysis of the contents of the software development kit 1141 (SDK). 1142 1143 - *task:* Save output file signatures for 1144 :ref:`shared state <overview-manual/concepts:shared state cache>` 1145 (sstate) tasks. 1146 This saves one file per task and lists the SHA-256 checksums for 1147 each file staged (i.e. the output of the task). 1148 1149 By default, the :ref:`ref-classes-buildhistory` class enables the 1150 following features:: 1151 1152 BUILDHISTORY_FEATURES ?= "image package sdk" 1153 1154 :term:`BUILDHISTORY_IMAGE_FILES` 1155 When inheriting the :ref:`ref-classes-buildhistory` 1156 class, this variable specifies a list of paths to files copied from 1157 the image contents into the build history directory under an 1158 "image-files" directory in the directory for the image, so that you 1159 can track the contents of each file. The default is to copy 1160 ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for 1161 changes in user and group entries. You can modify the list to include 1162 any file. Specifying an invalid path does not produce an error. 1163 Consequently, you can include files that might not always be present. 1164 1165 By default, the :ref:`ref-classes-buildhistory` class provides paths to 1166 the following files:: 1167 1168 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" 1169 1170 :term:`BUILDHISTORY_PATH_PREFIX_STRIP` 1171 When inheriting the :ref:`ref-classes-buildhistory` 1172 class, this variable specifies a common path prefix that should be 1173 stripped off the beginning of paths in the task signature list when the 1174 ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be 1175 useful when build history is populated from multiple sources that may not 1176 all use the same top level directory. 1177 1178 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1179 as follows:: 1180 1181 BUILDHISTORY_PATH_PREFIX_STRIP ?= "" 1182 1183 In this case, no prefixes will be stripped. 1184 1185 :term:`BUILDHISTORY_PUSH_REPO` 1186 When inheriting the :ref:`ref-classes-buildhistory` class, this variable 1187 optionally specifies a remote repository to which build history pushes 1188 Git changes. In order for :term:`BUILDHISTORY_PUSH_REPO` to work, 1189 :term:`BUILDHISTORY_COMMIT` must be set to "1". 1190 1191 The repository should correspond to a remote address that specifies a 1192 repository as understood by Git, or alternatively to a remote name 1193 that you have set up manually using ``git remote`` within the local 1194 repository. 1195 1196 By default, the :ref:`ref-classes-buildhistory` class sets the variable 1197 as follows:: 1198 1199 BUILDHISTORY_PUSH_REPO ?= "" 1200 1201 :term:`BUILDNAME` 1202 See :term:`bitbake:BUILDNAME` in the BitBake manual. 1203 1204 :term:`BUILDSDK_CFLAGS` 1205 Specifies the flags to pass to the C compiler when building for the 1206 SDK. When building in the ``nativesdk-`` context, 1207 :term:`CFLAGS` is set to the value of this variable by 1208 default. 1209 1210 :term:`BUILDSDK_CPPFLAGS` 1211 Specifies the flags to pass to the C pre-processor (i.e. to both the 1212 C and the C++ compilers) when building for the SDK. When building in 1213 the ``nativesdk-`` context, :term:`CPPFLAGS` is set 1214 to the value of this variable by default. 1215 1216 :term:`BUILDSDK_CXXFLAGS` 1217 Specifies the flags to pass to the C++ compiler when building for the 1218 SDK. When building in the ``nativesdk-`` context, 1219 :term:`CXXFLAGS` is set to the value of this variable 1220 by default. 1221 1222 :term:`BUILDSDK_LDFLAGS` 1223 Specifies the flags to pass to the linker when building for the SDK. 1224 When building in the ``nativesdk-`` context, 1225 :term:`LDFLAGS` is set to the value of this variable 1226 by default. 1227 1228 :term:`BUILDSTATS_BASE` 1229 Points to the location of the directory that holds build statistics 1230 when you use and enable the :ref:`ref-classes-buildstats` class. The 1231 :term:`BUILDSTATS_BASE` directory defaults to 1232 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. 1233 1234 :term:`BUSYBOX_SPLIT_SUID` 1235 For the BusyBox recipe, specifies whether to split the output 1236 executable file into two parts: one for features that require 1237 ``setuid root``, and one for the remaining features (i.e. those that 1238 do not require ``setuid root``). 1239 1240 The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in 1241 splitting the output executable file. Set the variable to "0" to get 1242 a single output executable file. 1243 1244 :term:`BZRDIR` 1245 See :term:`bitbake:BZRDIR` in the BitBake manual. 1246 1247 :term:`CACHE` 1248 Specifies the directory BitBake uses to store a cache of the 1249 :term:`Metadata` so it does not need to be parsed every time 1250 BitBake is started. 1251 1252 :term:`CC` 1253 The minimal command and arguments used to run the C compiler. 1254 1255 :term:`CFLAGS` 1256 Specifies the flags to pass to the C compiler. This variable is 1257 exported to an environment variable and thus made visible to the 1258 software being built during the compilation step. 1259 1260 Default initialization for :term:`CFLAGS` varies depending on what is 1261 being built: 1262 1263 - :term:`TARGET_CFLAGS` when building for the 1264 target 1265 1266 - :term:`BUILD_CFLAGS` when building for the 1267 build host (i.e. ``-native``) 1268 1269 - :term:`BUILDSDK_CFLAGS` when building for 1270 an SDK (i.e. ``nativesdk-``) 1271 1272 :term:`CLASSOVERRIDE` 1273 An internal variable specifying the special class override that 1274 should currently apply (e.g. "class-target", "class-native", and so 1275 forth). The classes that use this variable (e.g. 1276 :ref:`ref-classes-native`, :ref:`ref-classes-nativesdk`, and so forth) 1277 set the variable to appropriate values. 1278 1279 .. note:: 1280 1281 :term:`CLASSOVERRIDE` gets its default "class-target" value from the 1282 ``bitbake.conf`` file. 1283 1284 As an example, the following override allows you to install extra 1285 files, but only when building for the target:: 1286 1287 do_install:append:class-target() { 1288 install my-extra-file ${D}${sysconfdir} 1289 } 1290 1291 Here is an example where ``FOO`` is set to 1292 "native" when building for the build host, and to "other" when not 1293 building for the build host:: 1294 1295 FOO:class-native = "native" 1296 FOO = "other" 1297 1298 The underlying mechanism behind :term:`CLASSOVERRIDE` is simply 1299 that it is included in the default value of 1300 :term:`OVERRIDES`. 1301 1302 :term:`CLEANBROKEN` 1303 If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the 1304 ``make clean`` command does not work for the software being built. 1305 Consequently, the OpenEmbedded build system will not try to run 1306 ``make clean`` during the :ref:`ref-tasks-configure` 1307 task, which is the default behavior. 1308 1309 :term:`COMBINED_FEATURES` 1310 Provides a list of hardware features that are enabled in both 1311 :term:`MACHINE_FEATURES` and 1312 :term:`DISTRO_FEATURES`. This select list of 1313 features contains features that make sense to be controlled both at 1314 the machine and distribution configuration level. For example, the 1315 "bluetooth" feature requires hardware support but should also be 1316 optional at the distribution level, in case the hardware supports 1317 Bluetooth but you do not ever intend to use it. 1318 1319 :term:`COMMERCIAL_AUDIO_PLUGINS` 1320 This variable is specific to the :yocto_git:`GStreamer recipes 1321 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. 1322 It allows to build the GStreamer `"ugly" 1323 <https://github.com/GStreamer/gst-plugins-ugly>`__ and 1324 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins. 1325 1326 See the :ref:`dev-manual/licenses:other variables related to commercial licenses` 1327 section for usage details. 1328 1329 :term:`COMMERCIAL_VIDEO_PLUGINS` 1330 This variable is specific to the :yocto_git:`GStreamer recipes 1331 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. 1332 It allows to build the GStreamer `"ugly" 1333 <https://github.com/GStreamer/gst-plugins-ugly>`__ and 1334 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins. 1335 1336 See the :ref:`dev-manual/licenses:other variables related to commercial licenses` 1337 section for usage details. 1338 1339 :term:`COMMON_LICENSE_DIR` 1340 Points to ``meta/files/common-licenses`` in the 1341 :term:`Source Directory`, which is where generic license 1342 files reside. 1343 1344 :term:`COMPATIBLE_HOST` 1345 A regular expression that resolves to one or more hosts (when the 1346 recipe is native) or one or more targets (when the recipe is 1347 non-native) with which a recipe is compatible. The regular expression 1348 is matched against :term:`HOST_SYS`. You can use the 1349 variable to stop recipes from being built for classes of systems with 1350 which the recipes are not compatible. Stopping these builds is 1351 particularly useful with kernels. The variable also helps to increase 1352 parsing speed since the build system skips parsing recipes not 1353 compatible with the current system. 1354 1355 :term:`COMPATIBLE_MACHINE` 1356 A regular expression that resolves to one or more target machines 1357 with which a recipe is compatible. The regular expression is matched 1358 against :term:`MACHINEOVERRIDES`. You can use 1359 the variable to stop recipes from being built for machines with which 1360 the recipes are not compatible. Stopping these builds is particularly 1361 useful with kernels. The variable also helps to increase parsing 1362 speed since the build system skips parsing recipes not compatible 1363 with the current machine. 1364 1365 If one wants to have a recipe only available for some architectures 1366 (here ``aarch64`` and ``mips64``), the following can be used:: 1367 1368 COMPATIBLE_MACHINE = "^$" 1369 COMPATIBLE_MACHINE:arch64 = "^(aarch64)$" 1370 COMPATIBLE_MACHINE:mips64 = "^(mips64)$" 1371 1372 The first line means "match all machines whose :term:`MACHINEOVERRIDES` 1373 contains the empty string", which will always be none. 1374 1375 The second is for matching all machines whose :term:`MACHINEOVERRIDES` 1376 contains one override which is exactly ``aarch64``. 1377 1378 The third is for matching all machines whose :term:`MACHINEOVERRIDES` 1379 contains one override which is exactly ``mips64``. 1380 1381 The same could be achieved with:: 1382 1383 COMPATIBLE_MACHINE = "^(aarch64|mips64)$" 1384 1385 .. note:: 1386 1387 When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from 1388 native, the recipe is always skipped. All native recipes must be 1389 entirely target independent and should not rely on :term:`MACHINE`. 1390 1391 :term:`COMPLEMENTARY_GLOB` 1392 Defines wildcards to match when installing a list of complementary 1393 packages for all the packages explicitly (or implicitly) installed in 1394 an image. 1395 1396 The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching 1397 (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), 1398 which is similar to the Unix style pathname pattern expansion 1399 (`glob <https://docs.python.org/3/library/glob.html>`__). 1400 1401 The resulting list of complementary packages is associated with an 1402 item that can be added to 1403 :term:`IMAGE_FEATURES`. An example usage of 1404 this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES` 1405 will install -dev packages (containing headers and other development 1406 files) for every package in the image. 1407 1408 To add a new feature item pointing to a wildcard, use a variable flag 1409 to specify the feature item name and use the value to specify the 1410 wildcard. Here is an example:: 1411 1412 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' 1413 1414 .. note:: 1415 1416 When installing complementary packages, recommends relationships 1417 (set via :term:`RRECOMMENDS`) are always ignored. 1418 1419 :term:`COMPONENTS_DIR` 1420 Stores sysroot components for each recipe. The OpenEmbedded build 1421 system uses :term:`COMPONENTS_DIR` when constructing recipe-specific 1422 sysroots for other recipes. 1423 1424 The default is 1425 "``${``\ :term:`STAGING_DIR`\ ``}-components``." 1426 (i.e. 1427 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). 1428 1429 :term:`CONF_VERSION` 1430 Tracks the version of the local configuration file (i.e. 1431 ``local.conf``). The value for :term:`CONF_VERSION` increments each time 1432 ``build/conf/`` compatibility changes. 1433 1434 :term:`CONFFILES` 1435 Identifies editable or configurable files that are part of a package. 1436 If the Package Management System (PMS) is being used to update 1437 packages on the target system, it is possible that configuration 1438 files you have changed after the original installation and that you 1439 now want to remain unchanged are overwritten. In other words, 1440 editable files might exist in the package that you do not want reset 1441 as part of the package update process. You can use the :term:`CONFFILES` 1442 variable to list the files in the package that you wish to prevent 1443 the PMS from overwriting during this update process. 1444 1445 To use the :term:`CONFFILES` variable, provide a package name override 1446 that identifies the resulting package. Then, provide a 1447 space-separated list of files. Here is an example:: 1448 1449 CONFFILES:${PN} += "${sysconfdir}/file1 \ 1450 ${sysconfdir}/file2 ${sysconfdir}/file3" 1451 1452 There is a relationship between the :term:`CONFFILES` and :term:`FILES` 1453 variables. The files listed within :term:`CONFFILES` must be a subset of 1454 the files listed within :term:`FILES`. Because the configuration files 1455 you provide with :term:`CONFFILES` are simply being identified so that 1456 the PMS will not overwrite them, it makes sense that the files must 1457 already be included as part of the package through the :term:`FILES` 1458 variable. 1459 1460 .. note:: 1461 1462 When specifying paths as part of the :term:`CONFFILES` variable, it is 1463 good practice to use appropriate path variables. 1464 For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` 1465 rather than ``/usr/bin``. You can find a list of these variables at 1466 the top of the ``meta/conf/bitbake.conf`` file in the 1467 :term:`Source Directory`. 1468 1469 :term:`CONFIG_INITRAMFS_SOURCE` 1470 Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The 1471 OpenEmbedded build system receives and uses this kernel Kconfig 1472 variable as an environment variable. By default, the variable is set 1473 to null (""). 1474 1475 The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive 1476 with a ``.cpio`` suffix or a space-separated list of directories and 1477 files for building the :term:`Initramfs` image. A cpio archive should contain 1478 a filesystem archive to be used as an :term:`Initramfs` image. Directories 1479 should contain a filesystem layout to be included in the :term:`Initramfs` 1480 image. Files should contain entries according to the format described 1481 by the ``usr/gen_init_cpio`` program in the kernel tree. 1482 1483 If you specify multiple directories and files, the :term:`Initramfs` image 1484 will be the aggregate of all of them. 1485 1486 For information on creating an :term:`Initramfs`, see the 1487 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 1488 in the Yocto Project Development Tasks Manual. 1489 1490 :term:`CONFIG_SITE` 1491 A list of files that contains ``autoconf`` test results relevant to 1492 the current build. This variable is used by the Autotools utilities 1493 when running ``configure``. 1494 1495 :term:`CONFIGURE_FLAGS` 1496 The minimal arguments for GNU configure. 1497 1498 :term:`CONFLICT_DISTRO_FEATURES` 1499 When inheriting the :ref:`ref-classes-features_check` 1500 class, this variable identifies distribution features that would be 1501 in conflict should the recipe be built. In other words, if the 1502 :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also 1503 appears in :term:`DISTRO_FEATURES` within the current configuration, then 1504 the recipe will be skipped, and if the build system attempts to build 1505 the recipe then an error will be triggered. 1506 1507 :term:`CONVERSION_CMD` 1508 This variable is used for storing image conversion commands. 1509 Image conversion can convert an image into different objects like: 1510 1511 - Compressed version of the image 1512 1513 - Checksums for the image 1514 1515 An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types` 1516 class is:: 1517 1518 CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}" 1519 1520 :term:`COPY_LIC_DIRS` 1521 If set to "1" along with the 1522 :term:`COPY_LIC_MANIFEST` variable, the 1523 OpenEmbedded build system copies into the image the license files, 1524 which are located in ``/usr/share/common-licenses``, for each 1525 package. The license files are placed in directories within the image 1526 itself during build time. 1527 1528 .. note:: 1529 1530 The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for 1531 newly installed packages to an image, which might be most suitable for 1532 read-only filesystems that cannot be upgraded. See the 1533 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1534 You can also reference the ":ref:`dev-manual/licenses:providing license text`" 1535 section in the Yocto Project Development Tasks Manual for 1536 information on providing license text. 1537 1538 :term:`COPY_LIC_MANIFEST` 1539 If set to "1", the OpenEmbedded build system copies the license 1540 manifest for the image to 1541 ``/usr/share/common-licenses/license.manifest`` within the image 1542 itself during build time. 1543 1544 .. note:: 1545 1546 The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for 1547 newly installed packages to an image, which might be most suitable for 1548 read-only filesystems that cannot be upgraded. See the 1549 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1550 You can also reference the ":ref:`dev-manual/licenses:providing license text`" 1551 section in the Yocto Project Development Tasks Manual for 1552 information on providing license text. 1553 1554 :term:`COPYLEFT_LICENSE_EXCLUDE` 1555 A space-separated list of licenses to exclude from the source archived by 1556 the :ref:`ref-classes-archiver` class. In other words, if a license in a 1557 recipe's :term:`LICENSE` value is in the value of 1558 :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the 1559 class. 1560 1561 .. note:: 1562 1563 The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the 1564 :term:`COPYLEFT_LICENSE_INCLUDE` variable. 1565 1566 The default value, which is "CLOSED Proprietary", for 1567 :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the 1568 :ref:`ref-classes-copyleft_filter` class, which 1569 is inherited by the :ref:`ref-classes-archiver` class. 1570 1571 :term:`COPYLEFT_LICENSE_INCLUDE` 1572 A space-separated list of licenses to include in the source archived 1573 by the :ref:`ref-classes-archiver` class. In other 1574 words, if a license in a recipe's :term:`LICENSE` 1575 value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its 1576 source is archived by the class. 1577 1578 The default value is set by the :ref:`ref-classes-copyleft_filter` class, 1579 which is inherited by the :ref:`ref-classes-archiver` class. The default 1580 value includes "GPL*", "LGPL*", and "AGPL*". 1581 1582 :term:`COPYLEFT_PN_EXCLUDE` 1583 A list of recipes to exclude in the source archived by the 1584 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_EXCLUDE` 1585 variable overrides the license inclusion and exclusion caused through the 1586 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` 1587 variables, respectively. 1588 1589 The default value, which is "" indicating to not explicitly exclude 1590 any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the 1591 :ref:`ref-classes-copyleft_filter` class, which is inherited by the 1592 :ref:`ref-classes-archiver` class. 1593 1594 :term:`COPYLEFT_PN_INCLUDE` 1595 A list of recipes to include in the source archived by the 1596 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_INCLUDE` 1597 variable overrides the license inclusion and exclusion caused through the 1598 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` 1599 variables, respectively. 1600 1601 The default value, which is "" indicating to not explicitly include 1602 any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the 1603 :ref:`ref-classes-copyleft_filter` class, which is inherited by the 1604 :ref:`ref-classes-archiver` class. 1605 1606 :term:`COPYLEFT_RECIPE_TYPES` 1607 A space-separated list of recipe types to include in the source 1608 archived by the :ref:`archiver <ref-classes-archiver>` class. 1609 Recipe types are ``target``, :ref:`ref-classes-native`, 1610 :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`, 1611 :ref:`ref-classes-crosssdk`, and :ref:`ref-classes-cross-canadian`. 1612 1613 The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES` 1614 is set by the :ref:`ref-classes-copyleft_filter` class, which is 1615 inherited by the :ref:`ref-classes-archiver` class. 1616 1617 :term:`CORE_IMAGE_EXTRA_INSTALL` 1618 Specifies the list of packages to be added to the image. You should 1619 only set this variable in the ``local.conf`` configuration file found 1620 in the :term:`Build Directory`. 1621 1622 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer 1623 supported. 1624 1625 :term:`COREBASE` 1626 Specifies the parent directory of the OpenEmbedded-Core Metadata 1627 layer (i.e. ``meta``). 1628 1629 It is an important distinction that :term:`COREBASE` points to the parent 1630 of this layer and not the layer itself. Consider an example where you 1631 have cloned the Poky Git repository and retained the ``poky`` name 1632 for your local copy of the repository. In this case, :term:`COREBASE` 1633 points to the ``poky`` folder because it is the parent directory of 1634 the ``poky/meta`` layer. 1635 1636 :term:`COREBASE_FILES` 1637 Lists files from the :term:`COREBASE` directory that 1638 should be copied other than the layers listed in the 1639 ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows 1640 to copy metadata from the OpenEmbedded build system 1641 into the extensible SDK. 1642 1643 Explicitly listing files in :term:`COREBASE` is needed because it 1644 typically contains build directories and other files that should not 1645 normally be copied into the extensible SDK. Consequently, the value 1646 of :term:`COREBASE_FILES` is used in order to only copy the files that 1647 are actually needed. 1648 1649 :term:`CPP` 1650 The minimal command and arguments used to run the C preprocessor. 1651 1652 :term:`CPPFLAGS` 1653 Specifies the flags to pass to the C pre-processor (i.e. to both the 1654 C and the C++ compilers). This variable is exported to an environment 1655 variable and thus made visible to the software being built during the 1656 compilation step. 1657 1658 Default initialization for :term:`CPPFLAGS` varies depending on what is 1659 being built: 1660 1661 - :term:`TARGET_CPPFLAGS` when building for 1662 the target 1663 1664 - :term:`BUILD_CPPFLAGS` when building for the 1665 build host (i.e. ``-native``) 1666 1667 - :term:`BUILDSDK_CPPFLAGS` when building 1668 for an SDK (i.e. ``nativesdk-``) 1669 1670 :term:`CROSS_COMPILE` 1671 The toolchain binary prefix for the target tools. The 1672 :term:`CROSS_COMPILE` variable is the same as the 1673 :term:`TARGET_PREFIX` variable. 1674 1675 .. note:: 1676 1677 The OpenEmbedded build system sets the :term:`CROSS_COMPILE` 1678 variable only in certain contexts (e.g. when building for kernel 1679 and kernel module recipes). 1680 1681 :term:`CVE_CHECK_CREATE_MANIFEST` 1682 Specifies whether to create a CVE manifest to place in the deploy 1683 directory. The default is "1". 1684 1685 :term:`CVE_CHECK_IGNORE` 1686 This variable is deprecated and should be replaced by :term:`CVE_STATUS`. 1687 1688 :term:`CVE_CHECK_MANIFEST_JSON` 1689 Specifies the path to the CVE manifest in JSON format. See 1690 :term:`CVE_CHECK_CREATE_MANIFEST`. 1691 1692 :term:`CVE_CHECK_MANIFEST_JSON_SUFFIX` 1693 Allows to modify the JSON manifest suffix. See 1694 :term:`CVE_CHECK_MANIFEST_JSON`. 1695 1696 :term:`CVE_CHECK_REPORT_PATCHED` 1697 Specifies whether or not the :ref:`ref-classes-cve-check` 1698 class should report patched or ignored CVEs. The default is "1", but you 1699 may wish to set it to "0" if you do not need patched or ignored CVEs in 1700 the logs. 1701 1702 :term:`CVE_CHECK_SHOW_WARNINGS` 1703 Specifies whether or not the :ref:`ref-classes-cve-check` 1704 class should generate warning messages on the console when unpatched 1705 CVEs are found. The default is "1", but you may wish to set it to "0" if 1706 you are already examining/processing the logs after the build has 1707 completed and thus do not need the warning messages. 1708 1709 :term:`CVE_CHECK_SKIP_RECIPE` 1710 The list of package names (:term:`PN`) for which 1711 CVEs (Common Vulnerabilities and Exposures) are ignored. 1712 1713 :term:`CVE_DB_INCR_UPDATE_AGE_THRES` 1714 Specifies the maximum age of the CVE database in seconds for an 1715 incremental update (instead of a full-download). Use "0" to force a 1716 full-download. 1717 1718 :term:`CVE_DB_UPDATE_INTERVAL` 1719 Specifies the CVE database update interval in seconds, as used by 1720 ``cve-update-db-native``. The default value is "86400" i.e. once a day 1721 (24*60*60). If the value is set to "0" then the update will be forced 1722 every time. Alternatively, a negative value e.g. "-1" will disable 1723 updates entirely. 1724 1725 :term:`CVE_PRODUCT` 1726 In a recipe, defines the name used to match the recipe name 1727 against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__. 1728 1729 The default is ${:term:`BPN`} (except for recipes that inherit the 1730 :ref:`ref-classes-pypi` class where it is set based upon 1731 :term:`PYPI_PACKAGE`). If it does not match the name in the NIST CVE 1732 database or matches with multiple entries in the database, the default 1733 value needs to be changed. 1734 1735 Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`:: 1736 1737 CVE_PRODUCT = "oracle_berkeley_db berkeley_db" 1738 1739 Sometimes the product name is not specific enough, for example 1740 "tar" has been matching CVEs for the GNU ``tar`` package and also 1741 the ``node-tar`` node.js extension. To avoid this problem, use the 1742 vendor name as a prefix. The syntax for this is:: 1743 1744 CVE_PRODUCT = "vendor:package" 1745 1746 :term:`CVE_STATUS` 1747 The CVE ID which is patched or should be ignored. Here is 1748 an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`:: 1749 1750 CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows" 1751 1752 It has the format "reason: description" and the description is optional. 1753 The Reason is mapped to the final CVE state by mapping via 1754 :term:`CVE_CHECK_STATUSMAP`. See :ref:`dev-manual/vulnerabilities:fixing vulnerabilities in recipes` 1755 for details. 1756 1757 :term:`CVE_STATUS_GROUPS` 1758 If there are many CVEs with the same status and reason, they can by simplified by using this 1759 variable instead of many similar lines with :term:`CVE_STATUS`:: 1760 1761 CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED" 1762 1763 CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002" 1764 CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows" 1765 CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004" 1766 CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally" 1767 1768 :term:`CVE_CHECK_STATUSMAP` 1769 Mapping variable for all possible reasons of :term:`CVE_STATUS`: 1770 ``Patched``, ``Unpatched`` and ``Ignored``. 1771 See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details:: 1772 1773 CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored" 1774 1775 :term:`CVE_VERSION` 1776 In a recipe, defines the version used to match the recipe version 1777 against the version in the `NIST CVE database <https://nvd.nist.gov/>`__ 1778 when usign :ref:`ref-classes-cve-check`. 1779 1780 The default is ${:term:`PV`} but if recipes use custom version numbers 1781 which do not map to upstream software component release versions and the versions 1782 used in the CVE database, then this variable can be used to set the 1783 version number for :ref:`ref-classes-cve-check`. Example:: 1784 1785 CVE_VERSION = "2.39" 1786 1787 :term:`CVSDIR` 1788 The directory in which files checked out under the CVS system are 1789 stored. 1790 1791 :term:`CXX` 1792 The minimal command and arguments used to run the C++ compiler. 1793 1794 :term:`CXXFLAGS` 1795 Specifies the flags to pass to the C++ compiler. This variable is 1796 exported to an environment variable and thus made visible to the 1797 software being built during the compilation step. 1798 1799 Default initialization for :term:`CXXFLAGS` varies depending on what is 1800 being built: 1801 1802 - :term:`TARGET_CXXFLAGS` when building for 1803 the target 1804 1805 - :term:`BUILD_CXXFLAGS` when building for the 1806 build host (i.e. ``-native``) 1807 1808 - :term:`BUILDSDK_CXXFLAGS` when building 1809 for an SDK (i.e. ``nativesdk-``) 1810 1811 :term:`D` 1812 The destination directory. The location in the :term:`Build Directory` 1813 where components are installed by the 1814 :ref:`ref-tasks-install` task. This location defaults 1815 to:: 1816 1817 ${WORKDIR}/image 1818 1819 .. note:: 1820 1821 Tasks that read from or write to this directory should run under 1822 :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`. 1823 1824 :term:`DATE` 1825 The date the build was started. Dates appear using the year, month, 1826 and day (YMD) format (e.g. "20150209" for February 9th, 2015). 1827 1828 :term:`DATETIME` 1829 The date and time on which the current build started. The format is 1830 suitable for timestamps. 1831 1832 :term:`DEBIAN_NOAUTONAME` 1833 When the :ref:`ref-classes-debian` class is inherited, 1834 which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a 1835 particular package should not be renamed according to Debian library 1836 package naming. You must use the package name as an override when you 1837 set this variable. Here is an example from the ``fontconfig`` recipe:: 1838 1839 DEBIAN_NOAUTONAME:fontconfig-utils = "1" 1840 1841 :term:`DEBIANNAME` 1842 When the :ref:`ref-classes-debian` class is inherited, 1843 which is the default behavior, :term:`DEBIANNAME` allows you to override 1844 the library name for an individual package. Overriding the library 1845 name in these cases is rare. You must use the package name as an 1846 override when you set this variable. Here is an example from the 1847 ``dbus`` recipe:: 1848 1849 DEBIANNAME:${PN} = "dbus-1" 1850 1851 :term:`DEBUG_BUILD` 1852 Specifies to build packages with debugging information. This 1853 influences the value of the :term:`SELECTED_OPTIMIZATION` variable. 1854 1855 :term:`DEBUG_OPTIMIZATION` 1856 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when 1857 compiling a system for debugging. This variable defaults to "-O 1858 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". 1859 1860 :term:`DEBUG_PREFIX_MAP` 1861 Allows to set C compiler options, such as ``-fdebug-prefix-map``, 1862 ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to 1863 replace build-time paths by install-time ones in the debugging sections 1864 of binaries. This makes compiler output files location independent, 1865 at the cost of having to pass an extra command to tell the debugger 1866 where source files are. 1867 1868 This is used by the Yocto Project to guarantee 1869 :doc:`/test-manual/reproducible-builds` even when the source code of 1870 a package uses the ``__FILE__`` or ``assert()`` macros. See the 1871 `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__ 1872 website for details. 1873 1874 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 1875 not intended to be user-configurable. 1876 1877 :term:`DEFAULT_PREFERENCE` 1878 Specifies a weak bias for recipe selection priority. 1879 1880 The most common usage of this is variable is to set it to "-1" within 1881 a recipe for a development version of a piece of software. Using the 1882 variable in this way causes the stable version of the recipe to build 1883 by default in the absence of :term:`PREFERRED_VERSION` being used to 1884 build the development version. 1885 1886 .. note:: 1887 1888 The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden 1889 by :term:`BBFILE_PRIORITY` if that variable is different between two 1890 layers that contain different versions of the same recipe. 1891 1892 :term:`DEFAULT_TIMEZONE` 1893 Specifies the time zone set in the image. 1894 1895 This variable causes the ``tzdata`` package to configure 1896 ``${sysconfdir}/localtime`` accordingly. Valid values are all files 1897 found in ``/usr/share/zoneinfo`` like ``CET`` or ``Asia/Baku``. 1898 1899 :term:`DEFAULTTUNE` 1900 The default CPU and Application Binary Interface (ABI) tunings (i.e. 1901 the "tune") used by the OpenEmbedded build system. The 1902 :term:`DEFAULTTUNE` helps define 1903 :term:`TUNE_FEATURES`. 1904 1905 The default tune is either implicitly or explicitly set by the 1906 machine (:term:`MACHINE`). However, you can override 1907 the setting using available tunes as defined with 1908 :term:`AVAILTUNES`. 1909 1910 :term:`DEPENDS` 1911 Lists a recipe's build-time dependencies. These are dependencies on 1912 other recipes whose contents (e.g. headers and shared libraries) are 1913 needed by the recipe at build time. 1914 1915 As an example, consider a recipe ``foo`` that contains the following 1916 assignment:: 1917 1918 DEPENDS = "bar" 1919 1920 The practical effect of the previous assignment is that all files 1921 installed by bar will be available in the appropriate staging sysroot, 1922 given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time 1923 the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is 1924 implemented by having :ref:`ref-tasks-configure` depend on the 1925 :ref:`ref-tasks-populate_sysroot` task of each recipe listed in 1926 :term:`DEPENDS`, through a 1927 ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` 1928 declaration in the :ref:`ref-classes-base` class. 1929 1930 .. note:: 1931 1932 It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST` 1933 explicitly. The standard classes and build-related variables are 1934 configured to automatically use the appropriate staging sysroots. 1935 1936 As another example, :term:`DEPENDS` can also be used to add utilities 1937 that run on the build machine during the build. For example, a recipe 1938 that makes use of a code generator built by the recipe ``codegen`` 1939 might have the following:: 1940 1941 DEPENDS = "codegen-native" 1942 1943 For more 1944 information, see the :ref:`ref-classes-native` class and 1945 the :term:`EXTRANATIVEPATH` variable. 1946 1947 .. note:: 1948 1949 - :term:`DEPENDS` is a list of recipe names. Or, to be more precise, 1950 it is a list of :term:`PROVIDES` names, which 1951 usually match recipe names. Putting a package name such as 1952 "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo" 1953 instead, as this will put files from all the packages that make 1954 up ``foo``, which includes those from ``foo-dev``, into the 1955 sysroot. 1956 1957 - One recipe having another recipe in :term:`DEPENDS` does not by 1958 itself add any runtime dependencies between the packages 1959 produced by the two recipes. However, as explained in the 1960 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 1961 section in the Yocto Project Overview and Concepts Manual, 1962 runtime dependencies will often be added automatically, meaning 1963 :term:`DEPENDS` alone is sufficient for most recipes. 1964 1965 - Counterintuitively, :term:`DEPENDS` is often necessary even for 1966 recipes that install precompiled components. For example, if 1967 ``libfoo`` is a precompiled library that links against 1968 ``libbar``, then linking against ``libfoo`` requires both 1969 ``libfoo`` and ``libbar`` to be available in the sysroot. 1970 Without a :term:`DEPENDS` from the recipe that installs ``libfoo`` 1971 to the recipe that installs ``libbar``, other recipes might 1972 fail to link against ``libfoo``. 1973 1974 For information on runtime dependencies, see the :term:`RDEPENDS` 1975 variable. You can also see the 1976 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and 1977 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" 1978 sections in the BitBake User Manual for additional information on tasks 1979 and dependencies. 1980 1981 :term:`DEPLOY_DIR` 1982 Points to the general area that the OpenEmbedded build system uses to 1983 place images, packages, SDKs, and other output files that are ready 1984 to be used outside of the build system. By default, this directory 1985 resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``. 1986 1987 For more information on the structure of the Build Directory, see 1988 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 1989 For more detail on the contents of the ``deploy`` directory, see the 1990 ":ref:`overview-manual/concepts:images`", 1991 ":ref:`overview-manual/concepts:package feeds`", and 1992 ":ref:`overview-manual/concepts:application development sdk`" sections all in the 1993 Yocto Project Overview and Concepts Manual. 1994 1995 :term:`DEPLOY_DIR_DEB` 1996 Points to the area that the OpenEmbedded build system uses to place 1997 Debian packages that are ready to be used outside of the build 1998 system. This variable applies only when :term:`PACKAGE_CLASSES` contains 1999 ":ref:`ref-classes-package_deb`". 2000 2001 The BitBake configuration file initially defines the 2002 :term:`DEPLOY_DIR_DEB` variable as a sub-folder of 2003 :term:`DEPLOY_DIR`:: 2004 2005 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" 2006 2007 The :ref:`ref-classes-package_deb` class uses the 2008 :term:`DEPLOY_DIR_DEB` variable to make sure the 2009 :ref:`ref-tasks-package_write_deb` task 2010 writes Debian packages into the appropriate folder. For more 2011 information on how packaging works, see the 2012 ":ref:`overview-manual/concepts:package feeds`" section 2013 in the Yocto Project Overview and Concepts Manual. 2014 2015 :term:`DEPLOY_DIR_IMAGE` 2016 Points to the area that the OpenEmbedded build system uses to place 2017 images and other associated output files that are ready to be 2018 deployed onto the target machine. The directory is machine-specific 2019 as it contains the ``${MACHINE}`` name. By default, this directory 2020 resides within the :term:`Build Directory` as 2021 ``${DEPLOY_DIR}/images/${MACHINE}/``. 2022 2023 It must not be used directly in recipes when deploying files. Instead, 2024 it's only useful when a recipe needs to "read" a file already deployed 2025 by a dependency. So, it should be filled with the contents of 2026 :term:`DEPLOYDIR` by the :ref:`ref-classes-deploy` class or with the 2027 contents of :term:`IMGDEPLOYDIR` by the :ref:`ref-classes-image` class. 2028 2029 For more information on the structure of the :term:`Build Directory`, see 2030 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. 2031 For more detail on the contents of the ``deploy`` directory, see the 2032 ":ref:`overview-manual/concepts:images`" and 2033 ":ref:`overview-manual/concepts:application development sdk`" sections both in 2034 the Yocto Project Overview and Concepts Manual. 2035 2036 :term:`DEPLOY_DIR_IPK` 2037 Points to the area that the OpenEmbedded build system uses to place 2038 IPK packages that are ready to be used outside of the build system. 2039 This variable applies only when :term:`PACKAGE_CLASSES` contains 2040 ":ref:`ref-classes-package_ipk`". 2041 2042 The BitBake configuration file initially defines this variable as a 2043 sub-folder of :term:`DEPLOY_DIR`:: 2044 2045 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" 2046 2047 The :ref:`ref-classes-package_ipk` class uses the :term:`DEPLOY_DIR_IPK` 2048 variable to make sure the :ref:`ref-tasks-package_write_ipk` task 2049 writes IPK packages into the appropriate folder. For more information 2050 on how packaging works, see the 2051 ":ref:`overview-manual/concepts:package feeds`" section 2052 in the Yocto Project Overview and Concepts Manual. 2053 2054 :term:`DEPLOY_DIR_RPM` 2055 Points to the area that the OpenEmbedded build system uses to place 2056 RPM packages that are ready to be used outside of the build system. 2057 This variable applies only when :term:`PACKAGE_CLASSES` contains 2058 ":ref:`ref-classes-package_rpm`". 2059 2060 The BitBake configuration file initially defines this variable as a 2061 sub-folder of :term:`DEPLOY_DIR`:: 2062 2063 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" 2064 2065 The :ref:`ref-classes-package_rpm` class uses the 2066 :term:`DEPLOY_DIR_RPM` variable to make sure the 2067 :ref:`ref-tasks-package_write_rpm` task 2068 writes RPM packages into the appropriate folder. For more information 2069 on how packaging works, see the 2070 ":ref:`overview-manual/concepts:package feeds`" section 2071 in the Yocto Project Overview and Concepts Manual. 2072 2073 :term:`DEPLOYDIR` 2074 When inheriting the :ref:`ref-classes-deploy` class, the 2075 :term:`DEPLOYDIR` points to a temporary work area for deployed files that 2076 is set in the :ref:`ref-classes-deploy` class as follows:: 2077 2078 DEPLOYDIR = "${WORKDIR}/deploy-${PN}" 2079 2080 Recipes inheriting the :ref:`ref-classes-deploy` class should copy files to be 2081 deployed into :term:`DEPLOYDIR`, and the class will take care of copying 2082 them into :term:`DEPLOY_DIR_IMAGE` 2083 afterwards. 2084 2085 :term:`DESCRIPTION` 2086 The package description used by package managers. If not set, 2087 :term:`DESCRIPTION` takes the value of the :term:`SUMMARY` 2088 variable. 2089 2090 :term:`DEV_PKG_DEPENDENCY` 2091 Provides an easy way for recipes to disable or adjust the runtime recommendation 2092 (:term:`RRECOMMENDS`) of the ``${PN}-dev`` package on the main 2093 (``${PN}``) package. 2094 2095 :term:`DISABLE_STATIC` 2096 Used in order to disable static linking by default (in order to save 2097 space, since static libraries are often unused in embedded systems.) 2098 The default value is " --disable-static", however it can be set to "" 2099 in order to enable static linking if desired. Certain recipes do this 2100 individually, and also there is a 2101 ``meta/conf/distro/include/no-static-libs.inc`` include file that 2102 disables static linking for a number of recipes. Some software 2103 packages or build tools (such as CMake) have explicit support for 2104 enabling / disabling static linking, and in those cases 2105 :term:`DISABLE_STATIC` is not used. 2106 2107 :term:`DISTRO` 2108 The short name of the distribution. For information on the long name 2109 of the distribution, see the :term:`DISTRO_NAME` 2110 variable. 2111 2112 The :term:`DISTRO` variable corresponds to a distribution configuration 2113 file whose root name is the same as the variable's argument and whose 2114 filename extension is ``.conf``. For example, the distribution 2115 configuration file for the Poky distribution is named ``poky.conf`` 2116 and resides in the ``meta-poky/conf/distro`` directory of the 2117 :term:`Source Directory`. 2118 2119 Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as 2120 follows:: 2121 2122 DISTRO = "poky" 2123 2124 Distribution configuration files are located in a ``conf/distro`` 2125 directory within the :term:`Metadata` that contains the 2126 distribution configuration. The value for :term:`DISTRO` must not contain 2127 spaces, and is typically all lower-case. 2128 2129 .. note:: 2130 2131 If the :term:`DISTRO` variable is blank, a set of default configurations 2132 are used, which are specified within 2133 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2134 2135 :term:`DISTRO_CODENAME` 2136 Specifies a codename for the distribution being built. 2137 2138 :term:`DISTRO_EXTRA_RDEPENDS` 2139 Specifies a list of distro-specific packages to add to all images. 2140 This variable takes effect through ``packagegroup-base`` so the 2141 variable only really applies to the more full-featured images that 2142 include ``packagegroup-base``. You can use this variable to keep 2143 distro policy out of generic images. As with all other distro 2144 variables, you set this variable in the distro ``.conf`` file. 2145 2146 :term:`DISTRO_EXTRA_RRECOMMENDS` 2147 Specifies a list of distro-specific packages to add to all images if 2148 the packages exist. The packages might not exist or be empty (e.g. 2149 kernel modules). The list of packages are automatically installed but 2150 you can remove them. 2151 2152 :term:`DISTRO_FEATURES` 2153 The software support you want in your distribution for various 2154 features. You define your distribution features in the distribution 2155 configuration file. 2156 2157 In most cases, the presence or absence of a feature in 2158 :term:`DISTRO_FEATURES` is translated to the appropriate option supplied 2159 to the configure script during the 2160 :ref:`ref-tasks-configure` task for recipes that 2161 optionally support the feature. For example, specifying "x11" in 2162 :term:`DISTRO_FEATURES`, causes every piece of software built for the 2163 target that can optionally support X11 to have its X11 support 2164 enabled. 2165 2166 .. note:: 2167 2168 Just enabling :term:`DISTRO_FEATURES` alone doesn't 2169 enable feature support for packages. Mechanisms such as making 2170 :term:`PACKAGECONFIG` track :term:`DISTRO_FEATURES` are used 2171 to enable/disable package features. 2172 2173 Two more examples are Bluetooth and NFS support. For a more complete 2174 list of features that ships with the Yocto Project and that you can 2175 provide with this variable, see the ":ref:`ref-features-distro`" section. 2176 2177 :term:`DISTRO_FEATURES_BACKFILL` 2178 A space-separated list of features to be added to :term:`DISTRO_FEATURES` 2179 if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. 2180 2181 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 2182 not intended to be user-configurable. It is best to just reference 2183 the variable to see which distro features are being 2184 :ref:`backfilled <ref-features-backfill>` for all distro configurations. 2185 2186 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 2187 A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL` 2188 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added 2189 to :term:`DISTRO_FEATURES`) during the build. 2190 2191 This corresponds to an opt-out mechanism. When new default distro 2192 features are introduced, distribution maintainers can review (`consider`) 2193 them and decide to exclude them from the 2194 :ref:`backfilled <ref-features-backfill>` features. Therefore, the 2195 combination of :term:`DISTRO_FEATURES_BACKFILL` and 2196 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to 2197 add new default features without breaking existing distributions. 2198 2199 2200 :term:`DISTRO_FEATURES_DEFAULT` 2201 A convenience variable that gives you the default list of distro 2202 features with the exception of any features specific to the C library 2203 (``libc``). 2204 2205 When creating a custom distribution, you might find it useful to be 2206 able to reuse the default 2207 :term:`DISTRO_FEATURES` options without the 2208 need to write out the full set. Here is an example that uses 2209 :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file:: 2210 2211 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" 2212 2213 :term:`DISTRO_FEATURES_FILTER_NATIVE` 2214 Specifies a list of features that if present in the target 2215 :term:`DISTRO_FEATURES` value should be 2216 included in :term:`DISTRO_FEATURES` when building native recipes. This 2217 variable is used in addition to the features filtered using the 2218 :term:`DISTRO_FEATURES_NATIVE` 2219 variable. 2220 2221 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` 2222 Specifies a list of features that if present in the target 2223 :term:`DISTRO_FEATURES` value should be included in 2224 :term:`DISTRO_FEATURES` when building :ref:`ref-classes-nativesdk` 2225 recipes. This variable is used in addition to the features filtered using 2226 the :term:`DISTRO_FEATURES_NATIVESDK` variable. 2227 2228 :term:`DISTRO_FEATURES_NATIVE` 2229 Specifies a list of features that should be included in 2230 :term:`DISTRO_FEATURES` when building native 2231 recipes. This variable is used in addition to the features filtered 2232 using the 2233 :term:`DISTRO_FEATURES_FILTER_NATIVE` 2234 variable. 2235 2236 :term:`DISTRO_FEATURES_NATIVESDK` 2237 Specifies a list of features that should be included in 2238 :term:`DISTRO_FEATURES` when building 2239 :ref:`ref-classes-nativesdk` recipes. This variable is used 2240 in addition to the features filtered using the 2241 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` variable. 2242 2243 :term:`DISTRO_NAME` 2244 The long name of the distribution. For information on the short name 2245 of the distribution, see the :term:`DISTRO` variable. 2246 2247 The :term:`DISTRO_NAME` variable corresponds to a distribution 2248 configuration file whose root name is the same as the variable's 2249 argument and whose filename extension is ``.conf``. For example, the 2250 distribution configuration file for the Poky distribution is named 2251 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory 2252 of the :term:`Source Directory`. 2253 2254 Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set 2255 as follows:: 2256 2257 DISTRO_NAME = "Poky (Yocto Project Reference Distro)" 2258 2259 Distribution configuration files are located in a ``conf/distro`` 2260 directory within the :term:`Metadata` that contains the 2261 distribution configuration. 2262 2263 .. note:: 2264 2265 If the :term:`DISTRO_NAME` variable is blank, a set of default 2266 configurations are used, which are specified within 2267 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2268 2269 :term:`DISTRO_VERSION` 2270 The version of the distribution. 2271 2272 :term:`DISTROOVERRIDES` 2273 A colon-separated list of overrides specific to the current 2274 distribution. By default, this list includes the value of 2275 :term:`DISTRO`. 2276 2277 You can extend :term:`DISTROOVERRIDES` to add extra overrides that should 2278 apply to the distribution. 2279 2280 The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it 2281 is included in the default value of 2282 :term:`OVERRIDES`. 2283 2284 Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf 2285 </poky/tree/meta-poky/conf/distro/poky-tiny.conf>`:: 2286 2287 DISTROOVERRIDES = "poky:poky-tiny" 2288 2289 :term:`DL_DIR` 2290 The central download directory used by the build process to store 2291 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring 2292 for everything except Git repositories. If you want tarballs of Git 2293 repositories, use the 2294 :term:`BB_GENERATE_MIRROR_TARBALLS` 2295 variable. 2296 2297 You can set this directory by defining the :term:`DL_DIR` variable in the 2298 ``conf/local.conf`` file. This directory is self-maintaining and you 2299 should not have to touch it. By default, the directory is 2300 ``downloads`` in the :term:`Build Directory`:: 2301 2302 #DL_DIR ?= "${TOPDIR}/downloads" 2303 2304 To specify a different download directory, 2305 simply remove the comment from the line and provide your directory. 2306 2307 During a first build, the system downloads many different source code 2308 tarballs from various upstream projects. Downloading can take a 2309 while, particularly if your network connection is slow. Tarballs are 2310 all stored in the directory defined by :term:`DL_DIR` and the build 2311 system looks there first to find source tarballs. 2312 2313 .. note:: 2314 2315 When wiping and rebuilding, you can preserve this directory to 2316 speed up this part of subsequent builds. 2317 2318 You can safely share this directory between multiple builds on the 2319 same development machine. For additional information on how the build 2320 process gets source files when working behind a firewall or proxy 2321 server, see this specific question in the ":doc:`faq`" 2322 chapter. You can also refer to the 2323 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 2324 Wiki page. 2325 2326 :term:`DOC_COMPRESS` 2327 When inheriting the :ref:`ref-classes-compress_doc` 2328 class, this variable sets the compression policy used when the 2329 OpenEmbedded build system compresses manual and info pages. By 2330 default, the compression method used is gz (gzip). Other policies 2331 available are xz and bz2. 2332 2333 For information on policies and on how to use this variable, see the 2334 comments in the ``meta/classes-recipe/compress_doc.bbclass`` file. 2335 2336 :term:`DT_FILES` 2337 Space-separated list of device tree source files to compile using 2338 a recipe that inherits the :ref:`ref-classes-devicetree` class. These 2339 are relative to the :term:`DT_FILES_PATH`. 2340 2341 For convenience, both ``.dts`` and ``.dtb`` extensions can be used. 2342 2343 Use an empty string (default) to build all device tree sources within 2344 the :term:`DT_FILES_PATH` directory. 2345 2346 :term:`DT_FILES_PATH` 2347 When compiling out-of-tree device tree sources using a recipe that 2348 inherits the :ref:`ref-classes-devicetree` class, this variable specifies 2349 the path to the directory containing dts files to build. 2350 2351 Defaults to the :term:`S` directory. 2352 2353 :term:`DT_PADDING_SIZE` 2354 When inheriting the :ref:`ref-classes-devicetree` class, this variable 2355 specifies the size of padding appended to the device tree blob, used as 2356 extra space typically for additional properties during boot. 2357 2358 :term:`EFI_ARCH` 2359 The CPU architecture name within EFI standard. Set in 2360 :oe_git:`meta/conf/image-uefi.conf 2361 <openembedded-core/tree/meta/conf/image-uefi.conf>`. 2362 2363 :term:`EFI_PROVIDER` 2364 When building bootable images (i.e. where ``hddimg``, ``iso``, or 2365 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the 2366 :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The 2367 default is "grub-efi", but "systemd-boot" can be used instead. 2368 2369 See the :ref:`ref-classes-systemd-boot` and :ref:`ref-classes-image-live` 2370 classes for more information. 2371 2372 :term:`EFI_UKI_DIR` 2373 The primary place for the UKI image inside the EFI System Partition. 2374 2375 :term:`EFI_UKI_PATH` 2376 The path for the UKI image inside the root filesystem. 2377 2378 :term:`ENABLE_BINARY_LOCALE_GENERATION` 2379 Variable that controls which locales for ``glibc`` are generated 2380 during the build (useful if the target device has 64Mbytes of RAM or 2381 less). 2382 2383 :term:`ERR_REPORT_DIR` 2384 When used with the :ref:`ref-classes-report-error` class, specifies the 2385 path used for storing the debug files created by the :ref:`error reporting 2386 tool <dev-manual/error-reporting-tool:using the error reporting tool>`, 2387 which allows you to submit build errors you encounter to a central 2388 database. By default, the value of this variable is 2389 ``${``\ :term:`LOG_DIR`\ ``}/error-report``. 2390 2391 You can set :term:`ERR_REPORT_DIR` to the path you want the error 2392 reporting tool to store the debug files as follows in your 2393 ``local.conf`` file:: 2394 2395 ERR_REPORT_DIR = "path" 2396 2397 :term:`ERROR_QA` 2398 Specifies the quality assurance checks whose failures are reported as 2399 errors by the OpenEmbedded build system. You set this variable in 2400 your distribution configuration file. For a list of the checks you 2401 can control with this variable, see the 2402 ":ref:`ref-classes-insane`" section. 2403 2404 :term:`ESDK_CLASS_INHERIT_DISABLE` 2405 A list of classes to remove from the :term:`INHERIT` 2406 value globally within the extensible SDK configuration. The 2407 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the 2408 default value:: 2409 2410 ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc" 2411 2412 Some classes are not generally applicable within the extensible SDK 2413 context. You can use this variable to disable those classes. 2414 2415 For additional information on how to customize the extensible SDK's 2416 configuration, see the 2417 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2418 section in the Yocto Project Application Development and the 2419 Extensible Software Development Kit (eSDK) manual. 2420 2421 :term:`ESDK_LOCALCONF_ALLOW` 2422 A list of variables allowed through from the OpenEmbedded build 2423 system configuration into the extensible SDK configuration. By 2424 default, the list of variables is empty and is set in the 2425 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. 2426 2427 This list overrides the variables specified using the 2428 :term:`ESDK_LOCALCONF_REMOVE` variable as well as 2429 other variables automatically added due to the "/" character 2430 being found at the start of the 2431 value, which is usually indicative of being a path and thus might not 2432 be valid on the system where the SDK is installed. 2433 2434 For additional information on how to customize the extensible SDK's 2435 configuration, see the 2436 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2437 section in the Yocto Project Application Development and the 2438 Extensible Software Development Kit (eSDK) manual. 2439 2440 :term:`ESDK_LOCALCONF_REMOVE` 2441 A list of variables not allowed through from the OpenEmbedded build 2442 system configuration into the extensible SDK configuration. Usually, 2443 these are variables that are specific to the machine on which the 2444 build system is running and thus would be potentially problematic 2445 within the extensible SDK. 2446 2447 By default, :term:`ESDK_LOCALCONF_REMOVE` is set in the 2448 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and 2449 excludes the following variables: 2450 2451 - :term:`CONF_VERSION` 2452 - :term:`BB_NUMBER_THREADS` 2453 - :term:`BB_NUMBER_PARSE_THREADS` 2454 - :term:`PARALLEL_MAKE` 2455 - :term:`PRSERV_HOST` 2456 - :term:`SSTATE_MIRRORS` :term:`DL_DIR` 2457 - :term:`SSTATE_DIR` :term:`TMPDIR` 2458 - :term:`BB_SERVER_TIMEOUT` 2459 2460 For additional information on how to customize the extensible SDK's 2461 configuration, see the 2462 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" 2463 section in the Yocto Project Application Development and the 2464 Extensible Software Development Kit (eSDK) manual. 2465 2466 :term:`EXCLUDE_FROM_SHLIBS` 2467 Triggers the OpenEmbedded build system's shared libraries resolver to 2468 exclude an entire package when scanning for shared libraries. 2469 2470 .. note:: 2471 2472 The shared libraries resolver's functionality results in part from 2473 the internal function ``package_do_shlibs``, which is part of the 2474 :ref:`ref-tasks-package` task. You should be aware that the shared 2475 libraries resolver might implicitly define some dependencies between 2476 packages. 2477 2478 The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the 2479 :term:`PRIVATE_LIBS` variable, which excludes a 2480 package's particular libraries only and not the whole package. 2481 2482 Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a 2483 particular package:: 2484 2485 EXCLUDE_FROM_SHLIBS = "1" 2486 2487 :term:`EXCLUDE_FROM_WORLD` 2488 Directs BitBake to exclude a recipe from world builds (i.e. 2489 ``bitbake world``). During world builds, BitBake locates, parses and 2490 builds all recipes found in every layer exposed in the 2491 ``bblayers.conf`` configuration file. 2492 2493 To exclude a recipe from a world build using this variable, set the 2494 variable to "1" in the recipe. 2495 2496 .. note:: 2497 2498 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a 2499 world build in order to satisfy dependencies of other recipes. Adding 2500 a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not 2501 explicitly added to the list of build targets in a world build. 2502 2503 :term:`EXTENDPE` 2504 Used with file and pathnames to create a prefix for a recipe's 2505 version based on the recipe's :term:`PE` value. If :term:`PE` 2506 is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that 2507 value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1"). 2508 If a recipe's :term:`PE` is not set (the default) or is equal to zero, 2509 :term:`EXTENDPE` becomes "". 2510 2511 See the :term:`STAMP` variable for an example. 2512 2513 :term:`EXTENDPKGV` 2514 The full package version specification as it appears on the final 2515 packages produced by a recipe. The variable's value is normally used 2516 to fix a runtime dependency to the exact same version of another 2517 package in the same recipe:: 2518 2519 RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" 2520 2521 The dependency relationships are intended to force the package 2522 manager to upgrade these types of packages in lock-step. 2523 2524 :term:`EXTERNAL_KERNEL_TOOLS` 2525 When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these 2526 tools are not in the source tree. 2527 2528 When kernel tools are available in the tree, they are preferred over 2529 any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS` 2530 variable tells the OpenEmbedded build system to prefer the installed 2531 external tools. See the :ref:`ref-classes-kernel-yocto` class in 2532 ``meta/classes-recipe`` to see how the variable is used. 2533 2534 :term:`EXTERNAL_KERNEL_DEVICETREE` 2535 When inheriting :ref:`ref-classes-kernel-fitimage` and a 2536 :term:`PREFERRED_PROVIDER` for ``virtual/dtb`` set to ``devicetree``, the 2537 variable :term:`EXTERNAL_KERNEL_DEVICETREE` can be used to specify a 2538 directory containing one or more compiled device tree or device tree 2539 overlays to use. 2540 2541 :term:`KERNEL_LOCALVERSION` 2542 This variable allows to append a string to the version 2543 of the kernel image. This corresponds to the ``CONFIG_LOCALVERSION`` 2544 kernel configuration parameter. 2545 2546 Using this variable is only useful when you are using a kernel recipe 2547 inheriting the :ref:`ref-classes-kernel` class, and which doesn't 2548 already set a local version. Therefore, setting this variable has no 2549 impact on ``linux-yocto`` kernels. 2550 2551 :term:`EXTERNAL_TOOLCHAIN` 2552 When you intend to use an 2553 :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`, 2554 this variable allows to specify the directory where this toolchain was 2555 installed. 2556 2557 :term:`EXTERNALSRC` 2558 When inheriting the :ref:`ref-classes-externalsrc` 2559 class, this variable points to the source tree, which is outside of 2560 the OpenEmbedded build system. When set, this variable sets the 2561 :term:`S` variable, which is what the OpenEmbedded build 2562 system uses to locate unpacked recipe source code. 2563 2564 See the ":ref:`ref-classes-externalsrc`" section for details. You 2565 can also find information on how to use this variable in the 2566 ":ref:`dev-manual/building:building software from an external source`" 2567 section in the Yocto Project Development Tasks Manual. 2568 2569 :term:`EXTERNALSRC_BUILD` 2570 When inheriting the :ref:`ref-classes-externalsrc` 2571 class, this variable points to the directory in which the recipe's 2572 source code is built, which is outside of the OpenEmbedded build 2573 system. When set, this variable sets the :term:`B` variable, 2574 which is what the OpenEmbedded build system uses to locate the 2575 :term:`Build Directory`. 2576 2577 See the ":ref:`ref-classes-externalsrc`" section for details. You 2578 can also find information on how to use this variable in the 2579 ":ref:`dev-manual/building:building software from an external source`" 2580 section in the Yocto Project Development Tasks Manual. 2581 2582 :term:`EXTRA_AUTORECONF` 2583 For recipes inheriting the :ref:`ref-classes-autotools` 2584 class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to 2585 pass to the ``autoreconf`` command that is executed during the 2586 :ref:`ref-tasks-configure` task. 2587 2588 The default value is "--exclude=autopoint". 2589 2590 :term:`EXTRA_IMAGE_FEATURES` 2591 A list of additional features to include in an image. When listing 2592 more than one feature, separate them with a space. 2593 2594 Typically, you configure this variable in your ``local.conf`` file, 2595 which is found in the :term:`Build Directory`. Although you can use this 2596 variable from within a recipe, best practices dictate that you do not. 2597 2598 .. note:: 2599 2600 To enable primary features from within the image recipe, use the 2601 :term:`IMAGE_FEATURES` variable. 2602 2603 Here are some examples of features you can add: 2604 2605 - "dbg-pkgs" --- adds -dbg packages for all installed packages including 2606 symbol information for debugging and profiling. 2607 2608 - "debug-tweaks" --- makes an image suitable for debugging. For example, allows root logins without passwords and 2609 enables post-installation logging. See the 'allow-empty-password' and 2610 'post-install-logging' features in the ":ref:`ref-features-image`" 2611 section for more information. 2612 - "dev-pkgs" --- adds -dev packages for all installed packages. This is 2613 useful if you want to develop against the libraries in the image. 2614 - "read-only-rootfs" --- creates an image whose root filesystem is 2615 read-only. See the 2616 ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`" 2617 section in the Yocto Project Development Tasks Manual for more 2618 information 2619 - "tools-debug" --- adds debugging tools such as gdb and strace. 2620 - "tools-sdk" --- adds development tools such as gcc, make, 2621 pkgconfig and so forth. 2622 - "tools-testapps" --- adds useful testing tools 2623 such as ts_print, aplay, arecord and so forth. 2624 2625 For a complete list of image features that ships with the Yocto 2626 Project, see the ":ref:`ref-features-image`" section. 2627 2628 For an example that shows how to customize your image by using this 2629 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 2630 section in the Yocto Project Development Tasks Manual. 2631 2632 :term:`EXTRA_IMAGECMD` 2633 Specifies additional options for the image creation command that has 2634 been specified in :term:`IMAGE_CMD`. When setting 2635 this variable, use an override for the associated image type. Here is 2636 an example:: 2637 2638 EXTRA_IMAGECMD:ext3 ?= "-i 4096" 2639 2640 :term:`EXTRA_IMAGEDEPENDS` 2641 A list of recipes to build that do not provide packages for 2642 installing into the root filesystem. 2643 2644 Sometimes a recipe is required to build the final image but is not 2645 needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS` 2646 variable to list these recipes and thus specify the dependencies. A 2647 typical example is a required bootloader in a machine configuration. 2648 2649 .. note:: 2650 2651 To add packages to the root filesystem, see the various 2652 :term:`RDEPENDS` and :term:`RRECOMMENDS` variables. 2653 2654 :term:`EXTRA_OECMAKE` 2655 Additional `CMake <https://cmake.org/overview/>`__ options. See the 2656 :ref:`ref-classes-cmake` class for additional information. 2657 2658 :term:`EXTRA_OECONF` 2659 Additional ``configure`` script options. See 2660 :term:`PACKAGECONFIG_CONFARGS` for 2661 additional information on passing configure script options. 2662 2663 :term:`EXTRA_OEMAKE` 2664 Additional GNU ``make`` options. 2665 2666 Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the 2667 variable to specify any required GNU options. 2668 2669 :term:`PARALLEL_MAKE` and 2670 :term:`PARALLEL_MAKEINST` also make use of 2671 :term:`EXTRA_OEMAKE` to pass the required flags. 2672 2673 :term:`EXTRA_OESCONS` 2674 When inheriting the :ref:`ref-classes-scons` class, this 2675 variable specifies additional configuration options you want to pass 2676 to the ``scons`` command line. 2677 2678 :term:`EXTRA_OEMESON` 2679 Additional `Meson <https://mesonbuild.com/>`__ options. See the 2680 :ref:`ref-classes-meson` class for additional information. 2681 2682 In addition to standard Meson options, such options correspond to 2683 `Meson build options <https://mesonbuild.com/Build-options.html>`__ 2684 defined in the ``meson_options.txt`` file in the sources to build. 2685 Here is an example:: 2686 2687 EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled" 2688 2689 Note that any custom value for the Meson ``--buildtype`` option 2690 should be set through the :term:`MESON_BUILDTYPE` variable. 2691 2692 :term:`EXTRA_USERS_PARAMS` 2693 When inheriting the :ref:`ref-classes-extrausers` 2694 class, this variable provides image level user and group operations. 2695 This is a more global method of providing user and group 2696 configuration as compared to using the 2697 :ref:`ref-classes-useradd` class, which ties user and 2698 group configurations to a specific recipe. 2699 2700 The set list of commands you can configure using the 2701 :term:`EXTRA_USERS_PARAMS` is shown in the 2702 :ref:`ref-classes-extrausers` class. These commands map to the normal 2703 Unix commands of the same names:: 2704 2705 # EXTRA_USERS_PARAMS = "\ 2706 # useradd -p '' tester; \ 2707 # groupadd developers; \ 2708 # userdel nobody; \ 2709 # groupdel -g video; \ 2710 # groupmod -g 1020 developers; \ 2711 # usermod -s /bin/sh tester; \ 2712 # " 2713 2714 Hardcoded passwords are supported via the ``-p`` parameters for 2715 ``useradd`` or ``usermod``, but only hashed. 2716 2717 Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns 2718 passwords. First on host, create the (escaped) password hash:: 2719 2720 printf "%q" $(mkpasswd -m sha256crypt tester01) 2721 2722 The resulting hash is set to a variable and used in ``useradd`` command parameters:: 2723 2724 inherit extrausers 2725 PASSWD = "\$X\$ABC123\$A-Long-Hash" 2726 EXTRA_USERS_PARAMS = "\ 2727 useradd -p '${PASSWD}' tester-jim; \ 2728 useradd -p '${PASSWD}' tester-sue; \ 2729 " 2730 2731 Finally, here is an example that sets the root password:: 2732 2733 inherit extrausers 2734 EXTRA_USERS_PARAMS = "\ 2735 usermod -p '${PASSWD}' root; \ 2736 " 2737 2738 .. note:: 2739 2740 From a security perspective, hardcoding a default password is not 2741 generally a good idea or even legal in some jurisdictions. It is 2742 recommended that you do not do this if you are building a production 2743 image. 2744 2745 Additionally there is a special ``passwd-expire`` command that will 2746 cause the password for a user to be expired and thus force changing it 2747 on first login, for example:: 2748 2749 EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;" 2750 2751 .. note:: 2752 2753 At present, ``passwd-expire`` may only work for remote logins when 2754 using OpenSSH and not dropbear as an SSH server. 2755 2756 :term:`EXTRANATIVEPATH` 2757 A list of subdirectories of 2758 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` 2759 added to the beginning of the environment variable ``PATH``. As an 2760 example, the following prepends 2761 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to 2762 ``PATH``:: 2763 2764 EXTRANATIVEPATH = "foo bar" 2765 2766 :term:`FAKEROOT` 2767 See :term:`bitbake:FAKEROOT` in the BitBake manual. 2768 2769 :term:`FAKEROOTBASEENV` 2770 See :term:`bitbake:FAKEROOTBASEENV` in the BitBake manual. 2771 2772 :term:`FAKEROOTCMD` 2773 See :term:`bitbake:FAKEROOTCMD` in the BitBake manual. 2774 2775 :term:`FAKEROOTDIRS` 2776 See :term:`bitbake:FAKEROOTDIRS` in the BitBake manual. 2777 2778 :term:`FAKEROOTENV` 2779 See :term:`bitbake:FAKEROOTENV` in the BitBake manual. 2780 2781 :term:`FAKEROOTNOENV` 2782 See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual. 2783 2784 :term:`FEATURE_PACKAGES` 2785 Defines one or more packages to include in an image when a specific 2786 item is included in :term:`IMAGE_FEATURES`. 2787 When setting the value, :term:`FEATURE_PACKAGES` should have the name of 2788 the feature item as an override. Here is an example:: 2789 2790 FEATURE_PACKAGES_widget = "package1 package2" 2791 2792 In this example, if "widget" were added to :term:`IMAGE_FEATURES`, 2793 package1 and package2 would be included in the image. 2794 2795 .. note:: 2796 2797 Packages installed by features defined through :term:`FEATURE_PACKAGES` 2798 are often package groups. While similarly named, you should not 2799 confuse the :term:`FEATURE_PACKAGES` variable with package groups, which 2800 are discussed elsewhere in the documentation. 2801 2802 :term:`FEED_DEPLOYDIR_BASE_URI` 2803 Points to the base URL of the server and location within the 2804 document-root that provides the metadata and packages required by 2805 OPKG to support runtime package management of IPK packages. You set 2806 this variable in your ``local.conf`` file. 2807 2808 Consider the following example:: 2809 2810 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" 2811 2812 This example assumes you are serving 2813 your packages over HTTP and your databases are located in a directory 2814 named ``BOARD-dir``, which is underneath your HTTP server's 2815 document-root. In this case, the OpenEmbedded build system generates 2816 a set of configuration files for you in your target that work with 2817 the feed. 2818 2819 :term:`FETCHCMD` 2820 See :term:`bitbake:FETCHCMD` in the BitBake manual. 2821 2822 :term:`FILE` 2823 See :term:`bitbake:FILE` in the BitBake manual. 2824 2825 :term:`FILES` 2826 The list of files and directories that are placed in a package. The 2827 :term:`PACKAGES` variable lists the packages 2828 generated by a recipe. 2829 2830 To use the :term:`FILES` variable, provide a package name override that 2831 identifies the resulting package. Then, provide a space-separated 2832 list of files or paths that identify the files you want included as 2833 part of the resulting package. Here is an example:: 2834 2835 FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" 2836 2837 .. note:: 2838 2839 - When specifying files or paths, you can pattern match using 2840 Python's 2841 `glob <https://docs.python.org/3/library/glob.html>`__ 2842 syntax. For details on the syntax, see the documentation by 2843 following the previous link. 2844 2845 - When specifying paths as part of the :term:`FILES` variable, it is 2846 good practice to use appropriate path variables. For example, 2847 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` 2848 rather than ``/usr/bin``. You can find a list of these 2849 variables at the top of the ``meta/conf/bitbake.conf`` file in 2850 the :term:`Source Directory`. You will also 2851 find the default values of the various ``FILES:*`` variables in 2852 this file. 2853 2854 If some of the files you provide with the :term:`FILES` variable are 2855 editable and you know they should not be overwritten during the 2856 package update process by the Package Management System (PMS), you 2857 can identify these files so that the PMS will not overwrite them. See 2858 the :term:`CONFFILES` variable for information on 2859 how to identify these files to the PMS. 2860 2861 :term:`FILES_SOLIBSDEV` 2862 Defines the file specification to match 2863 :term:`SOLIBSDEV`. In other words, 2864 :term:`FILES_SOLIBSDEV` defines the full path name of the development 2865 symbolic link (symlink) for shared libraries on the target platform. 2866 2867 The following statement from the ``bitbake.conf`` shows how it is 2868 set:: 2869 2870 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" 2871 2872 :term:`FILESEXTRAPATHS` 2873 A colon-separated list to extend the search path the OpenEmbedded build 2874 system uses when looking for files and patches as it processes recipes 2875 and append files. The default directories BitBake uses when it processes 2876 recipes are initially defined by the :term:`FILESPATH` variable. You can 2877 extend :term:`FILESPATH` variable by using :term:`FILESEXTRAPATHS`. 2878 2879 Best practices dictate that you accomplish this by using 2880 :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you 2881 prepend paths as follows:: 2882 2883 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 2884 2885 In the above example, the build system first 2886 looks for files in a directory that has the same name as the 2887 corresponding append file. 2888 2889 .. note:: 2890 2891 When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate 2892 expansion (``:=``) operator. Immediate expansion makes sure that 2893 BitBake evaluates :term:`THISDIR` at the time the 2894 directive is encountered rather than at some later time when 2895 expansion might result in a directory that does not contain the 2896 files you need. 2897 2898 Also, include the trailing separating colon character if you are 2899 prepending. The trailing colon character is necessary because you 2900 are directing BitBake to extend the path by prepending directories 2901 to the search path. 2902 2903 Here is another common use:: 2904 2905 FILESEXTRAPATHS:prepend := "${THISDIR}/files:" 2906 2907 In this example, the build system extends the 2908 :term:`FILESPATH` variable to include a directory named ``files`` that is 2909 in the same directory as the corresponding append file. 2910 2911 This next example specifically adds three paths:: 2912 2913 FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:" 2914 2915 A final example shows how you can extend the search path and include 2916 a :term:`MACHINE`-specific override, which is useful 2917 in a BSP layer:: 2918 2919 FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:" 2920 2921 The previous statement appears in the 2922 ``linux-yocto-dev.bbappend`` file, which is found in the 2923 :ref:`overview-manual/development-environment:yocto project source repositories` in 2924 ``meta-intel/common/recipes-kernel/linux``. Here, the machine 2925 override is a special :term:`PACKAGE_ARCH` 2926 definition for multiple ``meta-intel`` machines. 2927 2928 .. note:: 2929 2930 For a layer that supports a single BSP, the override could just be 2931 the value of :term:`MACHINE`. 2932 2933 By prepending paths in ``.bbappend`` files, you allow multiple append 2934 files that reside in different layers but are used for the same 2935 recipe to correctly extend the path. 2936 2937 :term:`FILESOVERRIDES` 2938 A colon-separated list to specify a subset of :term:`OVERRIDES` used by 2939 the OpenEmbedded build system for creating :term:`FILESPATH`. The 2940 :term:`FILESOVERRIDES` variable uses overrides to automatically extend 2941 the :term:`FILESPATH` variable. For an example of how that works, see the 2942 :term:`FILESPATH` variable description. Additionally, you find more 2943 information on how overrides are handled in the 2944 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 2945 section of the BitBake User Manual. 2946 2947 By default, the :term:`FILESOVERRIDES` variable is defined as:: 2948 2949 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" 2950 2951 .. note:: 2952 2953 Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up 2954 with expected overrides and are used in an expected manner by the 2955 build system. 2956 2957 :term:`FILESPATH` 2958 A colon-separated list specifying the default set of directories the 2959 OpenEmbedded build system uses when searching for patches and files. 2960 2961 During the build process, BitBake searches each directory in 2962 :term:`FILESPATH` in the specified order when looking for files and 2963 patches specified by each ``file://`` URI in a recipe's 2964 :term:`SRC_URI` statements. 2965 2966 The default value for the :term:`FILESPATH` variable is defined in the 2967 :ref:`ref-classes-base` class found in ``meta/classes-global`` in the 2968 :term:`Source Directory`:: 2969 2970 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ 2971 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" 2972 2973 The 2974 :term:`FILESPATH` variable is automatically extended using the overrides 2975 from the :term:`FILESOVERRIDES` variable. 2976 2977 .. note:: 2978 2979 - Do not hand-edit the :term:`FILESPATH` variable. If you want the 2980 build system to look in directories other than the defaults, 2981 extend the :term:`FILESPATH` variable by using the 2982 :term:`FILESEXTRAPATHS` variable. 2983 2984 - Be aware that the default :term:`FILESPATH` directories do not map 2985 to directories in custom layers where append files 2986 (``.bbappend``) are used. If you want the build system to find 2987 patches or files that reside with your append files, you need 2988 to extend the :term:`FILESPATH` variable by using the 2989 :term:`FILESEXTRAPATHS` variable. 2990 2991 You can take advantage of this searching behavior in useful ways. For 2992 example, consider a case where there is the following directory structure 2993 for general and machine-specific configurations:: 2994 2995 files/defconfig 2996 files/MACHINEA/defconfig 2997 files/MACHINEB/defconfig 2998 2999 Also in the example, the :term:`SRC_URI` statement contains 3000 "file://defconfig". Given this scenario, you can set 3001 :term:`MACHINE` to "MACHINEA" and cause the build 3002 system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to 3003 "MACHINEB" and the build system uses files from ``files/MACHINEB``. 3004 Finally, for any machine other than "MACHINEA" and "MACHINEB", the 3005 build system uses files from ``files/defconfig``. 3006 3007 You can find out more about the patching process in the 3008 ":ref:`overview-manual/concepts:patching`" section 3009 in the Yocto Project Overview and Concepts Manual and the 3010 ":ref:`dev-manual/new-recipe:patching code`" section in 3011 the Yocto Project Development Tasks Manual. See the 3012 :ref:`ref-tasks-patch` task as well. 3013 3014 :term:`FILESYSTEM_PERMS_TABLES` 3015 Allows you to define your own file permissions settings tables as part 3016 of your configuration for the packaging process. For example, suppose 3017 you need a consistent set of custom permissions for a set of groups 3018 and users across an entire work project. It is best to do this in the 3019 packages themselves but this is not always possible. 3020 3021 By default, the OpenEmbedded build system uses the ``fs-perms.txt``, 3022 ``fs-perms-volatile-log.txt`` and ``fs-perms-volatile-tmp.txt`` which are 3023 located in the ``meta/files`` folder in the :term:`Source Directory`. If 3024 you create your own permission setting table files, you should place 3025 those in your layer. 3026 3027 You can override the value of :term:`FILESYSTEM_PERMS_TABLES` variable 3028 in your distribution configuration file to point to your custom 3029 permission table files. You can specify one or more file permissions 3030 setting tables. The paths that you specify to these files must be defined 3031 within the :term:`BBPATH` variable. 3032 3033 In order to disable the volatile log, which is enabled by default, one 3034 can remove the ``files/fs-perms-volatile-log.txt`` value from 3035 ``FILESYSTEM_PERMS_TABLES``. Similarly, in order to disable the volatile 3036 tmp, one can remove the ``files/fs-perms-volatile-tmp.txt`` value. 3037 3038 For guidance on how to define your own file permissions settings 3039 tables, examine the existing ``fs-perms.txt``, 3040 ``fs-perms-volatile-log.txt`` and ``fs-perms-volatile-tmp.txt`` files. 3041 3042 :term:`FIT_ADDRESS_CELLS` 3043 Specifies the value of the ``#address-cells`` value for the 3044 description of the FIT image. 3045 3046 The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` 3047 class, which corresponds to 32 bit addresses. 3048 3049 For platforms that need to set 64 bit addresses, for example in 3050 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to 3051 set this value to "2", as two 32 bit values (cells) will be needed 3052 to represent such addresses. 3053 3054 Here is an example setting "0x400000000" as a load address:: 3055 3056 FIT_ADDRESS_CELLS = "2" 3057 UBOOT_LOADADDRESS= "0x04 0x00000000" 3058 3059 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. 3060 3061 :term:`FIT_CONF_DEFAULT_DTB` 3062 Specifies the default device tree binary (dtb) file for a FIT image 3063 when multiple ones are provided. 3064 3065 This variable is used in the :ref:`ref-classes-kernel-fitimage` class. 3066 3067 :term:`FIT_DESC` 3068 Specifies the description string encoded into a FIT image. The 3069 default value is set by the :ref:`ref-classes-kernel-fitimage` class as 3070 follows:: 3071 3072 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" 3073 3074 :term:`FIT_GENERATE_KEYS` 3075 Decides whether to generate the keys for signing the FIT image if 3076 they don't already exist. The keys are created in 3077 :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0" 3078 by the :ref:`ref-classes-kernel-fitimage` class. 3079 3080 :term:`FIT_HASH_ALG` 3081 Specifies the hash algorithm used in creating the FIT Image. 3082 This variable is set by default to "sha256" by the 3083 :ref:`ref-classes-kernel-fitimage` class. 3084 3085 :term:`FIT_KERNEL_COMP_ALG` 3086 The compression algorithm to use for the kernel image inside the FIT Image. 3087 At present, the only supported values are "gzip" (default), "lzo" or "none". 3088 If you set this variable to anything other than "none" you may also need 3089 to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`. 3090 3091 This variable is used in the :ref:`ref-classes-kernel-uboot` class. 3092 3093 :term:`FIT_KERNEL_COMP_ALG_EXTENSION` 3094 File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default 3095 value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you 3096 set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this 3097 variable to ".lzo". 3098 3099 :term:`FIT_KEY_GENRSA_ARGS` 3100 Arguments to ``openssl genrsa`` for generating a RSA private key for 3101 signing the FIT image. The default value is set to "-F4" by the 3102 :ref:`ref-classes-kernel-fitimage` class. 3103 3104 :term:`FIT_KEY_REQ_ARGS` 3105 Arguments to ``openssl req`` for generating a certificate for signing 3106 the FIT image. The default value is "-batch -new" by the 3107 :ref:`ref-classes-kernel-fitimage` class, "batch" for 3108 non interactive mode and "new" for generating new keys. 3109 3110 :term:`FIT_KEY_SIGN_PKCS` 3111 Format for the public key certificate used for signing the FIT image. 3112 The default value is set to "x509" by the 3113 :ref:`ref-classes-kernel-fitimage` class. 3114 3115 :term:`FIT_SIGN_ALG` 3116 Specifies the signature algorithm used in creating the FIT Image. 3117 This variable is set by default to "rsa2048" by the 3118 :ref:`ref-classes-kernel-fitimage` class. 3119 3120 :term:`FIT_PAD_ALG` 3121 Specifies the padding algorithm used in creating the FIT Image. 3122 The default value is set to "pkcs-1.5" by the 3123 :ref:`ref-classes-kernel-fitimage` class. 3124 3125 :term:`FIT_SIGN_INDIVIDUAL` 3126 If set to "1", then the :ref:`ref-classes-kernel-fitimage` 3127 class will sign the kernel, dtb and ramdisk images individually in addition 3128 to signing the FIT image itself. This could be useful if you are 3129 intending to verify signatures in another context than booting via 3130 U-Boot. 3131 3132 This variable is set to "0" by default. 3133 3134 :term:`FIT_SIGN_NUMBITS` 3135 Size of the private key used in the FIT image, in number of bits. 3136 The default value for this variable is set to "2048" 3137 by the :ref:`ref-classes-kernel-fitimage` class. 3138 3139 :term:`FONT_EXTRA_RDEPENDS` 3140 When inheriting the :ref:`ref-classes-fontcache` class, 3141 this variable specifies the runtime dependencies for font packages. 3142 By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils". 3143 3144 :term:`FONT_PACKAGES` 3145 When inheriting the :ref:`ref-classes-fontcache` class, this variable 3146 identifies packages containing font files that need to be cached by 3147 Fontconfig. By default, the :ref:`ref-classes-fontcache` class assumes 3148 that fonts are in the recipe's main package (i.e. 3149 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you 3150 need are in a package other than that main package. 3151 3152 :term:`FORCE_RO_REMOVE` 3153 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED`` 3154 during the generation of the root filesystem. 3155 3156 Set the variable to "1" to force the removal of these packages. 3157 3158 :term:`FULL_OPTIMIZATION` 3159 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when 3160 compiling an optimized system. This variable defaults to "-O2 -pipe 3161 ${DEBUG_FLAGS}". 3162 3163 :term:`GCCPIE` 3164 Enables Position Independent Executables (PIE) within the GNU C 3165 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented 3166 Programming (ROP) attacks much more difficult to execute. 3167 3168 By default the ``security_flags.inc`` file enables PIE by setting the 3169 variable as follows:: 3170 3171 GCCPIE ?= "--enable-default-pie" 3172 3173 :term:`GCCVERSION` 3174 Specifies the default version of the GNU C Compiler (GCC) used for 3175 compilation. By default, :term:`GCCVERSION` is set to "8.x" in the 3176 ``meta/conf/distro/include/tcmode-default.inc`` include file:: 3177 3178 GCCVERSION ?= "8.%" 3179 3180 You can override this value by setting it in a 3181 configuration file such as the ``local.conf``. 3182 3183 :term:`GDB` 3184 The minimal command and arguments to run the GNU Debugger. 3185 3186 :term:`GIR_EXTRA_LIBS_PATH` 3187 Allows to specify an extra search path for ``.so`` files 3188 in GLib related recipes using GObject introspection, 3189 and which do not compile without this setting. 3190 See the ":ref:`dev-manual/gobject-introspection:enabling gobject introspection support`" 3191 section for details. 3192 3193 :term:`GITDIR` 3194 The directory in which a local copy of a Git repository is stored 3195 when it is cloned. 3196 3197 :term:`GITHUB_BASE_URI` 3198 When inheriting the :ref:`ref-classes-github-releases` 3199 class, specifies the base URL for fetching releases for the github 3200 project you wish to fetch sources from. The default value is as follows:: 3201 3202 GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/" 3203 3204 :term:`GLIBC_GENERATE_LOCALES` 3205 Specifies the list of GLIBC locales to generate should you not wish 3206 to generate all LIBC locals, which can be time consuming. 3207 3208 .. note:: 3209 3210 If you specifically remove the locale ``en_US.UTF-8``, you must set 3211 :term:`IMAGE_LINGUAS` appropriately. 3212 3213 You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file. 3214 By default, all locales are generated:: 3215 3216 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" 3217 3218 :term:`GO_IMPORT` 3219 When inheriting the :ref:`ref-classes-go` class, this mandatory variable 3220 sets the import path for the Go package that will be created for the code 3221 to build. If you have a ``go.mod`` file in the source directory, this 3222 typically matches the path in the ``module`` line in this file. 3223 3224 Other Go programs importing this package will use this path. 3225 3226 Here is an example setting from the 3227 :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>` 3228 recipe:: 3229 3230 GO_IMPORT = "golang.org/x/example" 3231 3232 :term:`GO_INSTALL` 3233 When inheriting the :ref:`ref-classes-go` class, this optional variable 3234 specifies which packages in the sources should be compiled and 3235 installed in the Go build space by the 3236 `go install <https://go.dev/ref/mod#go-install>`__ command. 3237 3238 Here is an example setting from the 3239 :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>` 3240 recipe:: 3241 3242 GO_INSTALL = "\ 3243 ${GO_IMPORT}/cmd/crucible \ 3244 ${GO_IMPORT}/cmd/habtool \ 3245 " 3246 3247 By default, :term:`GO_INSTALL` is defined as:: 3248 3249 GO_INSTALL ?= "${GO_IMPORT}/..." 3250 3251 The ``...`` wildcard means that it will catch all 3252 packages found in the sources. 3253 3254 See the :term:`GO_INSTALL_FILTEROUT` variable for 3255 filtering out unwanted packages from the ones 3256 found from the :term:`GO_INSTALL` value. 3257 3258 :term:`GO_INSTALL_FILTEROUT` 3259 When using the Go "vendor" mechanism to bring in dependencies for a Go 3260 package, the default :term:`GO_INSTALL` setting, which uses the ``...`` 3261 wildcard, will include the vendored packages in the build, which produces 3262 incorrect results. 3263 3264 There are also some Go packages that are structured poorly, so that the 3265 ``...`` wildcard results in building example or test code that should not 3266 be included in the build, or could fail to build. 3267 3268 This optional variable allows for filtering out a subset of the sources. 3269 It defaults to excluding everything under the ``vendor`` subdirectory 3270 under package's main directory. This is the normal location for vendored 3271 packages, but it can be overridden by a recipe to filter out other 3272 subdirectories if needed. 3273 3274 :term:`GO_WORKDIR` 3275 When using Go Modules, the current working directory must be the directory 3276 containing the ``go.mod`` file, or one of its subdirectories. When the 3277 ``go`` tool is used, it will automatically look for the ``go.mod`` file 3278 in the Go working directory or in any parent directory, but not in 3279 subdirectories. 3280 3281 When using the :ref:`ref-classes-go-mod` class to use Go modules, 3282 the optional :term:`GO_WORKDIR` variable, defaulting to the value 3283 of :term:`GO_IMPORT`, allows to specify a different Go working directory. 3284 3285 :term:`GROUPADD_PARAM` 3286 When inheriting the :ref:`ref-classes-useradd` class, 3287 this variable specifies for a package what parameters should be 3288 passed to the ``groupadd`` command if you wish to add a group to the 3289 system when the package is installed. 3290 3291 Here is an example from the ``dbus`` recipe:: 3292 3293 GROUPADD_PARAM:${PN} = "-r netdev" 3294 3295 More than one group can be added by separating each set of different 3296 groups' parameters with a semicolon. 3297 3298 Here is an example adding multiple groups from the ``useradd-example.bb`` 3299 file in the ``meta-skeleton`` layer:: 3300 3301 GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2" 3302 3303 For information on the standard Linux shell command 3304 ``groupadd``, see https://linux.die.net/man/8/groupadd. 3305 3306 :term:`GROUPMEMS_PARAM` 3307 When inheriting the :ref:`ref-classes-useradd` class, 3308 this variable specifies for a package what parameters should be 3309 passed to the ``groupmems`` command if you wish to modify the members 3310 of a group when the package is installed. 3311 3312 For information on the standard Linux shell command ``groupmems``, 3313 see https://linux.die.net/man/8/groupmems. 3314 3315 :term:`GRUB_GFXSERIAL` 3316 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics 3317 and serial in the boot menu. Set this variable to "1" in your 3318 ``local.conf`` or distribution configuration file to enable graphics 3319 and serial in the menu. 3320 3321 See the :ref:`ref-classes-grub-efi` class for more 3322 information on how this variable is used. 3323 3324 :term:`GRUB_OPTS` 3325 Additional options to add to the GNU GRand Unified Bootloader (GRUB) 3326 configuration. Use a semi-colon character (``;``) to separate 3327 multiple options. 3328 3329 The :term:`GRUB_OPTS` variable is optional. See the 3330 :ref:`ref-classes-grub-efi` class for more information 3331 on how this variable is used. 3332 3333 :term:`GRUB_TIMEOUT` 3334 Specifies the timeout before executing the default ``LABEL`` in the 3335 GNU GRand Unified Bootloader (GRUB). 3336 3337 The :term:`GRUB_TIMEOUT` variable is optional. See the 3338 :ref:`ref-classes-grub-efi` class for more information 3339 on how this variable is used. 3340 3341 :term:`GTKIMMODULES_PACKAGES` 3342 When inheriting the :ref:`ref-classes-gtk-immodules-cache` class, 3343 this variable specifies the packages that contain the GTK+ input 3344 method modules being installed when the modules are in packages other 3345 than the main package. 3346 3347 :term:`HGDIR` 3348 See :term:`bitbake:HGDIR` in the BitBake manual. 3349 3350 :term:`HOMEPAGE` 3351 Website where more information about the software the recipe is 3352 building can be found. 3353 3354 :term:`HOST_ARCH` 3355 The name of the target architecture, which is normally the same as 3356 :term:`TARGET_ARCH`. The OpenEmbedded build system 3357 supports many architectures. Here is an example list of architectures 3358 supported. This list is by no means complete as the architecture is 3359 configurable: 3360 3361 - arm 3362 - i586 3363 - x86_64 3364 - powerpc 3365 - powerpc64 3366 - mips 3367 - mipsel 3368 3369 :term:`HOST_CC_ARCH` 3370 Specifies architecture-specific compiler flags that are passed to the 3371 C compiler. 3372 3373 Default initialization for :term:`HOST_CC_ARCH` varies depending on what 3374 is being built: 3375 3376 - :term:`TARGET_CC_ARCH` when building for the 3377 target 3378 3379 - :term:`BUILD_CC_ARCH` when building for the build host (i.e. 3380 ``-native``) 3381 3382 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e. 3383 ``nativesdk-``) 3384 3385 :term:`HOST_OS` 3386 Specifies the name of the target operating system, which is normally 3387 the same as the :term:`TARGET_OS`. The variable can 3388 be set to "linux" for ``glibc``-based systems and to "linux-musl" for 3389 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and 3390 "linux-musleabi" values possible. 3391 3392 :term:`HOST_PREFIX` 3393 Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX` 3394 is normally the same as :term:`TARGET_PREFIX`. 3395 3396 :term:`HOST_SYS` 3397 Specifies the system, including the architecture and the operating 3398 system, for which the build is occurring in the context of the 3399 current recipe. 3400 3401 The OpenEmbedded build system automatically sets this variable based 3402 on :term:`HOST_ARCH`, 3403 :term:`HOST_VENDOR`, and 3404 :term:`HOST_OS` variables. 3405 3406 .. note:: 3407 3408 You do not need to set the variable yourself. 3409 3410 Consider these two examples: 3411 3412 - Given a native recipe on a 32-bit x86 machine running Linux, the 3413 value is "i686-linux". 3414 3415 - Given a recipe being built for a little-endian MIPS target running 3416 Linux, the value might be "mipsel-linux". 3417 3418 :term:`HOST_VENDOR` 3419 Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the 3420 same as :term:`TARGET_VENDOR`. 3421 3422 :term:`HOSTTOOLS` 3423 A space-separated list (filter) of tools on the build host that 3424 should be allowed to be called from within build tasks. Using this 3425 filter helps reduce the possibility of host contamination. If a tool 3426 specified in the value of :term:`HOSTTOOLS` is not found on the build 3427 host, the OpenEmbedded build system produces an error and the build 3428 is not started. 3429 3430 For additional information, see 3431 :term:`HOSTTOOLS_NONFATAL`. 3432 3433 :term:`HOSTTOOLS_NONFATAL` 3434 A space-separated list (filter) of tools on the build host that 3435 should be allowed to be called from within build tasks. Using this 3436 filter helps reduce the possibility of host contamination. Unlike 3437 :term:`HOSTTOOLS`, the OpenEmbedded build system 3438 does not produce an error if a tool specified in the value of 3439 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can 3440 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools. 3441 3442 :term:`ICECC_CLASS_DISABLE` 3443 Identifies user classes that you do not want the Icecream distributed 3444 compile support to consider. This variable is used by the 3445 :ref:`ref-classes-icecc` class. You set this variable in 3446 your ``local.conf`` file. 3447 3448 When you list classes using this variable, the recipes inheriting 3449 those classes will not benefit from distributed compilation across 3450 remote hosts. Instead they will be built locally. 3451 3452 :term:`ICECC_DISABLED` 3453 Disables or enables the ``icecc`` (Icecream) function. For more 3454 information on this function and best practices for using this 3455 variable, see the ":ref:`ref-classes-icecc`" 3456 section. 3457 3458 Setting this variable to "1" in your ``local.conf`` disables the 3459 function:: 3460 3461 ICECC_DISABLED ??= "1" 3462 3463 To enable the function, set the variable as follows:: 3464 3465 ICECC_DISABLED = "" 3466 3467 :term:`ICECC_ENV_EXEC` 3468 Points to the ``icecc-create-env`` script that you provide. This 3469 variable is used by the :ref:`ref-classes-icecc` class. You 3470 set this variable in your ``local.conf`` file. 3471 3472 If you do not point to a script that you provide, the OpenEmbedded 3473 build system uses the default script provided by the 3474 :oe_git:`icecc-create-env_0.1.bb 3475 </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>` 3476 recipe, which is a modified version and not the one that comes with 3477 ``icecream``. 3478 3479 :term:`ICECC_PARALLEL_MAKE` 3480 Extra options passed to the ``make`` command during the 3481 :ref:`ref-tasks-compile` task that specify parallel 3482 compilation. This variable usually takes the form of "-j x", where x 3483 represents the maximum number of parallel threads ``make`` can run. 3484 3485 .. note:: 3486 3487 The options passed affect builds on all enabled machines on the 3488 network, which are machines running the ``iceccd`` daemon. 3489 3490 If your enabled machines support multiple cores, coming up with the 3491 maximum number of parallel threads that gives you the best 3492 performance could take some experimentation since machine speed, 3493 network lag, available memory, and existing machine loads can all 3494 affect build time. Consequently, unlike the 3495 :term:`PARALLEL_MAKE` variable, there is no 3496 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal 3497 performance. 3498 3499 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not 3500 use it (i.e. the system does not detect and assign the number of 3501 cores as is done with :term:`PARALLEL_MAKE`). 3502 3503 :term:`ICECC_PATH` 3504 The location of the ``icecc`` binary. You can set this variable in 3505 your ``local.conf`` file. If your ``local.conf`` file does not define 3506 this variable, the :ref:`ref-classes-icecc` class attempts 3507 to define it by locating ``icecc`` using ``which``. 3508 3509 :term:`ICECC_RECIPE_DISABLE` 3510 Identifies user recipes that you do not want the Icecream distributed 3511 compile support to consider. This variable is used by the 3512 :ref:`ref-classes-icecc` class. You set this variable in 3513 your ``local.conf`` file. 3514 3515 When you list recipes using this variable, you are excluding them 3516 from distributed compilation across remote hosts. Instead they will 3517 be built locally. 3518 3519 :term:`ICECC_RECIPE_ENABLE` 3520 Identifies user recipes that use an empty 3521 :term:`PARALLEL_MAKE` variable that you want to 3522 force remote distributed compilation on using the Icecream 3523 distributed compile support. This variable is used by the 3524 :ref:`ref-classes-icecc` class. You set this variable in 3525 your ``local.conf`` file. 3526 3527 :term:`IMAGE_BASENAME` 3528 The base name of image output files. This variable defaults to the 3529 recipe name (``${``\ :term:`PN`\ ``}``). 3530 3531 :term:`IMAGE_BOOT_FILES` 3532 A space-separated list of files installed into the boot partition 3533 when preparing an image using the Wic tool with the 3534 ``bootimg-partition`` source plugin. By default, 3535 the files are 3536 installed under the same name as the source files. To change the 3537 installed name, separate it from the original name with a semi-colon 3538 (;). Source files need to be located in 3539 :term:`DEPLOY_DIR_IMAGE`. Here are two 3540 examples:: 3541 3542 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" 3543 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" 3544 3545 Alternatively, source files can be picked up using a glob pattern. In 3546 this case, the destination file must have the same name as the base 3547 name of the source file path. To install files into a directory 3548 within the target location, pass its name after a semi-colon (;). 3549 Here are two examples:: 3550 3551 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" 3552 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" 3553 3554 The first example 3555 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles`` 3556 into the root of the target partition. The second example installs 3557 the same files into a ``boot`` directory within the target partition. 3558 3559 You can find information on how to use the Wic tool in the 3560 ":ref:`dev-manual/wic:creating partitioned images using wic`" 3561 section of the Yocto Project Development Tasks Manual. Reference 3562 material for Wic is located in the 3563 ":doc:`/ref-manual/kickstart`" chapter. 3564 3565 :term:`IMAGE_BUILDINFO_FILE` 3566 When using the :ref:`ref-classes-image-buildinfo` class, 3567 specifies the file in the image to write the build information into. The 3568 default value is "``${sysconfdir}/buildinfo``". 3569 3570 :term:`IMAGE_BUILDINFO_VARS` 3571 When using the :ref:`ref-classes-image-buildinfo` class, 3572 specifies the list of variables to include in the `Build Configuration` 3573 section of the output file (as a space-separated list). Defaults to 3574 ":term:`DISTRO` :term:`DISTRO_VERSION`". 3575 3576 :term:`IMAGE_CLASSES` 3577 A list of classes that all images should inherit. This is typically used 3578 to enable functionality across all image recipes. 3579 3580 Classes specified in :term:`IMAGE_CLASSES` must be located in the 3581 ``classes-recipe/`` or ``classes/`` subdirectories. 3582 3583 :term:`IMAGE_CMD` 3584 Specifies the command to create the image file for a specific image 3585 type, which corresponds to the value set in 3586 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, 3587 ``btrfs``, and so forth). When setting this variable, you should use 3588 an override for the associated type. Here is an example:: 3589 3590 IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \ 3591 --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \ 3592 ${EXTRA_IMAGECMD}" 3593 3594 You typically do not need to set this variable unless you are adding 3595 support for a new image type. For more examples on how to set this 3596 variable, see the :ref:`ref-classes-image_types` 3597 class file, which is ``meta/classes-recipe/image_types.bbclass``. 3598 3599 :term:`IMAGE_DEVICE_TABLES` 3600 Specifies one or more files that contain custom device tables that 3601 are passed to the ``makedevs`` command as part of creating an image. 3602 These files list basic device nodes that should be created under 3603 ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set, 3604 ``files/device_table-minimal.txt`` is used, which is located by 3605 :term:`BBPATH`. For details on how you should write 3606 device table files, see ``meta/files/device_table-minimal.txt`` as an 3607 example. 3608 3609 :term:`IMAGE_EFI_BOOT_FILES` 3610 A space-separated list of files installed into the boot partition 3611 when preparing an image using the Wic tool with the 3612 ``bootimg-efi`` source plugin. By default, 3613 the files are 3614 installed under the same name as the source files. To change the 3615 installed name, separate it from the original name with a semi-colon 3616 (;). Source files need to be located in 3617 :term:`DEPLOY_DIR_IMAGE`. Here are two 3618 examples:: 3619 3620 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" 3621 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" 3622 3623 Alternatively, source files can be picked up using a glob pattern. In 3624 this case, the destination file must have the same name as the base 3625 name of the source file path. To install files into a directory 3626 within the target location, pass its name after a semi-colon (;). 3627 Here are two examples:: 3628 3629 IMAGE_EFI_BOOT_FILES = "boot/loader/*" 3630 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" 3631 3632 The first example 3633 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/`` 3634 into the root of the target partition. The second example installs 3635 the same files into a ``boot`` directory within the target partition. 3636 3637 You can find information on how to use the Wic tool in the 3638 ":ref:`dev-manual/wic:creating partitioned images using wic`" 3639 section of the Yocto Project Development Tasks Manual. Reference 3640 material for Wic is located in the 3641 ":doc:`/ref-manual/kickstart`" chapter. 3642 3643 :term:`IMAGE_FEATURES` 3644 The primary list of features to include in an image. Typically, you 3645 configure this variable in an image recipe. Although you can use this 3646 variable from your ``local.conf`` file, which is found in the 3647 :term:`Build Directory`, best practices dictate that you do 3648 not. 3649 3650 .. note:: 3651 3652 To enable extra features from outside the image recipe, use the 3653 :term:`EXTRA_IMAGE_FEATURES` variable. 3654 3655 For a list of image features that ships with the Yocto Project, see 3656 the ":ref:`ref-features-image`" section. 3657 3658 For an example that shows how to customize your image by using this 3659 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 3660 section in the Yocto Project Development Tasks Manual. 3661 3662 :term:`IMAGE_FSTYPES` 3663 Specifies the formats the OpenEmbedded build system uses during the 3664 build when creating the root filesystem. For example, setting 3665 :term:`IMAGE_FSTYPES` as follows causes the build system to create root 3666 filesystems using two formats: ``.ext3`` and ``.tar.bz2``:: 3667 3668 IMAGE_FSTYPES = "ext3 tar.bz2" 3669 3670 For the complete list of supported image formats from which you can 3671 choose, see :term:`IMAGE_TYPES`. 3672 3673 .. note:: 3674 3675 - If an image recipe uses the "inherit image" line and you are 3676 setting :term:`IMAGE_FSTYPES` inside the recipe, you must set 3677 :term:`IMAGE_FSTYPES` prior to using the "inherit image" line. 3678 3679 - Due to the way the OpenEmbedded build system processes this 3680 variable, you cannot update its contents by using ``:append`` 3681 or ``:prepend``. You must use the ``+=`` operator to add one or 3682 more options to the :term:`IMAGE_FSTYPES` variable. 3683 3684 :term:`IMAGE_INSTALL` 3685 Used by recipes to specify the packages to install into an image 3686 through the :ref:`ref-classes-image` class. Use the 3687 :term:`IMAGE_INSTALL` variable with care to avoid ordering issues. 3688 3689 Image recipes set :term:`IMAGE_INSTALL` to specify the packages to 3690 install into an image through :ref:`ref-classes-image`. Additionally, 3691 there are "helper" classes such as the :ref:`ref-classes-core-image` 3692 class which can take lists used with :term:`IMAGE_FEATURES` and turn 3693 them into auto-generated entries in :term:`IMAGE_INSTALL` in addition 3694 to its default contents. 3695 3696 When you use this variable, it is best to use it as follows:: 3697 3698 IMAGE_INSTALL:append = " package-name" 3699 3700 Be sure to include the space 3701 between the quotation character and the start of the package name or 3702 names. 3703 3704 .. note:: 3705 3706 - When working with a 3707 :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 3708 image, do not use the :term:`IMAGE_INSTALL` variable to specify 3709 packages for installation. Instead, use the 3710 :term:`PACKAGE_INSTALL` variable, which 3711 allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a 3712 fixed set of packages and not be affected by :term:`IMAGE_INSTALL`. 3713 For information on creating an :term:`Initramfs`, see the 3714 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" 3715 section in the Yocto Project Development Tasks Manual. 3716 3717 - Using :term:`IMAGE_INSTALL` with the 3718 :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` 3719 BitBake operator within the ``/conf/local.conf`` file or from 3720 within an image recipe is not recommended. Use of this operator in 3721 these ways can cause ordering issues. Since 3722 :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a 3723 default value using the 3724 :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` 3725 operator, using a ``+=`` operation against :term:`IMAGE_INSTALL` 3726 results in unexpected behavior when used within 3727 ``conf/local.conf``. Furthermore, the same operation from within an 3728 image recipe may or may not succeed depending on the specific 3729 situation. In both these cases, the behavior is contrary to how 3730 most users expect the ``+=`` operator to work. 3731 3732 :term:`IMAGE_LINGUAS` 3733 Specifies the list of locales to install into the image during the 3734 root filesystem construction process. The OpenEmbedded build system 3735 automatically splits locale files, which are used for localization, 3736 into separate packages. Setting the :term:`IMAGE_LINGUAS` variable 3737 ensures that any locale packages that correspond to packages already 3738 selected for installation into the image are also installed. Here is 3739 an example:: 3740 3741 IMAGE_LINGUAS = "pt-br de-de" 3742 3743 In this example, the build system ensures any Brazilian Portuguese 3744 and German locale files that correspond to packages in the image are 3745 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as 3746 ``*-locale-pt`` and ``*-locale-de``, since some software packages 3747 only provide locale files by language and not by country-specific 3748 language). 3749 3750 See the :term:`GLIBC_GENERATE_LOCALES` 3751 variable for information on generating GLIBC locales. 3752 3753 3754 :term:`IMAGE_LINK_NAME` 3755 The name of the output image symlink (which does not include 3756 the version part as :term:`IMAGE_NAME` does). The default value 3757 is derived using the :term:`IMAGE_BASENAME` and 3758 :term:`IMAGE_MACHINE_SUFFIX` variables:: 3759 3760 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}" 3761 3762 .. note:: 3763 3764 It is possible to set this to "" to disable symlink creation, 3765 however, you also need to set :term:`IMAGE_NAME` to still have 3766 a reasonable value e.g.:: 3767 3768 IMAGE_LINK_NAME = "" 3769 IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" 3770 3771 :term:`IMAGE_MACHINE_SUFFIX` 3772 Specifies the by default machine-specific suffix for image file names 3773 (before the extension). The default value is set as follows:: 3774 3775 IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}" 3776 3777 The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE` 3778 subdirectory, so you may find it unnecessary to also include this suffix 3779 in the name of every image file. If you prefer to remove the suffix you 3780 can set this variable to an empty string:: 3781 3782 IMAGE_MACHINE_SUFFIX = "" 3783 3784 (Not to be confused with :term:`IMAGE_NAME_SUFFIX`.) 3785 3786 :term:`IMAGE_MANIFEST` 3787 The manifest file for the image. This file lists all the installed 3788 packages that make up the image. The file contains package 3789 information on a line-per-package basis as follows:: 3790 3791 packagename packagearch version 3792 3793 The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest 3794 file as follows:: 3795 3796 IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest" 3797 3798 The location is 3799 derived using the :term:`IMGDEPLOYDIR` 3800 and :term:`IMAGE_NAME` variables. You can find 3801 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" 3802 section in the Yocto Project Overview and Concepts Manual. 3803 3804 :term:`IMAGE_NAME` 3805 The name of the output image files minus the extension. By default 3806 this variable is set using the :term:`IMAGE_LINK_NAME`, and 3807 :term:`IMAGE_VERSION_SUFFIX` variables:: 3808 3809 IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}" 3810 3811 :term:`IMAGE_NAME_SUFFIX` 3812 Suffix used for the image output filename --- defaults to ``".rootfs"`` 3813 to distinguish the image file from other files created during image 3814 building; however if this suffix is redundant or not desired you can 3815 clear the value of this variable (set the value to ""). For example, 3816 this is typically cleared in :term:`Initramfs` image recipes. 3817 3818 :term:`IMAGE_OUTPUT_MANIFEST` 3819 When inheriting the :ref:`ref-classes-image` class directly or through the 3820 :ref:`ref-classes-core-image` class, the :term:`IMAGE_OUTPUT_MANIFEST` 3821 points to a manifest ``json`` file that lists what images were created by 3822 various image creation tasks (as defined by the :term:`IMAGE_FSTYPES` 3823 variable). It is set in the :ref:`ref-classes-image` class as follows:: 3824 3825 IMAGE_OUTPUT_MANIFEST = "${IMAGE_OUTPUT_MANIFEST_DIR}/manifest.json" 3826 3827 :term:`IMAGE_OUTPUT_MANIFEST_DIR` 3828 When inheriting the :ref:`ref-classes-image` class directly or through the 3829 :ref:`ref-classes-core-image` class, the :term:`IMAGE_OUTPUT_MANIFEST_DIR` points to 3830 a directory that stores a manifest ``json`` file that lists what 3831 images were created by various image creation tasks (as defined by the 3832 :term:`IMAGE_FSTYPES` variable). It is set in the :ref:`ref-classes-image` 3833 class as follows:: 3834 3835 IMAGE_OUTPUT_MANIFEST_DIR = "${WORKDIR}/deploy-image-output-manifest" 3836 3837 :term:`IMAGE_OVERHEAD_FACTOR` 3838 Defines a multiplier that the build system applies to the initial 3839 image size for cases when the multiplier times the returned disk 3840 usage value for the image is greater than the sum of 3841 :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of 3842 the multiplier applied to the initial image size creates free disk 3843 space in the image as overhead. By default, the build process uses a 3844 multiplier of 1.3 for this variable. This default value results in 3845 30% free disk space added to the image when this method is used to 3846 determine the final generated image size. You should be aware that 3847 post install scripts and the package management system uses disk 3848 space inside this overhead area. Consequently, the multiplier does 3849 not produce an image with all the theoretical free disk space. See 3850 :term:`IMAGE_ROOTFS_SIZE` for information on how the build system 3851 determines the overall image size. 3852 3853 The default 30% free disk space typically gives the image enough room 3854 to boot and allows for basic post installs while still leaving a 3855 small amount of free disk space. If 30% free space is inadequate, you 3856 can increase the default value. For example, the following setting 3857 gives you 50% free space added to the image:: 3858 3859 IMAGE_OVERHEAD_FACTOR = "1.5" 3860 3861 Alternatively, you can ensure a specific amount of free disk space is 3862 added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3863 variable. 3864 3865 :term:`IMAGE_PKGTYPE` 3866 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the 3867 OpenEmbedded build system. The variable is defined appropriately by 3868 the :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`, 3869 or :ref:`ref-classes-package_ipk` class. 3870 3871 The :ref:`ref-classes-populate-sdk-*` and :ref:`ref-classes-image` 3872 classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs. 3873 3874 You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the 3875 variable is set indirectly through the appropriate 3876 :ref:`package_* <ref-classes-package>` class using the 3877 :term:`PACKAGE_CLASSES` variable. The 3878 OpenEmbedded build system uses the first package type (e.g. DEB, RPM, 3879 or IPK) that appears with the variable 3880 3881 .. note:: 3882 3883 Files using the ``.tar`` format are never used as a substitute 3884 packaging format for DEB, RPM, and IPK formatted files for your image 3885 or SDK. 3886 3887 :term:`IMAGE_POSTPROCESS_COMMAND` 3888 Specifies a list of functions to call once the OpenEmbedded build 3889 system creates the final image output files. You can specify 3890 functions separated by spaces:: 3891 3892 IMAGE_POSTPROCESS_COMMAND += "function" 3893 3894 If you need to pass the root filesystem path to a command within the 3895 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3896 directory that becomes the root filesystem image. See the 3897 :term:`IMAGE_ROOTFS` variable for more 3898 information. 3899 3900 :term:`IMAGE_PREPROCESS_COMMAND` 3901 Specifies a list of functions to call before the OpenEmbedded build 3902 system creates the final image output files. You can specify 3903 functions separated by spaces:: 3904 3905 IMAGE_PREPROCESS_COMMAND += "function" 3906 3907 If you need to pass the root filesystem path to a command within the 3908 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3909 directory that becomes the root filesystem image. See the 3910 :term:`IMAGE_ROOTFS` variable for more 3911 information. 3912 3913 :term:`IMAGE_ROOTFS` 3914 The location of the root filesystem while it is under construction 3915 (i.e. during the :ref:`ref-tasks-rootfs` task). This 3916 variable is not configurable. Do not change it. 3917 3918 :term:`IMAGE_ROOTFS_ALIGNMENT` 3919 Specifies the alignment for the output image file in Kbytes. If the 3920 size of the image is not a multiple of this value, then the size is 3921 rounded up to the nearest multiple of the value. The default value is 3922 "1". See :term:`IMAGE_ROOTFS_SIZE` for 3923 additional information. 3924 3925 :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3926 Defines additional free disk space created in the image in Kbytes. By 3927 default, this variable is set to "0". This free disk space is added 3928 to the image after the build system determines the image size as 3929 described in :term:`IMAGE_ROOTFS_SIZE`. 3930 3931 This variable is particularly useful when you want to ensure that a 3932 specific amount of free disk space is available on a device after an 3933 image is installed and running. For example, to be sure 5 Gbytes of 3934 free disk space is available, set the variable as follows:: 3935 3936 IMAGE_ROOTFS_EXTRA_SPACE = "5242880" 3937 3938 For example, the Yocto Project Build Appliance specifically requests 3939 40 Gbytes of extra space with the line:: 3940 3941 IMAGE_ROOTFS_EXTRA_SPACE = "41943040" 3942 3943 :term:`IMAGE_ROOTFS_SIZE` 3944 Defines the size in Kbytes for the generated image. The OpenEmbedded 3945 build system determines the final size for the generated image using 3946 an algorithm that takes into account the initial disk space used for 3947 the generated image, a requested size for the image, and requested 3948 additional free disk space to be added to the image. Programatically, 3949 the build system determines the final size of the generated image as 3950 follows:: 3951 3952 if (image-du * overhead) < rootfs-size: 3953 internal-rootfs-size = rootfs-size + xspace 3954 else: 3955 internal-rootfs-size = (image-du * overhead) + xspace 3956 where: 3957 image-du = Returned value of the du command on the image. 3958 overhead = IMAGE_OVERHEAD_FACTOR 3959 rootfs-size = IMAGE_ROOTFS_SIZE 3960 internal-rootfs-size = Initial root filesystem size before any modifications. 3961 xspace = IMAGE_ROOTFS_EXTRA_SPACE 3962 3963 See the :term:`IMAGE_OVERHEAD_FACTOR` 3964 and :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3965 variables for related information. 3966 3967 :term:`IMAGE_TYPEDEP` 3968 Specifies a dependency from one image type on another. Here is an 3969 example from the :ref:`ref-classes-image-live` class:: 3970 3971 IMAGE_TYPEDEP:live = "ext3" 3972 3973 In the previous example, the variable ensures that when "live" is 3974 listed with the :term:`IMAGE_FSTYPES` variable, 3975 the OpenEmbedded build system produces an ``ext3`` image first since 3976 one of the components of the live image is an ``ext3`` formatted 3977 partition containing the root filesystem. 3978 3979 :term:`IMAGE_TYPES` 3980 Specifies the complete list of supported image types by default: 3981 3982 - btrfs 3983 - container 3984 - cpio 3985 - cpio.gz 3986 - cpio.lz4 3987 - cpio.lzma 3988 - cpio.xz 3989 - cramfs 3990 - erofs 3991 - erofs-lz4 3992 - erofs-lz4hc 3993 - ext2 3994 - ext2.bz2 3995 - ext2.gz 3996 - ext2.lzma 3997 - ext3 3998 - ext3.gz 3999 - ext4 4000 - ext4.gz 4001 - f2fs 4002 - hddimg 4003 - iso 4004 - jffs2 4005 - jffs2.sum 4006 - multiubi 4007 - squashfs 4008 - squashfs-lz4 4009 - squashfs-lzo 4010 - squashfs-xz 4011 - tar 4012 - tar.bz2 4013 - tar.gz 4014 - tar.lz4 4015 - tar.xz 4016 - tar.zst 4017 - ubi 4018 - ubifs 4019 - wic 4020 - wic.bz2 4021 - wic.gz 4022 - wic.lzma 4023 - wic.zst 4024 4025 For more information about these types of images, see 4026 ``meta/classes-recipe/image_types*.bbclass`` in the :term:`Source Directory`. 4027 4028 :term:`IMAGE_VERSION_SUFFIX` 4029 Version suffix that is part of the default :term:`IMAGE_NAME` and 4030 :term:`KERNEL_ARTIFACT_NAME` values. 4031 Defaults to ``"-${DATETIME}"``, however you could set this to a 4032 version string that comes from your external build environment if 4033 desired, and this suffix would then be used consistently across 4034 the build artifacts. 4035 4036 :term:`IMGDEPLOYDIR` 4037 When inheriting the :ref:`ref-classes-image` class directly or 4038 through the :ref:`ref-classes-core-image` class, the 4039 :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files 4040 that is set in the ``image`` class as follows:: 4041 4042 IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete" 4043 4044 Recipes inheriting the :ref:`ref-classes-image` class should copy 4045 files to be deployed into :term:`IMGDEPLOYDIR`, and the class will take 4046 care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards. 4047 4048 :term:`IMGMANIFESTDIR` 4049 When inheriting the :ref:`ref-classes-image` class directly or through the 4050 :ref:`ref-classes-core-image` class, the :term:`IMGMANIFESTDIR` setting 4051 points to a temporary area that stores manifest ``json`` files, that list 4052 what images were created by various images creation tasks (as defined by 4053 the :term:`IMAGE_FSTYPES` variable). It is set in the 4054 :ref:`ref-classes-image` class as follows:: 4055 4056 IMGMANIFESTDIR = "${WORKDIR}/image-task-manifest" 4057 4058 :term:`INCOMPATIBLE_LICENSE` 4059 Specifies a space-separated list of license names (as they would 4060 appear in :term:`LICENSE`) that should be excluded 4061 from the build (if set globally), or from an image (if set locally 4062 in an image recipe). 4063 4064 When the variable is set globally, recipes that provide no alternatives to listed 4065 incompatible licenses are not built. Packages that are individually 4066 licensed with the specified incompatible licenses will be deleted. 4067 Most of the time this does not allow a feasible build (because it becomes impossible 4068 to satisfy build time dependencies), so the recommended way to 4069 implement license restrictions is to set the variable in specific 4070 image recipes where the restrictions must apply. That way there 4071 are no build time restrictions, but the license check is still 4072 performed when the image's filesystem is assembled from packages. 4073 4074 There is some support for wildcards in this variable's value, 4075 however it is restricted to specific licenses. Currently only 4076 these wildcards are allowed and expand as follows: 4077 4078 - ``AGPL-3.0*"``: ``AGPL-3.0-only``, ``AGPL-3.0-or-later`` 4079 - ``GPL-3.0*``: ``GPL-3.0-only``, ``GPL-3.0-or-later`` 4080 - ``LGPL-3.0*``: ``LGPL-3.0-only``, ``LGPL-3.0-or-later`` 4081 4082 .. note:: 4083 4084 This functionality is only regularly tested using the following 4085 setting:: 4086 4087 INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*" 4088 4089 4090 Although you can use other settings, you might be required to 4091 remove dependencies on (or provide alternatives to) components that 4092 are required to produce a functional system image. 4093 4094 :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS` 4095 Specifies a space-separated list of package and license pairs that 4096 are allowed to be used even if the license is specified in 4097 :term:`INCOMPATIBLE_LICENSE`. The package and license pairs are 4098 separated using a colon. Example:: 4099 4100 INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only" 4101 4102 :term:`INHERIT` 4103 Causes the named class or classes to be inherited globally. Anonymous 4104 functions in the class or classes are not executed for the base 4105 configuration and in each individual recipe. The OpenEmbedded build 4106 system ignores changes to :term:`INHERIT` in individual recipes. 4107 Classes inherited using :term:`INHERIT` must be located in the 4108 ``classes-global/`` or ``classes/`` subdirectories. 4109 4110 For more information on :term:`INHERIT`, see the 4111 :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" 4112 section in the BitBake User Manual. 4113 4114 :term:`INHERIT_DISTRO` 4115 Lists classes that will be inherited at the distribution level. It is 4116 unlikely that you want to edit this variable. 4117 4118 Classes specified in :term:`INHERIT_DISTRO` must be located in the 4119 ``classes-global/`` or ``classes/`` subdirectories. 4120 4121 The default value of the variable is set as follows in the 4122 ``meta/conf/distro/defaultsetup.conf`` file:: 4123 4124 INHERIT_DISTRO ?= "debian devshell sstate license remove-libtool create-spdx" 4125 4126 :term:`INHIBIT_DEFAULT_DEPS` 4127 Prevents the default dependencies, namely the C compiler and standard 4128 C library (libc), from being added to :term:`DEPENDS`. 4129 This variable is usually used within recipes that do not require any 4130 compilation using the C compiler. 4131 4132 Set the variable to "1" to prevent the default dependencies from 4133 being added. 4134 4135 :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` 4136 Prevents the OpenEmbedded build system from splitting out debug 4137 information during packaging. By default, the build system splits out 4138 debugging information during the 4139 :ref:`ref-tasks-package` task. For more information on 4140 how debug information is split out, see the 4141 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 4142 variable. 4143 4144 To prevent the build system from splitting out debug information 4145 during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as 4146 follows:: 4147 4148 INHIBIT_PACKAGE_DEBUG_SPLIT = "1" 4149 4150 :term:`INHIBIT_PACKAGE_STRIP` 4151 If set to "1", causes the build to not strip binaries in resulting 4152 packages and prevents the ``-dbg`` package from containing the source 4153 files. 4154 4155 By default, the OpenEmbedded build system strips binaries and puts 4156 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. 4157 Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you 4158 plan to debug in general. 4159 4160 :term:`INHIBIT_SYSROOT_STRIP` 4161 If set to "1", causes the build to not strip binaries in the 4162 resulting sysroot. 4163 4164 By default, the OpenEmbedded build system strips binaries in the 4165 resulting sysroot. When you specifically set the 4166 :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit 4167 this stripping. 4168 4169 If you want to use this variable, include the :ref:`ref-classes-staging` 4170 class. This class uses a ``sys_strip()`` function to test for the variable 4171 and acts accordingly. 4172 4173 .. note:: 4174 4175 Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and 4176 special circumstances. For example, suppose you are building 4177 bare-metal firmware by using an external GCC toolchain. Furthermore, 4178 even if the toolchain's binaries are strippable, there are other files 4179 needed for the build that are not strippable. 4180 4181 :term:`INIT_MANAGER` 4182 Specifies the system init manager to use. Available options are: 4183 4184 - ``sysvinit`` 4185 - ``systemd`` 4186 - ``mdev-busybox`` 4187 4188 With ``sysvinit``, the init manager is set to 4189 :wikipedia:`SysVinit <Init#SysV-style>`, the traditional UNIX init 4190 system. This is the default choice in the Poky distribution, together with 4191 the Udev device manager (see the ":ref:`device-manager`" section). 4192 4193 With ``systemd``, the init manager becomes :wikipedia:`systemd <Systemd>`, 4194 which comes with the :wikipedia:`udev <Udev>` device manager. 4195 4196 With ``mdev-busybox``, the init manager becomes the much simpler BusyBox 4197 init, together with the BusyBox mdev device manager. This is the simplest 4198 and lightest solution, and probably the best choice for low-end systems 4199 with a rather slow CPU and a limited amount of RAM. 4200 4201 More concretely, this is used to include 4202 ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global 4203 configuration. You can have a look at the 4204 :yocto_git:`meta/conf/distro/include/init-manager-*.inc </poky/tree/meta/conf/distro/include>` 4205 files for more information, and also the ":ref:`init-manager`" 4206 section in the Yocto Project Development Tasks Manual. 4207 4208 :term:`INITRAMFS_DEPLOY_DIR_IMAGE` 4209 Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs` 4210 where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is 4211 set by default to ``${DEPLOY_DIR_IMAGE}`` in the 4212 :ref:`ref-classes-kernel` class and it's only meant to be changed when 4213 building an :term:`Initramfs` image from a separate multiconfig via 4214 :term:`INITRAMFS_MULTICONFIG`. 4215 4216 :term:`INITRAMFS_FSTYPES` 4217 Defines the format for the output image of an initial RAM filesystem 4218 (:term:`Initramfs`), which is used during boot. Supported formats are the 4219 same as those supported by the 4220 :term:`IMAGE_FSTYPES` variable. 4221 4222 The default value of this variable, which is set in the 4223 ``meta/conf/bitbake.conf`` configuration file in the 4224 :term:`Source Directory`, is "cpio.gz". The Linux kernel's 4225 :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem 4226 :wikipedia:`initrd <Initrd>` mechanism, expects 4227 an optionally compressed cpio archive. 4228 4229 :term:`INITRAMFS_IMAGE` 4230 Specifies the :term:`PROVIDES` name of an image 4231 recipe that is used to build an initial RAM filesystem (:term:`Initramfs`) 4232 image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an 4233 additional recipe to be built as a dependency to whatever root 4234 filesystem recipe you might be using (e.g. ``core-image-sato``). The 4235 :term:`Initramfs` image recipe you provide should set 4236 :term:`IMAGE_FSTYPES` to 4237 :term:`INITRAMFS_FSTYPES`. 4238 4239 An :term:`Initramfs` image provides a temporary root filesystem used for 4240 early system initialization (e.g. loading of modules needed to locate 4241 and mount the "real" root filesystem). 4242 4243 .. note:: 4244 4245 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` 4246 recipe in the :term:`Source Directory` 4247 for an example :term:`Initramfs` recipe. To select this sample recipe as 4248 the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE` 4249 to "core-image-minimal-initramfs". 4250 4251 You can also find more information by referencing the 4252 ``meta-poky/conf/templates/default/local.conf.sample.extended`` 4253 configuration file in the Source Directory, the :ref:`ref-classes-image` 4254 class, and the :ref:`ref-classes-kernel` class to see how to use the 4255 :term:`INITRAMFS_IMAGE` variable. 4256 4257 If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no 4258 :term:`Initramfs` image is built. 4259 4260 For more information, you can also see the 4261 :term:`INITRAMFS_IMAGE_BUNDLE` 4262 variable, which allows the generated image to be bundled inside the 4263 kernel image. Additionally, for information on creating an :term:`Initramfs` 4264 image, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 4265 in the Yocto Project Development Tasks Manual. 4266 4267 :term:`INITRAMFS_IMAGE_BUNDLE` 4268 Controls whether or not the image recipe specified by 4269 :term:`INITRAMFS_IMAGE` is run through an 4270 extra pass 4271 (:ref:`ref-tasks-bundle_initramfs`) during 4272 kernel compilation in order to build a single binary that contains 4273 both the kernel image and the initial RAM filesystem (:term:`Initramfs`) 4274 image. This makes use of the 4275 :term:`CONFIG_INITRAMFS_SOURCE` kernel 4276 feature. 4277 4278 .. note:: 4279 4280 Bundling the :term:`Initramfs` with the kernel conflates the code in the 4281 :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 4282 compatible software may be part of a bundled :term:`Initramfs`. 4283 4284 .. note:: 4285 4286 Using an extra compilation pass to bundle the :term:`Initramfs` avoids a 4287 circular dependency between the kernel recipe and the :term:`Initramfs` 4288 recipe should the :term:`Initramfs` include kernel modules. Should that be 4289 the case, the :term:`Initramfs` recipe depends on the kernel for the 4290 kernel modules, and the kernel depends on the :term:`Initramfs` recipe 4291 since the :term:`Initramfs` is bundled inside the kernel image. 4292 4293 The combined binary is deposited into the ``tmp/deploy`` directory, 4294 which is part of the :term:`Build Directory`. 4295 4296 Setting the variable to "1" in a configuration file causes the 4297 OpenEmbedded build system to generate a kernel image with the 4298 :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within:: 4299 4300 INITRAMFS_IMAGE_BUNDLE = "1" 4301 4302 By default, the :ref:`ref-classes-kernel` class sets this variable to a 4303 null string as follows:: 4304 4305 INITRAMFS_IMAGE_BUNDLE ?= "" 4306 4307 .. note:: 4308 4309 You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a 4310 configuration file. You cannot set the variable in a recipe file. 4311 4312 See the 4313 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>` 4314 file for additional information. Also, for information on creating an 4315 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 4316 in the Yocto Project Development Tasks Manual. 4317 4318 :term:`INITRAMFS_IMAGE_NAME` 4319 4320 This value needs to stay in sync with :term:`IMAGE_LINK_NAME`, but with 4321 :term:`INITRAMFS_IMAGE` instead of :term:`IMAGE_BASENAME`. The default value 4322 is set as follows: 4323 4324 INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}" 4325 4326 That is, if :term:`INITRAMFS_IMAGE` is set, the value of 4327 :term:`INITRAMFS_IMAGE_NAME` will be set based upon 4328 :term:`INITRAMFS_IMAGE` and :term:`IMAGE_MACHINE_SUFFIX`. 4329 4330 4331 :term:`INITRAMFS_LINK_NAME` 4332 The link name of the initial RAM filesystem image. This variable is 4333 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4334 follows:: 4335 4336 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" 4337 4338 The value of the 4339 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4340 file, has the following value:: 4341 4342 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4343 4344 See the :term:`MACHINE` variable for additional 4345 information. 4346 4347 :term:`INITRAMFS_MULTICONFIG` 4348 Defines the multiconfig to create a multiconfig dependency to be used by 4349 the :ref:`ref-classes-kernel` class. 4350 4351 This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from 4352 a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`. 4353 4354 For more information on how to bundle an :term:`Initramfs` image from a separate 4355 multiconfig see the ":ref:`dev-manual/building:Bundling an Initramfs Image From a Separate Multiconfig`" 4356 section in the Yocto Project Development Tasks Manual. 4357 4358 :term:`INITRAMFS_NAME` 4359 The base name of the initial RAM filesystem image. This variable is 4360 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4361 follows:: 4362 4363 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" 4364 4365 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4366 4367 :term:`INITRD` 4368 Indicates list of filesystem images to concatenate and use as an 4369 initial RAM disk (``initrd``). 4370 4371 The :term:`INITRD` variable is an optional variable used with the 4372 :ref:`ref-classes-image-live` class. 4373 4374 :term:`INITRD_IMAGE` 4375 When building a "live" bootable image (i.e. when 4376 :term:`IMAGE_FSTYPES` contains "live"), 4377 :term:`INITRD_IMAGE` specifies the image recipe that should be built to 4378 provide the initial RAM disk image. The default value is 4379 "core-image-minimal-initramfs". 4380 4381 See the :ref:`ref-classes-image-live` class for more information. 4382 4383 :term:`INITSCRIPT_NAME` 4384 The filename of the initialization script as installed to 4385 ``${sysconfdir}/init.d``. 4386 4387 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. 4388 The variable is mandatory. 4389 4390 :term:`INITSCRIPT_PACKAGES` 4391 A list of the packages that contain initscripts. If multiple packages 4392 are specified, you need to append the package name to the other 4393 ``INITSCRIPT_*`` as an override. 4394 4395 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. 4396 The variable is optional and defaults to the :term:`PN` 4397 variable. 4398 4399 :term:`INITSCRIPT_PARAMS` 4400 Specifies the options to pass to ``update-rc.d``. Here is an example:: 4401 4402 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." 4403 4404 In this example, the script has a runlevel of 99, starts the script 4405 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. 4406 4407 The variable's default value is "defaults", which is set in the 4408 :ref:`ref-classes-update-rc.d` class. 4409 4410 The value in :term:`INITSCRIPT_PARAMS` is passed through to the 4411 ``update-rc.d`` command. For more information on valid parameters, 4412 please see the ``update-rc.d`` manual page at 4413 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html 4414 4415 :term:`INSANE_SKIP` 4416 Specifies the QA checks to skip for a specific package within a 4417 recipe. For example, to skip the check for symbolic link ``.so`` 4418 files in the main package of a recipe, add the following to the 4419 recipe. The package name override must be used, which in this example 4420 is ``${PN}``:: 4421 4422 INSANE_SKIP:${PN} += "dev-so" 4423 4424 See the ":ref:`ref-classes-insane`" section for a 4425 list of the valid QA checks you can specify using this variable. 4426 4427 :term:`INSTALL_TIMEZONE_FILE` 4428 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. 4429 Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the 4430 configuration level to disable this behavior. 4431 4432 :term:`IPK_FEED_URIS` 4433 When the IPK backend is in use and package management is enabled on 4434 the target, you can use this variable to set up ``opkg`` in the 4435 target image to point to package feeds on a nominated server. Once 4436 the feed is established, you can perform installations or upgrades 4437 using the package manager at runtime. 4438 4439 :term:`KARCH` 4440 Defines the kernel architecture used when assembling the 4441 configuration. Architectures supported for this release are: 4442 4443 - powerpc 4444 - i386 4445 - x86_64 4446 - arm 4447 - qemu 4448 - mips 4449 4450 You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. 4451 4452 :term:`KBRANCH` 4453 A regular expression used by the build process to explicitly identify 4454 the kernel branch that is validated, patched, and configured during a 4455 build. You must set this variable to ensure the exact kernel branch 4456 you want is being used by the build process. 4457 4458 Values for this variable are set in the kernel's recipe file and the 4459 kernel's append file. For example, if you are using the 4460 ``linux-yocto_4.12`` kernel, the kernel recipe file is the 4461 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH` 4462 is set as follows in that kernel recipe file:: 4463 4464 KBRANCH ?= "standard/base" 4465 4466 This variable is also used from the kernel's append file to identify 4467 the kernel branch specific to a particular machine or target 4468 hardware. Continuing with the previous kernel example, the kernel's 4469 append file is located in the 4470 BSP layer for a given machine. For example, the append file for the 4471 Beaglebone and generic versions of both 32 and 64-bit IA 4472 machines (``meta-yocto-bsp``) is named 4473 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend``. 4474 Here are the related statements from that append file:: 4475 4476 KBRANCH:genericx86 = "v6.1/standard/base" 4477 KBRANCH:genericx86-64 = "v6.1/standard/base" 4478 KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" 4479 4480 The :term:`KBRANCH` statements 4481 identify the kernel branch to use when building for each supported 4482 BSP. 4483 4484 :term:`KBUILD_DEFCONFIG` 4485 When used with the :ref:`ref-classes-kernel-yocto` 4486 class, specifies an "in-tree" kernel configuration file for use 4487 during a kernel build. 4488 4489 Typically, when using a ``defconfig`` to configure a kernel during a 4490 build, you place the file in your layer in the same manner as you 4491 would place patch files and configuration fragment files (i.e. 4492 "out-of-tree"). However, if you want to use a ``defconfig`` file that 4493 is part of the kernel tree (i.e. "in-tree"), you can use the 4494 :term:`KBUILD_DEFCONFIG` variable and append the 4495 :term:`KMACHINE` variable to point to the 4496 ``defconfig`` file. 4497 4498 To use the variable, set it in the append file for your kernel recipe 4499 using the following form:: 4500 4501 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file" 4502 4503 Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses 4504 a ``defconfig`` file named "bcm2709_defconfig":: 4505 4506 KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig" 4507 4508 As an alternative, you can use the following within your append file:: 4509 4510 KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file" 4511 4512 For more 4513 information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the 4514 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" 4515 section in the Yocto Project Linux Kernel Development Manual. 4516 4517 :term:`KCONFIG_MODE` 4518 When used with the :ref:`ref-classes-kernel-yocto` 4519 class, specifies the kernel configuration values to use for options 4520 not specified in the provided ``defconfig`` file. Valid options are:: 4521 4522 KCONFIG_MODE = "alldefconfig" 4523 KCONFIG_MODE = "allnoconfig" 4524 4525 In ``alldefconfig`` mode the options not explicitly specified will be 4526 assigned their Kconfig default value. In ``allnoconfig`` mode the 4527 options not explicitly specified will be disabled in the kernel 4528 config. 4529 4530 In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where 4531 the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file 4532 will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed 4533 in ``${WORKDIR}`` through a meta-layer will be handled in 4534 ``allnoconfig`` mode. 4535 4536 An "in-tree" ``defconfig`` file can be selected via the 4537 :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to 4538 be explicitly set. 4539 4540 A ``defconfig`` file compatible with ``allnoconfig`` mode can be 4541 generated by copying the ``.config`` file from a working Linux kernel 4542 build, renaming it to ``defconfig`` and placing it into the Linux 4543 kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does 4544 not need to be explicitly set. 4545 4546 A ``defconfig`` file compatible with ``alldefconfig`` mode can be 4547 generated using the 4548 :ref:`ref-tasks-savedefconfig` 4549 task and placed into the Linux kernel ``${WORKDIR}`` through your 4550 meta-layer. Explicitely set :term:`KCONFIG_MODE`:: 4551 4552 KCONFIG_MODE = "alldefconfig" 4553 4554 :term:`KERNEL_ALT_IMAGETYPE` 4555 Specifies an alternate kernel image type for creation in addition to 4556 the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and 4557 :term:`KERNEL_IMAGETYPES` variables. 4558 4559 :term:`KERNEL_ARTIFACT_NAME` 4560 Specifies the name of all of the build artifacts. You can change the 4561 name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME` 4562 variable. 4563 4564 The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the 4565 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the 4566 following default value:: 4567 4568 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" 4569 4570 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`IMAGE_MACHINE_SUFFIX` 4571 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information. 4572 4573 :term:`KERNEL_CLASSES` 4574 A list of classes defining kernel image types that the 4575 :ref:`ref-classes-kernel` class should inherit. You typically 4576 append this variable to enable extended image types. An example is 4577 ":ref:`ref-classes-kernel-fitimage`", which enables 4578 FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``. 4579 You can register custom kernel image types with the 4580 :ref:`ref-classes-kernel` class using this variable. 4581 4582 :term:`KERNEL_DANGLING_FEATURES_WARN_ONLY` 4583 When kernel configuration fragments are missing for some 4584 :term:`KERNEL_FEATURES` specified by layers or BSPs, 4585 building and configuring the kernel stops with an error. 4586 4587 You can turn these errors into warnings by setting the 4588 following in ``conf/local.conf``:: 4589 4590 KERNEL_DANGLING_FEATURES_WARN_ONLY = "1" 4591 4592 You will still be warned that runtime issues may occur, 4593 but at least the kernel configuration and build process will 4594 be allowed to continue. 4595 4596 :term:`KERNEL_DEBUG_TIMESTAMPS` 4597 If set to "1", enables timestamping functionality during building 4598 the kernel. The default is "0" to disable this for reproducibility 4599 reasons. 4600 4601 :term:`KERNEL_DEPLOY_DEPEND` 4602 Provides a means of controlling the dependency of an image recipe 4603 on the kernel. The default value is "virtual/kernel:do_deploy", 4604 however for a small initramfs image or other images that do not 4605 need the kernel, this can be set to "" in the image recipe. 4606 4607 :term:`KERNEL_DEVICETREE` 4608 Specifies the name of the generated Linux kernel device tree (i.e. 4609 the ``.dtb``) file. 4610 4611 .. note:: 4612 4613 There is legacy support for specifying the full path to the device 4614 tree. However, providing just the ``.dtb`` file is preferred. 4615 4616 In order to use this variable, the :ref:`ref-classes-kernel-devicetree` 4617 class must be inherited. 4618 4619 :term:`KERNEL_DEVICETREE_BUNDLE` 4620 When set to "1", this variable allows to bundle the Linux kernel 4621 and the Device Tree Binary together in a single file. 4622 4623 This feature is currently only supported on the "arm" (32 bit) 4624 architecture. 4625 4626 This variable is set to "0" by default by the 4627 :ref:`ref-classes-kernel-devicetree` class. 4628 4629 :term:`KERNEL_DTB_LINK_NAME` 4630 The link name of the kernel device tree binary (DTB). This variable 4631 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4632 follows:: 4633 4634 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4635 4636 The 4637 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in 4638 the same file, has the following value:: 4639 4640 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4641 4642 See the :term:`MACHINE` variable for additional 4643 information. 4644 4645 :term:`KERNEL_DTB_NAME` 4646 The base name of the kernel device tree binary (DTB). This variable 4647 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as 4648 follows:: 4649 4650 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4651 4652 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4653 4654 :term:`KERNEL_DTBDEST` 4655 This variable, used by the :ref:`ref-classes-kernel-devicetree` 4656 class, allows to change the installation directory of the DTB 4657 (Device Tree Binary) files. 4658 4659 It is set by default to "${KERNEL_IMAGEDEST}" by the 4660 :ref:`ref-classes-kernel` class. 4661 4662 :term:`KERNEL_DTBVENDORED` 4663 This variable, used by the :ref:`ref-classes-kernel-devicetree`, 4664 allows to ignore vendor subdirectories when installing DTB 4665 (Device Tree Binary) files, when it is set to "false". 4666 4667 To keep vendor subdirectories, set this variable to "true". 4668 4669 It is set by default to "false" by the :ref:`ref-classes-kernel` class. 4670 4671 :term:`KERNEL_DTC_FLAGS` 4672 Specifies the ``dtc`` flags that are passed to the Linux kernel build 4673 system when generating the device trees (via ``DTC_FLAGS`` environment 4674 variable). 4675 4676 In order to use this variable, the :ref:`ref-classes-kernel-devicetree` 4677 class must be inherited. 4678 4679 :term:`KERNEL_EXTRA_ARGS` 4680 Specifies additional ``make`` command-line arguments the OpenEmbedded 4681 build system passes on when compiling the kernel. 4682 4683 :term:`KERNEL_FEATURES` 4684 Includes additional kernel metadata. In the OpenEmbedded build 4685 system, the default Board Support Packages (BSPs) 4686 :term:`Metadata` is provided through the 4687 :term:`KMACHINE` and :term:`KBRANCH` 4688 variables. You can use the :term:`KERNEL_FEATURES` variable from within 4689 the kernel recipe or kernel append file to further add metadata for 4690 all BSPs or specific BSPs. 4691 4692 The metadata you add through this variable includes config fragments 4693 and features descriptions, which usually includes patches as well as 4694 config fragments. You typically override the :term:`KERNEL_FEATURES` 4695 variable for a specific machine. In this way, you can provide 4696 validated, but optional, sets of kernel configurations and features. 4697 4698 For example, the following example from the ``linux-yocto-rt_4.12`` 4699 kernel recipe adds "netfilter" and "taskstats" features to all BSPs 4700 as well as "virtio" configurations to all QEMU machines. The last two 4701 statements add specific configurations to targeted machine types:: 4702 4703 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" 4704 KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" 4705 KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc" 4706 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" 4707 KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc" 4708 4709 :term:`KERNEL_FIT_LINK_NAME` 4710 The link name of the kernel flattened image tree (FIT) image. This 4711 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` 4712 file as follows:: 4713 4714 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4715 4716 The value of the 4717 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4718 file, has the following value:: 4719 4720 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4721 4722 See the :term:`MACHINE` variable for additional 4723 information. 4724 4725 :term:`KERNEL_FIT_NAME` 4726 The base name of the kernel flattened image tree (FIT) image. This 4727 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` 4728 file as follows:: 4729 4730 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4731 4732 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4733 4734 :term:`KERNEL_IMAGE_LINK_NAME` 4735 The link name for the kernel image. This variable is set in the 4736 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 4737 4738 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4739 4740 The value of 4741 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4742 file, has the following value:: 4743 4744 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4745 4746 See the :term:`MACHINE` variable for additional 4747 information. 4748 4749 :term:`KERNEL_IMAGE_MAXSIZE` 4750 Specifies the maximum size of the kernel image file in kilobytes. If 4751 :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is 4752 checked against the set value during the 4753 :ref:`ref-tasks-sizecheck` task. The task fails if 4754 the kernel image file is larger than the setting. 4755 4756 :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a 4757 limited amount of space in which the kernel image must be stored. 4758 4759 By default, this variable is not set, which means the size of the 4760 kernel image is not checked. 4761 4762 :term:`KERNEL_IMAGE_NAME` 4763 The base name of the kernel image. This variable is set in the 4764 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 4765 4766 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4767 4768 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 4769 4770 :term:`KERNEL_IMAGETYPE` 4771 The type of kernel to build for a device, usually set by the machine 4772 configuration files and defaults to "zImage". This variable is used 4773 when building the kernel and is passed to ``make`` as the target to 4774 build. 4775 4776 To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`. 4777 4778 :term:`KERNEL_IMAGETYPES` 4779 Lists additional types of kernel images to build for a device in addition 4780 to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the 4781 machine configuration files. 4782 4783 :term:`KERNEL_MODULE_AUTOLOAD` 4784 Lists kernel modules that need to be auto-loaded during boot. 4785 4786 .. note:: 4787 4788 This variable replaces the deprecated :term:`module_autoload` 4789 variable. 4790 4791 You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it 4792 can be recognized by the kernel recipe or by an out-of-tree kernel 4793 module recipe (e.g. a machine configuration file, a distribution 4794 configuration file, an append file for the recipe, or the recipe 4795 itself). 4796 4797 Specify it as follows:: 4798 4799 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" 4800 4801 Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build 4802 system to populate the ``/etc/modules-load.d/modname.conf`` file with 4803 the list of modules to be auto-loaded on boot. The modules appear 4804 one-per-line in the file. Here is an example of the most common use 4805 case:: 4806 4807 KERNEL_MODULE_AUTOLOAD += "module_name" 4808 4809 For information on how to populate the ``modname.conf`` file with 4810 ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable. 4811 4812 :term:`KERNEL_MODULE_PROBECONF` 4813 Provides a list of modules for which the OpenEmbedded build system 4814 expects to find ``module_conf_``\ modname values that specify 4815 configuration for each of the modules. For information on how to 4816 provide those module configurations, see the 4817 :term:`module_conf_* <module_conf>` variable. 4818 4819 :term:`KERNEL_PACKAGE_NAME` 4820 Specifies the base name of the kernel packages, such as "kernel" 4821 in the kernel packages such as "kernel-modules", "kernel-image" and 4822 "kernel-dbg". 4823 4824 The default value for this variable is set to "kernel" by the 4825 :ref:`ref-classes-kernel` class. 4826 4827 :term:`KERNEL_PATH` 4828 The location of the kernel sources. This variable is set to the value 4829 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` 4830 class. For information on how this variable is used, see the 4831 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4832 section in the Yocto Project Linux Kernel Development Manual. 4833 4834 To help maximize compatibility with out-of-tree drivers used to build 4835 modules, the OpenEmbedded build system also recognizes and uses the 4836 :term:`KERNEL_SRC` variable, which is identical to 4837 the :term:`KERNEL_PATH` variable. Both variables are common variables 4838 used by external Makefiles to point to the kernel source directory. 4839 4840 :term:`KERNEL_SRC` 4841 The location of the kernel sources. This variable is set to the value 4842 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` 4843 class. For information on how this variable is used, see the 4844 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4845 section in the Yocto Project Linux Kernel Development Manual. 4846 4847 To help maximize compatibility with out-of-tree drivers used to build 4848 modules, the OpenEmbedded build system also recognizes and uses the 4849 :term:`KERNEL_PATH` variable, which is identical 4850 to the :term:`KERNEL_SRC` variable. Both variables are common variables 4851 used by external Makefiles to point to the kernel source directory. 4852 4853 :term:`KERNEL_STRIP` 4854 Allows to specific which ``strip`` command to use to strip the kernel 4855 binary, typically either GNU binutils ``strip`` or ``llvm-strip``. 4856 4857 :term:`KERNEL_VERSION` 4858 Specifies the version of the kernel as extracted from ``version.h`` 4859 or ``utsrelease.h`` within the kernel sources. Effects of setting 4860 this variable do not take effect until the kernel has been 4861 configured. Consequently, attempting to refer to this variable in 4862 contexts prior to configuration will not work. 4863 4864 :term:`KERNELDEPMODDEPEND` 4865 Specifies whether the data referenced through 4866 :term:`PKGDATA_DIR` is needed or not. 4867 :term:`KERNELDEPMODDEPEND` does not control whether or not that data 4868 exists, but simply whether or not it is used. If you do not need to 4869 use the data, set the :term:`KERNELDEPMODDEPEND` variable in your 4870 :term:`Initramfs` recipe. Setting the variable there when the data is not 4871 needed avoids a potential dependency loop. 4872 4873 :term:`KFEATURE_DESCRIPTION` 4874 Provides a short description of a configuration fragment. You use 4875 this variable in the ``.scc`` file that describes a configuration 4876 fragment file. Here is the variable used in a file named ``smp.scc`` 4877 to describe SMP being enabled:: 4878 4879 define KFEATURE_DESCRIPTION "Enable SMP" 4880 4881 :term:`KMACHINE` 4882 The machine as known by the kernel. Sometimes the machine name used 4883 by the kernel does not match the machine name used by the 4884 OpenEmbedded build system. For example, the machine name that the 4885 OpenEmbedded build system understands as ``core2-32-intel-common`` 4886 goes by a different name in the Linux Yocto kernel. The kernel 4887 understands that machine as ``intel-core2-32``. For cases like these, 4888 the :term:`KMACHINE` variable maps the kernel machine name to the 4889 OpenEmbedded build system machine name. 4890 4891 These mappings between different names occur in the Yocto Linux 4892 Kernel's ``meta`` branch. As an example take a look in the 4893 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:: 4894 4895 LINUX_VERSION:core2-32-intel-common = "3.19.0" 4896 COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}" 4897 SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" 4898 SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" 4899 KMACHINE:core2-32-intel-common = "intel-core2-32" 4900 KBRANCH:core2-32-intel-common = "standard/base" 4901 KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}" 4902 4903 The :term:`KMACHINE` statement says 4904 that the kernel understands the machine name as "intel-core2-32". 4905 However, the OpenEmbedded build system understands the machine as 4906 "core2-32-intel-common". 4907 4908 :term:`KTYPE` 4909 Defines the kernel type to be used in assembling the configuration. 4910 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 4911 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" 4912 section in the 4913 Yocto Project Linux Kernel Development Manual for more information on 4914 kernel types. 4915 4916 You define the :term:`KTYPE` variable in the 4917 :ref:`kernel-dev/advanced:bsp descriptions`. The 4918 value you use must match the value used for the 4919 :term:`LINUX_KERNEL_TYPE` value used by the 4920 kernel recipe. 4921 4922 :term:`LABELS` 4923 Provides a list of targets for automatic configuration. 4924 4925 See the :ref:`ref-classes-grub-efi` class for more 4926 information on how this variable is used. 4927 4928 :term:`LAYERDEPENDS` 4929 Lists the layers, separated by spaces, on which this recipe depends. 4930 Optionally, you can specify a specific layer version for a dependency 4931 by adding it to the end of the layer name. Here is an example:: 4932 4933 LAYERDEPENDS_mylayer = "anotherlayer (=3)" 4934 4935 In this previous example, 4936 version 3 of "anotherlayer" is compared against 4937 :term:`LAYERVERSION`\ ``_anotherlayer``. 4938 4939 An error is produced if any dependency is missing or the version 4940 numbers (if specified) do not match exactly. This variable is used in 4941 the ``conf/layer.conf`` file and must be suffixed with the name of 4942 the specific layer (e.g. ``LAYERDEPENDS_mylayer``). 4943 4944 :term:`LAYERDIR` 4945 When used inside the ``layer.conf`` configuration file, this variable 4946 provides the path of the current layer. This variable is not 4947 available outside of ``layer.conf`` and references are expanded 4948 immediately when parsing of the file completes. 4949 4950 :term:`LAYERDIR_RE` 4951 See :term:`bitbake:LAYERDIR_RE` in the BitBake manual. 4952 4953 :term:`LAYERRECOMMENDS` 4954 Lists the layers, separated by spaces, recommended for use with this 4955 layer. 4956 4957 Optionally, you can specify a specific layer version for a 4958 recommendation by adding the version to the end of the layer name. 4959 Here is an example:: 4960 4961 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" 4962 4963 In this previous example, version 3 of "anotherlayer" is compared 4964 against ``LAYERVERSION_anotherlayer``. 4965 4966 This variable is used in the ``conf/layer.conf`` file and must be 4967 suffixed with the name of the specific layer (e.g. 4968 ``LAYERRECOMMENDS_mylayer``). 4969 4970 :term:`LAYERSERIES_COMPAT` 4971 See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual. 4972 4973 :term:`LAYERVERSION` 4974 Optionally specifies the version of a layer as a single number. You 4975 can use this within :term:`LAYERDEPENDS` for 4976 another layer in order to depend on a specific version of the layer. 4977 This variable is used in the ``conf/layer.conf`` file and must be 4978 suffixed with the name of the specific layer (e.g. 4979 ``LAYERVERSION_mylayer``). 4980 4981 :term:`LD` 4982 The minimal command and arguments used to run the linker. 4983 4984 :term:`LDFLAGS` 4985 Specifies the flags to pass to the linker. This variable is exported 4986 to an environment variable and thus made visible to the software 4987 being built during the compilation step. 4988 4989 Default initialization for :term:`LDFLAGS` varies depending on what is 4990 being built: 4991 4992 - :term:`TARGET_LDFLAGS` when building for the 4993 target 4994 4995 - :term:`BUILD_LDFLAGS` when building for the 4996 build host (i.e. ``-native``) 4997 4998 - :term:`BUILDSDK_LDFLAGS` when building for 4999 an SDK (i.e. ``nativesdk-``) 5000 5001 :term:`LEAD_SONAME` 5002 Specifies the lead (or primary) compiled library file (i.e. ``.so``) 5003 that the :ref:`ref-classes-debian` class applies its 5004 naming policy to given a recipe that packages multiple libraries. 5005 5006 This variable works in conjunction with the :ref:`ref-classes-debian` 5007 class. 5008 5009 :term:`LIC_FILES_CHKSUM` 5010 Checksums of the license text in the recipe source code. 5011 5012 This variable tracks changes in license text of the source code 5013 files. If the license text is changed, it will trigger a build 5014 failure, which gives the developer an opportunity to review any 5015 license change. 5016 5017 This variable must be defined for all recipes (unless 5018 :term:`LICENSE` is set to "CLOSED"). 5019 5020 For more information, see the ":ref:`dev-manual/licenses:tracking license changes`" 5021 section in the Yocto Project Development Tasks Manual. 5022 5023 :term:`LICENSE` 5024 The list of source licenses for the recipe. Follow these rules: 5025 5026 - Do not use spaces within individual license names. 5027 5028 - Separate license names using \| (pipe) when there is a choice 5029 between licenses. 5030 5031 - Separate license names using & (ampersand) when there are 5032 multiple licenses for different parts of the source. 5033 5034 - You can use spaces between license names. 5035 5036 - For standard licenses, use the names of the files in 5037 ``meta/files/common-licenses/`` or the 5038 :term:`SPDXLICENSEMAP` flag names defined in 5039 ``meta/conf/licenses.conf``. 5040 5041 Here are some examples:: 5042 5043 LICENSE = "LGPL-2.1-only | GPL-3.0-only" 5044 LICENSE = "MPL-1.0 & LGPL-2.1-only" 5045 LICENSE = "GPL-2.0-or-later" 5046 5047 The first example is from the 5048 recipes for Qt, which the user may choose to distribute under either 5049 the LGPL version 2.1 or GPL version 3. The second example is from 5050 Cairo where two licenses cover different parts of the source code. 5051 The final example is from ``sysstat``, which presents a single 5052 license. 5053 5054 You can also specify licenses on a per-package basis to handle 5055 situations where components of the output have different licenses. 5056 For example, a piece of software whose code is licensed under GPLv2 5057 but has accompanying documentation licensed under the GNU Free 5058 Documentation License 1.2 could be specified as follows:: 5059 5060 LICENSE = "GFDL-1.2 & GPL-2.0-only" 5061 LICENSE:${PN} = "GPL-2.0.only" 5062 LICENSE:${PN}-doc = "GFDL-1.2" 5063 5064 :term:`LICENSE_CREATE_PACKAGE` 5065 Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded 5066 build system to create an extra package (i.e. 5067 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add 5068 those packages to the 5069 :term:`RRECOMMENDS`\ ``:${PN}``. 5070 5071 The ``${PN}-lic`` package installs a directory in 5072 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base 5073 name, and installs files in that directory that contain license and 5074 copyright information (i.e. copies of the appropriate license files 5075 from ``meta/common-licenses`` that match the licenses specified in 5076 the :term:`LICENSE` variable of the recipe metadata 5077 and copies of files marked in 5078 :term:`LIC_FILES_CHKSUM` as containing 5079 license text). 5080 5081 For related information on providing license text, see the 5082 :term:`COPY_LIC_DIRS` variable, the 5083 :term:`COPY_LIC_MANIFEST` variable, and the 5084 ":ref:`dev-manual/licenses:providing license text`" 5085 section in the Yocto Project Development Tasks Manual. 5086 5087 :term:`LICENSE_FLAGS` 5088 Specifies additional flags for a recipe you must allow through 5089 :term:`LICENSE_FLAGS_ACCEPTED` in 5090 order for the recipe to be built. When providing multiple flags, 5091 separate them with spaces. 5092 5093 This value is independent of :term:`LICENSE` and is 5094 typically used to mark recipes that might require additional licenses 5095 in order to be used in a commercial product. For more information, 5096 see the 5097 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" 5098 section in the Yocto Project Development Tasks Manual. 5099 5100 :term:`LICENSE_FLAGS_ACCEPTED` 5101 Lists license flags that when specified in 5102 :term:`LICENSE_FLAGS` within a recipe should not 5103 prevent that recipe from being built. For more information, see the 5104 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" 5105 section in the Yocto Project Development Tasks Manual. 5106 5107 :term:`LICENSE_FLAGS_DETAILS` 5108 Adds details about a flag in :term:`LICENSE_FLAGS`. This way, 5109 if such a flag is not accepted through :term:`LICENSE_FLAGS_ACCEPTED`, 5110 the error message will be more informative, containing the specified 5111 extra details. 5112 5113 For example, a recipe with an EULA may set:: 5114 5115 LICENSE_FLAGS = "FooBar-EULA" 5116 LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula." 5117 5118 If ``Foobar-EULA`` isn't in :term:`LICENSE_FLAGS_ACCEPTED`, the 5119 error message is more useful:: 5120 5121 Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED. 5122 For further details, see https://example.com/eula. 5123 5124 :term:`LICENSE_PATH` 5125 Path to additional licenses used during the build. By default, the 5126 OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the 5127 directory that holds common license text used during the build. The 5128 :term:`LICENSE_PATH` variable allows you to extend that location to other 5129 areas that have additional licenses:: 5130 5131 LICENSE_PATH += "path-to-additional-common-licenses" 5132 5133 :term:`LINUX_KERNEL_TYPE` 5134 Defines the kernel type to be used in assembling the configuration. 5135 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 5136 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" 5137 section in the 5138 Yocto Project Linux Kernel Development Manual for more information on 5139 kernel types. 5140 5141 If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to 5142 "standard". Together with :term:`KMACHINE`, the 5143 :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by 5144 the kernel tools to find the appropriate description within the 5145 kernel :term:`Metadata` with which to build out the sources 5146 and configuration. 5147 5148 :term:`LINUX_VERSION` 5149 The Linux version from ``kernel.org`` on which the Linux kernel image 5150 being built using the OpenEmbedded build system is based. You define 5151 this variable in the kernel recipe. For example, the 5152 ``linux-yocto-3.4.bb`` kernel recipe found in 5153 ``meta/recipes-kernel/linux`` defines the variables as follows:: 5154 5155 LINUX_VERSION ?= "3.4.24" 5156 5157 The :term:`LINUX_VERSION` variable is used to define :term:`PV` 5158 for the recipe:: 5159 5160 PV = "${LINUX_VERSION}+git${SRCPV}" 5161 5162 :term:`LINUX_VERSION_EXTENSION` 5163 A string extension compiled into the version string of the Linux 5164 kernel built with the OpenEmbedded build system. You define this 5165 variable in the kernel recipe. For example, the linux-yocto kernel 5166 recipes all define the variable as follows:: 5167 5168 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" 5169 5170 Defining this variable essentially sets the Linux kernel 5171 configuration item ``CONFIG_LOCALVERSION``, which is visible through 5172 the ``uname`` command. Here is an example that shows the extension 5173 assuming it was set as previously shown:: 5174 5175 $ uname -r 5176 3.7.0-rc8-custom 5177 5178 :term:`LOG_DIR` 5179 Specifies the directory to which the OpenEmbedded build system writes 5180 overall log files. The default directory is ``${TMPDIR}/log``. 5181 5182 For the directory containing logs specific to each task, see the 5183 :term:`T` variable. 5184 5185 :term:`MACHINE` 5186 Specifies the target device for which the image is built. You define 5187 :term:`MACHINE` in the ``local.conf`` file found in the 5188 :term:`Build Directory`. By default, :term:`MACHINE` is set to 5189 "qemux86", which is an x86-based architecture machine to be emulated 5190 using QEMU:: 5191 5192 MACHINE ?= "qemux86" 5193 5194 The variable corresponds to a machine configuration file of the same 5195 name, through which machine-specific configurations are set. Thus, 5196 when :term:`MACHINE` is set to "qemux86", the corresponding 5197 ``qemux86.conf`` machine configuration file can be found in 5198 the :term:`Source Directory` in 5199 ``meta/conf/machine``. 5200 5201 The list of machines supported by the Yocto Project as shipped 5202 include the following:: 5203 5204 MACHINE ?= "qemuarm" 5205 MACHINE ?= "qemuarm64" 5206 MACHINE ?= "qemumips" 5207 MACHINE ?= "qemumips64" 5208 MACHINE ?= "qemuppc" 5209 MACHINE ?= "qemux86" 5210 MACHINE ?= "qemux86-64" 5211 MACHINE ?= "genericx86" 5212 MACHINE ?= "genericx86-64" 5213 MACHINE ?= "beaglebone" 5214 5215 The last five are Yocto Project reference hardware 5216 boards, which are provided in the ``meta-yocto-bsp`` layer. 5217 5218 .. note:: 5219 5220 Adding additional Board Support Package (BSP) layers to your 5221 configuration adds new possible settings for :term:`MACHINE`. 5222 5223 :term:`MACHINE_ARCH` 5224 Specifies the name of the machine-specific architecture. This 5225 variable is set automatically from :term:`MACHINE` or 5226 :term:`TUNE_PKGARCH`. You should not hand-edit 5227 the :term:`MACHINE_ARCH` variable. 5228 5229 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 5230 A list of required machine-specific packages to install as part of 5231 the image being built. The build process depends on these packages 5232 being present. Furthermore, because this is a "machine-essential" 5233 variable, the list of packages are essential for the machine to boot. 5234 The impact of this variable affects images based on 5235 ``packagegroup-core-boot``, including the ``core-image-minimal`` 5236 image. 5237 5238 This variable is similar to the 5239 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception 5240 that the image being built has a build dependency on the variable's 5241 list of packages. In other words, the image will not build if a file 5242 in this list is not found. 5243 5244 As an example, suppose the machine for which you are building 5245 requires ``example-init`` to be run during boot to initialize the 5246 hardware. In this case, you would use the following in the machine's 5247 ``.conf`` configuration file:: 5248 5249 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" 5250 5251 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` 5252 A list of recommended machine-specific packages to install as part of 5253 the image being built. The build process does not depend on these 5254 packages being present. However, because this is a 5255 "machine-essential" variable, the list of packages are essential for 5256 the machine to boot. The impact of this variable affects images based 5257 on ``packagegroup-core-boot``, including the ``core-image-minimal`` 5258 image. 5259 5260 This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 5261 variable with the exception that the image being built does not have 5262 a build dependency on the variable's list of packages. In other 5263 words, the image will still build if a package in this list is not 5264 found. Typically, this variable is used to handle essential kernel 5265 modules, whose functionality may be selected to be built into the 5266 kernel rather than as a module, in which case a package will not be 5267 produced. 5268 5269 Consider an example where you have a custom kernel where a specific 5270 touchscreen driver is required for the machine to be usable. However, 5271 the driver can be built as a module or into the kernel depending on 5272 the kernel configuration. If the driver is built as a module, you 5273 want it to be installed. But, when the driver is built into the 5274 kernel, you still want the build to succeed. This variable sets up a 5275 "recommends" relationship so that in the latter case, the build will 5276 not fail due to the missing package. To accomplish this, assuming the 5277 package for the module was called ``kernel-module-ab123``, you would 5278 use the following in the machine's ``.conf`` configuration file:: 5279 5280 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" 5281 5282 .. note:: 5283 5284 In this example, the ``kernel-module-ab123`` recipe needs to 5285 explicitly set its :term:`PACKAGES` variable to ensure that BitBake 5286 does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to 5287 satisfy the dependency. 5288 5289 Some examples of these machine essentials are flash, screen, 5290 keyboard, mouse, or touchscreen drivers (depending on the machine). 5291 5292 :term:`MACHINE_EXTRA_RDEPENDS` 5293 A list of machine-specific packages to install as part of the image 5294 being built that are not essential for the machine to boot. However, 5295 the build process for more fully-featured images depends on the 5296 packages being present. 5297 5298 This variable affects all images based on ``packagegroup-base``, 5299 which does not include the ``core-image-minimal`` or 5300 ``core-image-full-cmdline`` images. 5301 5302 The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable 5303 with the exception that the image being built has a build dependency 5304 on the variable's list of packages. In other words, the image will 5305 not build if a file in this list is not found. 5306 5307 An example is a machine that has WiFi capability but is not essential 5308 for the machine to boot the image. However, if you are building a 5309 more fully-featured image, you want to enable the WiFi. The package 5310 containing the firmware for the WiFi hardware is always expected to 5311 exist, so it is acceptable for the build process to depend upon 5312 finding the package. In this case, assuming the package for the 5313 firmware was called ``wifidriver-firmware``, you would use the 5314 following in the ``.conf`` file for the machine:: 5315 5316 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" 5317 5318 :term:`MACHINE_EXTRA_RRECOMMENDS` 5319 A list of machine-specific packages to install as part of the image 5320 being built that are not essential for booting the machine. The image 5321 being built has no build dependency on this list of packages. 5322 5323 This variable affects only images based on ``packagegroup-base``, 5324 which does not include the ``core-image-minimal`` or 5325 ``core-image-full-cmdline`` images. 5326 5327 This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable 5328 with the exception that the image being built does not have a build 5329 dependency on the variable's list of packages. In other words, the 5330 image will build if a file in this list is not found. 5331 5332 An example is a machine that has WiFi capability but is not essential 5333 For the machine to boot the image. However, if you are building a 5334 more fully-featured image, you want to enable WiFi. In this case, the 5335 package containing the WiFi kernel module will not be produced if the 5336 WiFi driver is built into the kernel, in which case you still want 5337 the build to succeed instead of failing as a result of the package 5338 not being found. To accomplish this, assuming the package for the 5339 module was called ``kernel-module-examplewifi``, you would use the 5340 following in the ``.conf`` file for the machine:: 5341 5342 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" 5343 5344 :term:`MACHINE_FEATURES` 5345 Specifies the list of hardware features the 5346 :term:`MACHINE` is capable of supporting. For related 5347 information on enabling features, see the 5348 :term:`DISTRO_FEATURES`, 5349 :term:`COMBINED_FEATURES`, and 5350 :term:`IMAGE_FEATURES` variables. 5351 5352 For a list of hardware features supported by the Yocto Project as 5353 shipped, see the ":ref:`ref-features-machine`" section. 5354 5355 :term:`MACHINE_FEATURES_BACKFILL` 5356 A list of space-separated features to be added to 5357 :term:`MACHINE_FEATURES` if not also present in 5358 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. 5359 5360 This variable is set in the ``meta/conf/bitbake.conf`` file. It is not 5361 intended to be user-configurable. It is best to just reference the 5362 variable to see which machine features are being 5363 :ref:`backfilled <ref-features-backfill>` for all machine configurations. 5364 5365 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` 5366 A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL` 5367 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added 5368 to :term:`MACHINE_FEATURES`) during the build. 5369 5370 This corresponds to an opt-out mechanism. When new default machine 5371 features are introduced, machine definition maintainers can review 5372 (`consider`) them and decide to exclude them from the 5373 :ref:`backfilled <ref-features-backfill>` features. Therefore, the 5374 combination of :term:`MACHINE_FEATURES_BACKFILL` and 5375 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to 5376 add new default features without breaking existing machine definitions. 5377 5378 :term:`MACHINEOVERRIDES` 5379 A colon-separated list of overrides that apply to the current 5380 machine. By default, this list includes the value of 5381 :term:`MACHINE`. 5382 5383 You can extend :term:`MACHINEOVERRIDES` to add extra overrides that 5384 should apply to a machine. For example, all machines emulated in QEMU 5385 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named 5386 ``meta/conf/machine/include/qemu.inc`` that prepends the following 5387 override to :term:`MACHINEOVERRIDES`:: 5388 5389 MACHINEOVERRIDES =. "qemuall:" 5390 5391 This 5392 override allows variables to be overridden for all machines emulated 5393 in QEMU, like in the following example from the ``connman-conf`` 5394 recipe:: 5395 5396 SRC_URI:append:qemuall = " file://wired.config \ 5397 file://wired-setup \ 5398 " 5399 5400 The underlying mechanism behind 5401 :term:`MACHINEOVERRIDES` is simply that it is included in the default 5402 value of :term:`OVERRIDES`. 5403 5404 :term:`MAINTAINER` 5405 The email address of the distribution maintainer. 5406 5407 :term:`MESON_BUILDTYPE` 5408 Value of the Meson ``--buildtype`` argument used by the 5409 :ref:`ref-classes-meson` class. It defaults to ``debug`` if 5410 :term:`DEBUG_BUILD` is set to "1", and ``plain`` otherwise. 5411 5412 See `Meson build options <https://mesonbuild.com/Builtin-options.html>`__ 5413 for the values you could set in a recipe. Values such as ``plain``, 5414 ``debug``, ``debugoptimized``, ``release`` and ``minsize`` allow 5415 you to specify the inclusion of debugging symbols and the compiler 5416 optimizations (none, performance or size). 5417 5418 :term:`MESON_TARGET` 5419 A variable for the :ref:`ref-classes-meson` class, allowing to choose 5420 a Meson target to build in :ref:`ref-tasks-compile`. Otherwise, the 5421 default targets are built. 5422 5423 :term:`METADATA_BRANCH` 5424 The branch currently checked out for the OpenEmbedded-Core layer (path 5425 determined by :term:`COREBASE`). 5426 5427 :term:`METADATA_REVISION` 5428 The revision currently checked out for the OpenEmbedded-Core layer (path 5429 determined by :term:`COREBASE`). 5430 5431 :term:`MIME_XDG_PACKAGES` 5432 The current implementation of the :ref:`ref-classes-mime-xdg` 5433 class cannot detect ``.desktop`` files installed through absolute 5434 symbolic links. Use this setting to make the class create post-install 5435 and post-remove scripts for these packages anyway, to invoke the 5436 ``update-destop-database`` command. 5437 5438 :term:`MIRRORS` 5439 Specifies additional paths from which the OpenEmbedded build system 5440 gets source code. When the build system searches for source code, it 5441 first tries the local download directory. If that location fails, the 5442 build system tries locations defined by 5443 :term:`PREMIRRORS`, the upstream source, and then 5444 locations specified by :term:`MIRRORS` in that order. 5445 5446 The default value for :term:`MIRRORS` is defined in the 5447 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer. 5448 5449 :term:`MLPREFIX` 5450 Specifies a prefix has been added to :term:`PN` to create a 5451 special version of a recipe or package (i.e. a Multilib version). The 5452 variable is used in places where the prefix needs to be added to or 5453 removed from a name (e.g. the :term:`BPN` variable). 5454 :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`. 5455 5456 .. note:: 5457 5458 The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation 5459 is historical and comes from a time when ":ref:`ref-classes-nativesdk`" 5460 was a suffix rather than a prefix on the recipe name. When 5461 ":ref:`ref-classes-nativesdk`" was turned into a prefix, it made sense 5462 to set :term:`MLPREFIX` for it as well. 5463 5464 To help understand when :term:`MLPREFIX` might be needed, consider when 5465 :term:`BBCLASSEXTEND` is used to provide a :ref:`ref-classes-nativesdk` 5466 version of a recipe in addition to the target version. If that recipe 5467 declares build-time dependencies on tasks in other recipes by using 5468 :term:`DEPENDS`, then a dependency on "foo" will automatically get 5469 rewritten to a dependency on "nativesdk-foo". However, dependencies like 5470 the following will not get rewritten automatically:: 5471 5472 do_foo[depends] += "recipe:do_foo" 5473 5474 If you want such a dependency to also get transformed, you can do the 5475 following:: 5476 5477 do_foo[depends] += "${MLPREFIX}recipe:do_foo" 5478 5479 :term:`module_autoload` 5480 This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD` 5481 variable. You should replace all occurrences of :term:`module_autoload` 5482 with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example:: 5483 5484 module_autoload_rfcomm = "rfcomm" 5485 5486 should now be replaced with:: 5487 5488 KERNEL_MODULE_AUTOLOAD += "rfcomm" 5489 5490 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. 5491 5492 :term:`module_conf` 5493 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__ 5494 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` 5495 file. 5496 5497 You can use this variable anywhere that it can be recognized by the 5498 kernel recipe or out-of-tree kernel module recipe (e.g. a machine 5499 configuration file, a distribution configuration file, an append file 5500 for the recipe, or the recipe itself). If you use this variable, you 5501 must also be sure to list the module name in the 5502 :term:`KERNEL_MODULE_PROBECONF` 5503 variable. 5504 5505 Here is the general syntax:: 5506 5507 module_conf_module_name = "modprobe.d-syntax" 5508 5509 You must use the kernel module name override. 5510 5511 Run ``man modprobe.d`` in the shell to find out more information on 5512 the exact syntax you want to provide with :term:`module_conf`. 5513 5514 Including :term:`module_conf` causes the OpenEmbedded build system to 5515 populate the ``/etc/modprobe.d/modname.conf`` file with 5516 ``modprobe.d`` syntax lines. Here is an example that adds the options 5517 ``arg1`` and ``arg2`` to a module named ``mymodule``:: 5518 5519 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" 5520 5521 For information on how to specify kernel modules to auto-load on 5522 boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable. 5523 5524 :term:`MODULE_TARBALL_DEPLOY` 5525 Controls creation of the ``modules-*.tgz`` file. Set this variable to 5526 "0" to disable creation of this file, which contains all of the 5527 kernel modules resulting from a kernel build. 5528 5529 :term:`MODULE_TARBALL_LINK_NAME` 5530 The link name of the kernel module tarball. This variable is set in 5531 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 5532 5533 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 5534 5535 The value 5536 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the 5537 same file, has the following value:: 5538 5539 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 5540 5541 See the :term:`MACHINE` variable for additional information. 5542 5543 :term:`MODULE_TARBALL_NAME` 5544 The base name of the kernel module tarball. This variable is set in 5545 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: 5546 5547 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" 5548 5549 See :term:`KERNEL_ARTIFACT_NAME` for additional information. 5550 5551 :term:`MOUNT_BASE` 5552 On non-systemd systems (where ``udev-extraconf`` is being used), 5553 specifies the base directory for auto-mounting filesystems. The 5554 default value is "/run/media". 5555 5556 :term:`MULTIMACH_TARGET_SYS` 5557 Uniquely identifies the type of the target system for which packages 5558 are being built. This variable allows output for different types of 5559 target systems to be put into different subdirectories of the same 5560 output directory. 5561 5562 The default value of this variable is:: 5563 5564 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} 5565 5566 Some classes (e.g. :ref:`ref-classes-cross-canadian`) modify the 5567 :term:`MULTIMACH_TARGET_SYS` value. 5568 5569 See the :term:`STAMP` variable for an example. See the 5570 :term:`STAGING_DIR_TARGET` variable for more information. 5571 5572 :term:`NATIVELSBSTRING` 5573 A string identifying the host distribution. Strings consist of the 5574 host distributor ID followed by the release, as reported by the 5575 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For 5576 example, when running a build on Ubuntu 12.10, the value is 5577 "Ubuntu-12.10". If this information is unable to be determined, the 5578 value resolves to "Unknown". 5579 5580 This variable is used by default to isolate native shared state 5581 packages for different distributions (e.g. to avoid problems with 5582 ``glibc`` version incompatibilities). Additionally, the variable is 5583 checked against 5584 :term:`SANITY_TESTED_DISTROS` if that 5585 variable is set. 5586 5587 :term:`NM` 5588 The minimal command and arguments to run ``nm``. 5589 5590 :term:`NO_GENERIC_LICENSE` 5591 Avoids QA errors when you use a non-common, non-CLOSED license in a 5592 recipe. There are packages, such as the linux-firmware package, with many 5593 licenses that are not in any way common. Also, new licenses are added 5594 occasionally to avoid introducing a lot of common license files, 5595 which are only applicable to a specific package. 5596 :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does 5597 not exist in common licenses. 5598 5599 The following example shows how to add :term:`NO_GENERIC_LICENSE` to a 5600 recipe:: 5601 5602 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" 5603 5604 Here is an example that 5605 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched 5606 source:: 5607 5608 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" 5609 5610 :term:`NO_RECOMMENDATIONS` 5611 Prevents installation of all "recommended-only" packages. 5612 Recommended-only packages are packages installed only through the 5613 :term:`RRECOMMENDS` variable). Setting the 5614 :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on:: 5615 5616 NO_RECOMMENDATIONS = "1" 5617 5618 You can set this variable globally in your ``local.conf`` file or you 5619 can attach it to a specific image recipe by using the recipe name 5620 override:: 5621 5622 NO_RECOMMENDATIONS:pn-target_image = "1" 5623 5624 It is important to realize that if you choose to not install packages 5625 using this variable and some other packages are dependent on them 5626 (i.e. listed in a recipe's :term:`RDEPENDS` 5627 variable), the OpenEmbedded build system ignores your request and 5628 will install the packages to avoid dependency errors. 5629 5630 .. note:: 5631 5632 Some recommended packages might be required for certain system 5633 functionality, such as kernel modules. It is up to you to add 5634 packages with the :term:`IMAGE_INSTALL` variable. 5635 5636 This variable is only supported when using the IPK and RPM 5637 packaging backends. DEB is not supported. 5638 5639 See the :term:`BAD_RECOMMENDATIONS` and 5640 the :term:`PACKAGE_EXCLUDE` variables for 5641 related information. 5642 5643 :term:`NOAUTOPACKAGEDEBUG` 5644 Disables auto package from splitting ``.debug`` files. If a recipe 5645 requires ``FILES:${PN}-dbg`` to be set manually, the 5646 :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the 5647 content of the debug package. For example:: 5648 5649 NOAUTOPACKAGEDEBUG = "1" 5650 FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" 5651 FILES:${PN}-dbg = "/usr/src/debug/" 5652 FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" 5653 5654 :term:`NON_MULTILIB_RECIPES` 5655 A list of recipes that should not be built for multilib. OE-Core's 5656 ``multilib.conf`` file defines a reasonable starting point for this 5657 list with:: 5658 5659 NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot" 5660 5661 :term:`NVDCVE_API_KEY` 5662 The NVD API key used to retrieve data from the CVE database when 5663 using :ref:`ref-classes-cve-check`. 5664 5665 By default, no API key is used, which results in larger delays between API 5666 requests and limits the number of queries to the public rate limits posted 5667 at the `NVD developer's page <https://nvd.nist.gov/developers/start-here>`__. 5668 5669 NVD API keys can be requested through the 5670 `Request an API Key <https://nvd.nist.gov/developers/request-an-api-key>`__ 5671 page. You can set this variable to the NVD API key in your ``local.conf`` file. 5672 Example:: 5673 5674 NVDCVE_API_KEY = "fe753&7a2-1427-347d-23ff-b2e2b7ca5f3" 5675 5676 :term:`OBJCOPY` 5677 The minimal command and arguments to run ``objcopy``. 5678 5679 :term:`OBJDUMP` 5680 The minimal command and arguments to run ``objdump``. 5681 5682 :term:`OE_BINCONFIG_EXTRA_MANGLE` 5683 When inheriting the :ref:`ref-classes-binconfig` class, 5684 this variable specifies additional arguments passed to the "sed" 5685 command. The sed command alters any paths in configuration scripts 5686 that have been set up during compilation. Inheriting this class 5687 results in all paths in these scripts being changed to point into the 5688 ``sysroots/`` directory so that all builds that use the script will 5689 use the correct directories for the cross compiling layout. 5690 5691 See the ``meta/classes-recipe/binconfig.bbclass`` in the 5692 :term:`Source Directory` for details on how this class 5693 applies these additional sed command arguments. 5694 5695 :term:`OECMAKE_GENERATOR` 5696 A variable for the :ref:`ref-classes-cmake` class, allowing to choose 5697 which back-end will be generated by CMake to build an application. 5698 5699 By default, this variable is set to ``Ninja``, which is faster than GNU 5700 make, but if building is broken with Ninja, a recipe can use this 5701 variable to use GNU make instead:: 5702 5703 OECMAKE_GENERATOR = "Unix Makefiles" 5704 5705 :term:`OE_IMPORTS` 5706 An internal variable used to tell the OpenEmbedded build system what 5707 Python modules to import for every Python function run by the system. 5708 5709 .. note:: 5710 5711 Do not set this variable. It is for internal use only. 5712 5713 :term:`OE_INIT_ENV_SCRIPT` 5714 The name of the build environment setup script for the purposes of 5715 setting up the environment within the extensible SDK. The default 5716 value is "oe-init-build-env". 5717 5718 If you use a custom script to set up your build environment, set the 5719 :term:`OE_INIT_ENV_SCRIPT` variable to its name. 5720 5721 :term:`OE_TERMINAL` 5722 Controls how the OpenEmbedded build system spawns interactive 5723 terminals on the host development system (e.g. using the BitBake 5724 command with the ``-c devshell`` command-line option). For more 5725 information, see the ":ref:`dev-manual/development-shell:using a development shell`" section in 5726 the Yocto Project Development Tasks Manual. 5727 5728 You can use the following values for the :term:`OE_TERMINAL` variable: 5729 5730 - auto 5731 - gnome 5732 - xfce 5733 - rxvt 5734 - screen 5735 - konsole 5736 - none 5737 5738 :term:`OEROOT` 5739 The directory from which the top-level build environment setup script 5740 is sourced. The Yocto Project provides a top-level build environment 5741 setup script: :ref:`structure-core-script`. When you run this 5742 script, the :term:`OEROOT` variable resolves to the directory that 5743 contains the script. 5744 5745 For additional information on how this variable is used, see the 5746 initialization script. 5747 5748 :term:`OEQA_REPRODUCIBLE_TEST_PACKAGE` 5749 Set the package manager(s) for build reproducibility testing. 5750 See :yocto_git:`reproducible.py </poky/tree/meta/lib/oeqa/selftest/cases/reproducible.py>` 5751 and :doc:`/test-manual/reproducible-builds`. 5752 5753 :term:`OEQA_REPRODUCIBLE_TEST_TARGET` 5754 Set build target for build reproducibility testing. By default 5755 all available recipes are compiled with "bitbake world", see also :term:`EXCLUDE_FROM_WORLD` 5756 and :doc:`/test-manual/reproducible-builds`. 5757 5758 :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS` 5759 Set build targets which can be rebuilt using :ref:`shared state <overview-manual/concepts:shared state cache>` 5760 when running build reproducibility tests. See :doc:`/test-manual/reproducible-builds`. 5761 5762 :term:`OLDEST_KERNEL` 5763 Declares the oldest version of the Linux kernel that the produced 5764 binaries must support. This variable is passed into the build of the 5765 Embedded GNU C Library (``glibc``). 5766 5767 The default for this variable comes from the 5768 ``meta/conf/bitbake.conf`` configuration file. You can override this 5769 default by setting the variable in a custom distribution 5770 configuration file. 5771 5772 :term:`OPKG_MAKE_INDEX_EXTRA_PARAMS` 5773 Specifies extra parameters for the ``opkg-make-index`` command. 5774 5775 :term:`OPKGBUILDCMD` 5776 The variable :term:`OPKGBUILDCMD` specifies the command used to build opkg 5777 packages when using the :ref:`ref-classes-package_ipk` class. It is 5778 defined in :ref:`ref-classes-package_ipk` as:: 5779 5780 OPKGBUILDCMD ??= 'opkg-build -Z zstd -a "${ZSTD_DEFAULTS}"' 5781 5782 :term:`OVERLAYFS_ETC_DEVICE` 5783 When the :ref:`ref-classes-overlayfs-etc` class is 5784 inherited, specifies the device to be mounted for the read/write 5785 layer of ``/etc``. There is no default, so you must set this if you 5786 wish to enable :ref:`ref-classes-overlayfs-etc`, for 5787 example, assuming ``/dev/mmcblk0p2`` was the desired device:: 5788 5789 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2" 5790 5791 :term:`OVERLAYFS_ETC_EXPOSE_LOWER` 5792 When the :ref:`ref-classes-overlayfs-etc` class is 5793 inherited, if set to "1" then a read-only access to the original 5794 ``/etc`` content will be provided as a ``lower/`` subdirectory of 5795 :term:`OVERLAYFS_ETC_MOUNT_POINT`. The default value is "0". 5796 5797 :term:`OVERLAYFS_ETC_FSTYPE` 5798 When the :ref:`ref-classes-overlayfs-etc` class is 5799 inherited, specifies the file system type for the read/write 5800 layer of ``/etc``. There is no default, so you must set this if you 5801 wish to enable :ref:`ref-classes-overlayfs-etc`, 5802 for example, assuming the file system is ext4:: 5803 5804 OVERLAYFS_ETC_FSTYPE = "ext4" 5805 5806 :term:`OVERLAYFS_ETC_MOUNT_OPTIONS` 5807 When the :ref:`ref-classes-overlayfs-etc` class is 5808 inherited, specifies the mount options for the read-write layer. 5809 The default value is "defaults". 5810 5811 :term:`OVERLAYFS_ETC_MOUNT_POINT` 5812 When the :ref:`ref-classes-overlayfs-etc` class is 5813 inherited, specifies the parent mount path for the filesystem layers. 5814 There is no default, so you must set this if you wish to enable 5815 :ref:`ref-classes-overlayfs-etc`, for example if the desired path is 5816 "/data":: 5817 5818 OVERLAYFS_ETC_MOUNT_POINT = "/data" 5819 5820 :term:`OVERLAYFS_ETC_USE_ORIG_INIT_NAME` 5821 When the :ref:`ref-classes-overlayfs-etc` class is inherited, controls 5822 how the generated init will be named. For more information, see the 5823 :ref:`ref-classes-overlayfs-etc` class documentation. The default value 5824 is "1". 5825 5826 :term:`OVERLAYFS_MOUNT_POINT` 5827 When inheriting the :ref:`ref-classes-overlayfs` class, 5828 specifies mount point(s) to be used. For example:: 5829 5830 OVERLAYFS_MOUNT_POINT[data] = "/data" 5831 5832 The assumes you have a ``data.mount`` systemd unit defined elsewhere in 5833 your BSP (e.g. in ``systemd-machine-units`` recipe) and it is installed 5834 into the image. For more information see :ref:`ref-classes-overlayfs`. 5835 5836 .. note:: 5837 5838 Although the :ref:`ref-classes-overlayfs` class is 5839 inherited by individual recipes, :term:`OVERLAYFS_MOUNT_POINT` 5840 should be set in your machine configuration. 5841 5842 :term:`OVERLAYFS_QA_SKIP` 5843 When inheriting the :ref:`ref-classes-overlayfs` class, 5844 provides the ability to disable QA checks for particular overlayfs 5845 mounts. For example:: 5846 5847 OVERLAYFS_QA_SKIP[data] = "mount-configured" 5848 5849 .. note:: 5850 5851 Although the :ref:`ref-classes-overlayfs` class is 5852 inherited by individual recipes, :term:`OVERLAYFS_QA_SKIP` 5853 should be set in your machine configuration. 5854 5855 :term:`OVERLAYFS_WRITABLE_PATHS` 5856 When inheriting the :ref:`ref-classes-overlayfs` class, 5857 specifies writable paths used at runtime for the recipe. For 5858 example:: 5859 5860 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" 5861 5862 :term:`OVERRIDES` 5863 A colon-separated list of overrides that currently apply. Overrides 5864 are a BitBake mechanism that allows variables to be selectively 5865 overridden at the end of parsing. The set of overrides in 5866 :term:`OVERRIDES` represents the "state" during building, which includes 5867 the current recipe being built, the machine for which it is being 5868 built, and so forth. 5869 5870 As an example, if the string "an-override" appears as an element in 5871 the colon-separated list in :term:`OVERRIDES`, then the following 5872 assignment will override ``FOO`` with the value "overridden" at the 5873 end of parsing:: 5874 5875 FOO:an-override = "overridden" 5876 5877 See the 5878 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 5879 section in the BitBake User Manual for more information on the 5880 overrides mechanism. 5881 5882 The default value of :term:`OVERRIDES` includes the values of the 5883 :term:`CLASSOVERRIDE`, 5884 :term:`MACHINEOVERRIDES`, and 5885 :term:`DISTROOVERRIDES` variables. Another 5886 important override included by default is ``pn-${PN}``. This override 5887 allows variables to be set for a single recipe within configuration 5888 (``.conf``) files. Here is an example:: 5889 5890 FOO:pn-myrecipe = "myrecipe-specific value" 5891 5892 .. note:: 5893 5894 An easy way to see what overrides apply is to search for :term:`OVERRIDES` 5895 in the output of the ``bitbake -e`` command. See the 5896 ":ref:`dev-manual/debugging:viewing variable values`" section in the Yocto 5897 Project Development Tasks Manual for more information. 5898 5899 :term:`P` 5900 The recipe name and version. :term:`P` is comprised of the following:: 5901 5902 ${PN}-${PV} 5903 5904 :term:`P4DIR` 5905 See :term:`bitbake:P4DIR` in the BitBake manual. 5906 5907 :term:`PACKAGE_ADD_METADATA` 5908 This variable defines additional metadata to add to packages. 5909 5910 You may find you need to inject additional metadata into packages. 5911 This variable allows you to do that by setting the injected data as 5912 the value. Multiple fields can be added by splitting the content with 5913 the literal separator "\n". 5914 5915 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable 5916 to do package type specific settings. It can also be made package 5917 specific by using the package name as a suffix. 5918 5919 You can find out more about applying this variable in the 5920 ":ref:`dev-manual/packages:adding custom metadata to packages`" 5921 section in the Yocto Project Development Tasks Manual. 5922 5923 :term:`PACKAGE_ARCH` 5924 The architecture of the resulting package or packages. 5925 5926 By default, the value of this variable is set to 5927 :term:`TUNE_PKGARCH` when building for the 5928 target, :term:`BUILD_ARCH` when building for the 5929 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the 5930 SDK. 5931 5932 .. note:: 5933 5934 See :term:`SDK_ARCH` for more information. 5935 5936 However, if your recipe's output packages are built specific to the 5937 target machine rather than generally for the architecture of the 5938 machine, you should set :term:`PACKAGE_ARCH` to the value of 5939 :term:`MACHINE_ARCH` in the recipe as follows:: 5940 5941 PACKAGE_ARCH = "${MACHINE_ARCH}" 5942 5943 :term:`PACKAGE_ARCHS` 5944 Specifies a list of architectures compatible with the target machine. 5945 This variable is set automatically and should not normally be 5946 hand-edited. Entries are separated using spaces and listed in order 5947 of priority. The default value for :term:`PACKAGE_ARCHS` is "all any 5948 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". 5949 5950 :term:`PACKAGE_BEFORE_PN` 5951 Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so 5952 that those added packages can pick up files that would normally be 5953 included in the default package. 5954 5955 :term:`PACKAGE_CLASSES` 5956 This variable, which is set in the ``local.conf`` configuration file 5957 found in the ``conf`` folder of the 5958 :term:`Build Directory`, specifies the package manager the 5959 OpenEmbedded build system uses when packaging data. 5960 5961 You can provide one or more of the following arguments for the 5962 variable:: 5963 5964 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" 5965 5966 The build system uses only the first argument in the list as the 5967 package manager when creating your image or SDK. However, packages 5968 will be created using any additional packaging classes you specify. 5969 For example, if you use the following in your ``local.conf`` file:: 5970 5971 PACKAGE_CLASSES ?= "package_ipk" 5972 5973 The OpenEmbedded build system uses 5974 the IPK package manager to create your image or SDK. 5975 5976 For information on packaging and build performance effects as a 5977 result of the package manager in use, see the 5978 ":ref:`ref-classes-package`" section. 5979 5980 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 5981 Determines how to split up and package debug and source information 5982 when creating debugging packages to be used with the GNU Project 5983 Debugger (GDB). In general, based on the value of this variable, 5984 you can combine the source and debug info in a single package, 5985 you can break out the source into a separate package that can be 5986 installed independently, or you can choose to not have the source 5987 packaged at all. 5988 5989 The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable: 5990 5991 - "``.debug``": All debugging and source info is placed in a single 5992 ``*-dbg`` package; debug symbol files are placed next to the 5993 binary in a ``.debug`` directory so that, if a binary is installed 5994 into ``/bin``, the corresponding debug symbol file is installed 5995 in ``/bin/.debug``. Source files are installed in the same ``*-dbg`` 5996 package under ``/usr/src/debug``. 5997 5998 - "``debug-file-directory``": As above, all debugging and source info 5999 is placed in a single ``*-dbg`` package; debug symbol files are 6000 placed entirely under the directory ``/usr/lib/debug`` and separated 6001 by the path from where the binary is installed, so that if a binary 6002 is installed in ``/bin``, the corresponding debug symbols are installed 6003 in ``/usr/lib/debug/bin``, and so on. As above, source is installed 6004 in the same package under ``/usr/src/debug``. 6005 6006 - "``debug-with-srcpkg``": Debugging info is placed in the standard 6007 ``*-dbg`` package as with the ``.debug`` value, while source is 6008 placed in a separate ``*-src`` package, which can be installed 6009 independently. This is the default setting for this variable, 6010 as defined in Poky's ``bitbake.conf`` file. 6011 6012 - "``debug-without-src``": The same behavior as with the ``.debug`` 6013 setting, but no source is packaged at all. 6014 6015 .. note:: 6016 6017 Much of the above package splitting can be overridden via 6018 use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable. 6019 6020 You can find out more about debugging using GDB by reading the 6021 ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section 6022 in the Yocto Project Development Tasks Manual. 6023 6024 :term:`PACKAGE_EXCLUDE` 6025 Lists packages that should not be installed into an image. For 6026 example:: 6027 6028 PACKAGE_EXCLUDE = "package_name package_name package_name ..." 6029 6030 You can set this variable globally in your ``local.conf`` file or you 6031 can attach it to a specific image recipe by using the recipe name 6032 override:: 6033 6034 PACKAGE_EXCLUDE:pn-target_image = "package_name" 6035 6036 If you choose to not install a package using this variable and some 6037 other package is dependent on it (i.e. listed in a recipe's 6038 :term:`RDEPENDS` variable), the OpenEmbedded build 6039 system generates a fatal installation error. Because the build system 6040 halts the process with a fatal error, you can use the variable with 6041 an iterative development process to remove specific components from a 6042 system. 6043 6044 This variable is supported only when using the IPK and RPM 6045 packaging backends. DEB is not supported. 6046 6047 See the :term:`NO_RECOMMENDATIONS` and the 6048 :term:`BAD_RECOMMENDATIONS` variables for 6049 related information. 6050 6051 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` 6052 Prevents specific packages from being installed when you are 6053 installing complementary packages. 6054 6055 You might find that you want to prevent installing certain packages 6056 when you are installing complementary packages. For example, if you 6057 are using :term:`IMAGE_FEATURES` to install 6058 ``dev-pkgs``, you might not want to install all packages from a 6059 particular multilib. If you find yourself in this situation, you can 6060 use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular 6061 expressions to match the packages you want to exclude. 6062 6063 :term:`PACKAGE_EXTRA_ARCHS` 6064 Specifies the list of architectures compatible with the device CPU. 6065 This variable is useful when you build for several different devices 6066 that use miscellaneous processors such as XScale and ARM926-EJS. 6067 6068 :term:`PACKAGE_FEED_ARCHS` 6069 Optionally specifies the package architectures used as part of the 6070 package feed URIs during the build. When used, the 6071 :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed 6072 URI, which is constructed using the 6073 :term:`PACKAGE_FEED_URIS` and 6074 :term:`PACKAGE_FEED_BASE_PATHS` 6075 variables. 6076 6077 .. note:: 6078 6079 You can use the :term:`PACKAGE_FEED_ARCHS` 6080 variable to allow specific package architectures. If you do 6081 not need to allow specific architectures, which is a common 6082 case, you can omit this variable. Omitting the variable results in 6083 all available architectures for the current machine being included 6084 into remote package feeds. 6085 6086 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 6087 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 6088 defined in your ``local.conf`` file:: 6089 6090 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6091 https://example.com/packagerepos/updates" 6092 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 6093 PACKAGE_FEED_ARCHS = "all core2-64" 6094 6095 Given these settings, the resulting package feeds are as follows: 6096 6097 .. code-block:: none 6098 6099 https://example.com/packagerepos/release/rpm/all 6100 https://example.com/packagerepos/release/rpm/core2-64 6101 https://example.com/packagerepos/release/rpm-dev/all 6102 https://example.com/packagerepos/release/rpm-dev/core2-64 6103 https://example.com/packagerepos/updates/rpm/all 6104 https://example.com/packagerepos/updates/rpm/core2-64 6105 https://example.com/packagerepos/updates/rpm-dev/all 6106 https://example.com/packagerepos/updates/rpm-dev/core2-64 6107 6108 :term:`PACKAGE_FEED_BASE_PATHS` 6109 Specifies the base path used when constructing package feed URIs. The 6110 :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a 6111 package feed URI used by the OpenEmbedded build system. The base path 6112 lies between the :term:`PACKAGE_FEED_URIS` 6113 and :term:`PACKAGE_FEED_ARCHS` variables. 6114 6115 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 6116 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 6117 defined in your ``local.conf`` file:: 6118 6119 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6120 https://example.com/packagerepos/updates" 6121 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 6122 PACKAGE_FEED_ARCHS = "all core2-64" 6123 6124 Given these settings, the resulting package feeds are as follows: 6125 6126 .. code-block:: none 6127 6128 https://example.com/packagerepos/release/rpm/all 6129 https://example.com/packagerepos/release/rpm/core2-64 6130 https://example.com/packagerepos/release/rpm-dev/all 6131 https://example.com/packagerepos/release/rpm-dev/core2-64 6132 https://example.com/packagerepos/updates/rpm/all 6133 https://example.com/packagerepos/updates/rpm/core2-64 6134 https://example.com/packagerepos/updates/rpm-dev/all 6135 https://example.com/packagerepos/updates/rpm-dev/core2-64 6136 6137 :term:`PACKAGE_FEED_URIS` 6138 Specifies the front portion of the package feed URI used by the 6139 OpenEmbedded build system. Each final package feed URI is comprised 6140 of :term:`PACKAGE_FEED_URIS`, 6141 :term:`PACKAGE_FEED_BASE_PATHS`, and 6142 :term:`PACKAGE_FEED_ARCHS` variables. 6143 6144 Consider the following example where the :term:`PACKAGE_FEED_URIS`, 6145 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are 6146 defined in your ``local.conf`` file:: 6147 6148 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6149 https://example.com/packagerepos/updates" 6150 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" 6151 PACKAGE_FEED_ARCHS = "all core2-64" 6152 6153 Given these settings, the resulting package feeds are as follows: 6154 6155 .. code-block:: none 6156 6157 https://example.com/packagerepos/release/rpm/all 6158 https://example.com/packagerepos/release/rpm/core2-64 6159 https://example.com/packagerepos/release/rpm-dev/all 6160 https://example.com/packagerepos/release/rpm-dev/core2-64 6161 https://example.com/packagerepos/updates/rpm/all 6162 https://example.com/packagerepos/updates/rpm/core2-64 6163 https://example.com/packagerepos/updates/rpm-dev/all 6164 https://example.com/packagerepos/updates/rpm-dev/core2-64 6165 6166 :term:`PACKAGE_INSTALL` 6167 The final list of packages passed to the package manager for 6168 installation into the image. 6169 6170 Because the package manager controls actual installation of all 6171 packages, the list of packages passed using :term:`PACKAGE_INSTALL` is 6172 not the final list of packages that are actually installed. This 6173 variable is internal to the image construction code. Consequently, in 6174 general, you should use the 6175 :term:`IMAGE_INSTALL` variable to specify 6176 packages for installation. The exception to this is when working with 6177 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 6178 image. When working with an initial RAM filesystem (:term:`Initramfs`) image, 6179 use the :term:`PACKAGE_INSTALL` variable. For information on creating an 6180 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section 6181 in the Yocto Project Development Tasks Manual. 6182 6183 :term:`PACKAGE_INSTALL_ATTEMPTONLY` 6184 Specifies a list of packages the OpenEmbedded build system attempts 6185 to install when creating an image. If a listed package fails to 6186 install, the build system does not generate an error. This variable 6187 is generally not user-defined. 6188 6189 :term:`PACKAGE_PREPROCESS_FUNCS` 6190 Specifies a list of functions run to pre-process the 6191 :term:`PKGD` directory prior to splitting the files out 6192 to individual packages. 6193 6194 :term:`PACKAGE_WRITE_DEPS` 6195 Specifies a list of dependencies for post-installation and 6196 pre-installation scripts on native/cross tools. If your 6197 post-installation or pre-installation script can execute at root filesystem 6198 creation time rather than on the target but depends on a native tool 6199 in order to execute, you need to list the tools in 6200 :term:`PACKAGE_WRITE_DEPS`. 6201 6202 For information on running post-installation scripts, see the 6203 ":ref:`dev-manual/new-recipe:post-installation scripts`" 6204 section in the Yocto Project Development Tasks Manual. 6205 6206 :term:`PACKAGECONFIG` 6207 This variable provides a means of enabling or disabling features of a 6208 recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in 6209 recipes when you specify features and then arguments that define 6210 feature behaviors. Here is the basic block structure (broken over 6211 multiple lines for readability):: 6212 6213 PACKAGECONFIG ??= "f1 f2 f3 ..." 6214 PACKAGECONFIG[f1] = "\ 6215 --with-f1, \ 6216 --without-f1, \ 6217 build-deps-for-f1, \ 6218 runtime-deps-for-f1, \ 6219 runtime-recommends-for-f1, \ 6220 packageconfig-conflicts-for-f1" 6221 PACKAGECONFIG[f2] = "\ 6222 ... and so on and so on ... 6223 6224 The :term:`PACKAGECONFIG` variable itself specifies a space-separated 6225 list of the features to enable. Following the features, you can 6226 determine the behavior of each feature by providing up to six 6227 order-dependent arguments, which are separated by commas. You can 6228 omit any argument you like but must retain the separating commas. The 6229 order is important and specifies the following: 6230 6231 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS` 6232 if the feature is enabled. 6233 6234 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS` 6235 if the feature is disabled. 6236 6237 #. Additional build dependencies (:term:`DEPENDS`) 6238 that should be added if the feature is enabled. 6239 6240 #. Additional runtime dependencies (:term:`RDEPENDS`) 6241 that should be added if the feature is enabled. 6242 6243 #. Additional runtime recommendations 6244 (:term:`RRECOMMENDS`) that should be added if 6245 the feature is enabled. 6246 6247 #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG` 6248 settings for this feature. 6249 6250 Consider the following :term:`PACKAGECONFIG` block taken from the 6251 ``librsvg`` recipe. In this example the feature is ``gtk``, which has 6252 three arguments that determine the feature's behavior:: 6253 6254 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" 6255 6256 The 6257 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is 6258 enabled. In this case, ``--with-gtk3`` is added to the configure 6259 script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the 6260 other hand, if the feature is disabled say through a ``.bbappend`` 6261 file in another layer, then the second argument ``--without-gtk3`` is 6262 added to the configure script instead. 6263 6264 The basic :term:`PACKAGECONFIG` structure previously described holds true 6265 regardless of whether you are creating a block or changing a block. 6266 When creating a block, use the structure inside your recipe. 6267 6268 If you want to change an existing :term:`PACKAGECONFIG` block, you can do 6269 so one of two ways: 6270 6271 - *Append file:* Create an append file named 6272 ``recipename.bbappend`` in your layer and override the value of 6273 :term:`PACKAGECONFIG`. You can either completely override the 6274 variable:: 6275 6276 PACKAGECONFIG = "f4 f5" 6277 6278 Or, you can just append the variable:: 6279 6280 PACKAGECONFIG:append = " f4" 6281 6282 - *Configuration file:* This method is identical to changing the 6283 block through an append file except you edit your ``local.conf`` 6284 or ``mydistro.conf`` file. As with append files previously 6285 described, you can either completely override the variable:: 6286 6287 PACKAGECONFIG:pn-recipename = "f4 f5" 6288 6289 Or, you can just amend the variable:: 6290 6291 PACKAGECONFIG:append:pn-recipename = " f4" 6292 6293 Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service 6294 in which :term:`PACKAGECONFIG` is used to transform the systemd service 6295 into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`:: 6296 6297 example.c 6298 example.service 6299 CMakeLists.txt 6300 6301 The ``CMakeLists.txt`` file contains:: 6302 6303 if(WITH_SYSTEMD) 6304 install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd) 6305 endif(WITH_SYSTEMD) 6306 6307 In order to enable the installation of ``example.service`` we need to 6308 ensure that ``-DWITH_SYSTEMD=ON`` is passed to the ``cmake`` command 6309 execution. Recipes that have ``CMakeLists.txt`` generally inherit the 6310 :ref:`ref-classes-cmake` class, that runs ``cmake`` with 6311 :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be 6312 appended to. Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is 6313 automatically filled with either the first or second element of 6314 :term:`PACKAGECONFIG` flag value, the recipe would be like:: 6315 6316 inherit cmake 6317 PACKAGECONFIG = "systemd" 6318 PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF" 6319 6320 A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER` 6321 or not:: 6322 6323 PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}" 6324 6325 :term:`PACKAGECONFIG_CONFARGS` 6326 A space-separated list of configuration options generated from the 6327 :term:`PACKAGECONFIG` setting. 6328 6329 Classes such as :ref:`ref-classes-autotools` and :ref:`ref-classes-cmake` 6330 use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options 6331 to ``configure`` and ``cmake``, respectively. If you are using 6332 :term:`PACKAGECONFIG` but not a class that handles the 6333 :ref:`ref-tasks-configure` task, then you need to use 6334 :term:`PACKAGECONFIG_CONFARGS` appropriately. 6335 6336 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` 6337 For recipes inheriting the :ref:`ref-classes-packagegroup` class, setting 6338 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the 6339 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) 6340 should not be automatically created by the ``packagegroup`` recipe, 6341 which is the default behavior. 6342 6343 :term:`PACKAGES` 6344 The list of packages the recipe creates. The default value is the 6345 following:: 6346 6347 ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} 6348 6349 During packaging, the :ref:`ref-tasks-package` task 6350 goes through :term:`PACKAGES` and uses the :term:`FILES` 6351 variable corresponding to each package to assign files to the 6352 package. If a file matches the :term:`FILES` variable for more than one 6353 package in :term:`PACKAGES`, it will be assigned to the earliest 6354 (leftmost) package. 6355 6356 Packages in the variable's list that are empty (i.e. where none of 6357 the patterns in ``FILES:``\ pkg match any files installed by the 6358 :ref:`ref-tasks-install` task) are not generated, 6359 unless generation is forced through the 6360 :term:`ALLOW_EMPTY` variable. 6361 6362 :term:`PACKAGES_DYNAMIC` 6363 A promise that your recipe satisfies runtime dependencies for 6364 optional modules that are found in other recipes. 6365 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it 6366 only states that they should be satisfied. For example, if a hard, 6367 runtime dependency (:term:`RDEPENDS`) of another 6368 package is satisfied at build time through the :term:`PACKAGES_DYNAMIC` 6369 variable, but a package with the module name is never actually 6370 produced, then the other package will be broken. Thus, if you attempt 6371 to include that package in an image, you will get a dependency 6372 failure from the packaging system during the 6373 :ref:`ref-tasks-rootfs` task. 6374 6375 Typically, if there is a chance that such a situation can occur and 6376 the package that is not created is valid without the dependency being 6377 satisfied, then you should use :term:`RRECOMMENDS` 6378 (a soft runtime dependency) instead of :term:`RDEPENDS`. 6379 6380 For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when 6381 you are splitting packages, see the 6382 ":ref:`dev-manual/packages:handling optional module packaging`" 6383 section in the Yocto Project Development Tasks Manual. 6384 6385 :term:`PACKAGESPLITFUNCS` 6386 Specifies a list of functions run to perform additional splitting of 6387 files into individual packages. Recipes can either prepend to this 6388 variable or prepend to the ``populate_packages`` function in order to 6389 perform additional package splitting. In either case, the function 6390 should set :term:`PACKAGES`, 6391 :term:`FILES`, :term:`RDEPENDS` and 6392 other packaging variables appropriately in order to perform the 6393 desired splitting. 6394 6395 :term:`PARALLEL_MAKE` 6396 6397 Extra options passed to the build tool command (``make``, 6398 ``ninja`` or more specific build engines, like the Go language one) 6399 during the :ref:`ref-tasks-compile` task, to specify parallel compilation 6400 on the local build host. This variable is usually in the form "-j x", 6401 where x represents the maximum number of parallel threads such engines 6402 can run. 6403 6404 .. note:: 6405 6406 For software compiled by ``make``, in order for :term:`PARALLEL_MAKE` 6407 to be effective, ``make`` must be called with 6408 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 6409 way to ensure this is to use the ``oe_runmake`` function. 6410 6411 By default, the OpenEmbedded build system automatically sets this 6412 variable to be equal to the number of cores the build system uses. 6413 6414 .. note:: 6415 6416 If the software being built experiences dependency issues during 6417 the :ref:`ref-tasks-compile` task that result in race conditions, you can clear 6418 the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For 6419 information on addressing race conditions, see the 6420 ":ref:`dev-manual/debugging:debugging parallel make races`" 6421 section in the Yocto Project Development Tasks Manual. 6422 6423 For single socket systems (i.e. one CPU), you should not have to 6424 override this variable to gain optimal parallelism during builds. 6425 However, if you have very large systems that employ multiple physical 6426 CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is 6427 not set higher than "-j 20". 6428 6429 For more information on speeding up builds, see the 6430 ":ref:`dev-manual/speeding-up-build:speeding up a build`" 6431 section in the Yocto Project Development Tasks Manual. 6432 6433 :term:`PARALLEL_MAKEINST` 6434 Extra options passed to the build tool install command 6435 (``make install``, ``ninja install`` or more specific ones) 6436 during the :ref:`ref-tasks-install` task in order to specify 6437 parallel installation. This variable defaults to the value of 6438 :term:`PARALLEL_MAKE`. 6439 6440 .. note:: 6441 6442 For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST` 6443 to be effective, ``make`` must be called with 6444 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 6445 way to ensure this is to use the ``oe_runmake`` function. 6446 6447 If the software being built experiences dependency issues during 6448 the :ref:`ref-tasks-install` task that result in race conditions, you can 6449 clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a 6450 workaround. For information on addressing race conditions, see the 6451 ":ref:`dev-manual/debugging:debugging parallel make races`" 6452 section in the Yocto Project Development Tasks Manual. 6453 6454 :term:`PATCHRESOLVE` 6455 Determines the action to take when a patch fails. You can set this 6456 variable to one of two values: "noop" and "user". 6457 6458 The default value of "noop" causes the build to simply fail when the 6459 OpenEmbedded build system cannot successfully apply a patch. Setting 6460 the value to "user" causes the build system to launch a shell and 6461 places you in the right location so that you can manually resolve the 6462 conflicts. 6463 6464 Set this variable in your ``local.conf`` file. 6465 6466 :term:`PATCHTOOL` 6467 Specifies the utility used to apply patches for a recipe during the 6468 :ref:`ref-tasks-patch` task. You can specify one of 6469 three utilities: "patch", "quilt", or "git". The default utility used 6470 is "quilt" except for the quilt-native recipe itself. Because the 6471 quilt tool is not available at the time quilt-native is being 6472 patched, it uses "patch". 6473 6474 If you wish to use an alternative patching tool, set the variable in 6475 the recipe using one of the following:: 6476 6477 PATCHTOOL = "patch" 6478 PATCHTOOL = "quilt" 6479 PATCHTOOL = "git" 6480 6481 :term:`PE` 6482 The epoch of the recipe. By default, this variable is unset. The 6483 variable is used to make upgrades possible when the versioning scheme 6484 changes in some backwards incompatible way. 6485 6486 :term:`PE` is the default value of the :term:`PKGE` variable. 6487 6488 :term:`PEP517_WHEEL_PATH` 6489 When used by recipes that inherit the :ref:`ref-classes-python_pep517` 6490 class, denotes the path to ``dist/`` (short for distribution) where the 6491 binary archive ``wheel`` is built. 6492 6493 :term:`PERSISTENT_DIR` 6494 See :term:`bitbake:PERSISTENT_DIR` in the BitBake manual. 6495 6496 :term:`PF` 6497 Specifies the recipe or package name and includes all version and 6498 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and 6499 ``bash-4.2-r1/``). This variable is comprised of the following: 6500 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} 6501 6502 :term:`PIXBUF_PACKAGES` 6503 When inheriting the :ref:`ref-classes-pixbufcache` 6504 class, this variable identifies packages that contain the pixbuf 6505 loaders used with ``gdk-pixbuf``. By default, the 6506 :ref:`ref-classes-pixbufcache` class assumes that 6507 the loaders are in the recipe's main package (i.e. 6508 ``${``\ :term:`PN`\ ``}``). Use this variable if the 6509 loaders you need are in a package other than that main package. 6510 6511 :term:`PKG` 6512 The name of the resulting package created by the OpenEmbedded build 6513 system. 6514 6515 .. note:: 6516 6517 When using the :term:`PKG` variable, you must use a package name override. 6518 6519 For example, when the :ref:`ref-classes-debian` class renames the output 6520 package, it does so by setting ``PKG:packagename``. 6521 6522 :term:`PKG_CONFIG_PATH` 6523 The path to ``pkg-config`` files for the current build context. 6524 ``pkg-config`` reads this variable from the environment. 6525 6526 :term:`PKGD` 6527 Points to the destination directory for files to be packaged before 6528 they are split into individual packages. This directory defaults to 6529 the following:: 6530 6531 ${WORKDIR}/package 6532 6533 Do not change this default. 6534 6535 :term:`PKGDATA_DIR` 6536 Points to a shared, global-state directory that holds data generated 6537 during the packaging process. During the packaging process, the 6538 :ref:`ref-tasks-packagedata` task packages data 6539 for each recipe and installs it into this temporary, shared area. 6540 This directory defaults to the following, which you should not 6541 change:: 6542 6543 ${STAGING_DIR_HOST}/pkgdata 6544 6545 For examples of how this data is used, see the 6546 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6547 section in the Yocto Project Overview and Concepts Manual and the 6548 ":ref:`dev-manual/debugging:viewing package information with \`\`oe-pkgdata-util\`\``" 6549 section in the Yocto Project Development Tasks Manual. For more 6550 information on the shared, global-state directory, see 6551 :term:`STAGING_DIR_HOST`. 6552 6553 :term:`PKGDEST` 6554 Points to the parent directory for files to be packaged after they 6555 have been split into individual packages. This directory defaults to 6556 the following:: 6557 6558 ${WORKDIR}/packages-split 6559 6560 Under this directory, the build system creates directories for each 6561 package specified in :term:`PACKAGES`. Do not change 6562 this default. 6563 6564 :term:`PKGDESTWORK` 6565 Points to a temporary work area where the 6566 :ref:`ref-tasks-package` task saves package metadata. 6567 The :term:`PKGDESTWORK` location defaults to the following:: 6568 6569 ${WORKDIR}/pkgdata 6570 6571 Do not change this default. 6572 6573 The :ref:`ref-tasks-packagedata` task copies the 6574 package metadata from :term:`PKGDESTWORK` to 6575 :term:`PKGDATA_DIR` to make it available globally. 6576 6577 :term:`PKGE` 6578 The epoch of the package(s) built by the recipe. By default, :term:`PKGE` 6579 is set to :term:`PE`. 6580 6581 :term:`PKGR` 6582 The revision of the package(s) built by the recipe. By default, 6583 :term:`PKGR` is set to :term:`PR`. 6584 6585 :term:`PKGV` 6586 The version of the package(s) built by the recipe. By default, 6587 :term:`PKGV` is set to :term:`PV`. 6588 6589 :term:`PN` 6590 This variable can have two separate functions depending on the 6591 context: a recipe name or a resulting package name. 6592 6593 :term:`PN` refers to a recipe name in the context of a file used by the 6594 OpenEmbedded build system as input to create a package. The name is 6595 normally extracted from the recipe file name. For example, if the 6596 recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN` 6597 will be "expat". 6598 6599 The variable refers to a package name in the context of a file 6600 created or produced by the OpenEmbedded build system. 6601 6602 If applicable, the :term:`PN` variable also contains any special suffix 6603 or prefix. For example, using ``bash`` to build packages for the 6604 native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build 6605 packages for the target and for Multilib, :term:`PN` would be ``bash`` 6606 and ``lib64-bash``, respectively. 6607 6608 :term:`POPULATE_SDK_POST_HOST_COMMAND` 6609 Specifies a list of functions to call once the OpenEmbedded build 6610 system has created the host part of the SDK. You can specify 6611 functions separated by spaces:: 6612 6613 POPULATE_SDK_POST_HOST_COMMAND += "function" 6614 6615 If you need to pass the SDK path to a command within a function, you 6616 can use ``${SDK_DIR}``, which points to the parent directory used by 6617 the OpenEmbedded build system when creating SDK output. See the 6618 :term:`SDK_DIR` variable for more information. 6619 6620 :term:`POPULATE_SDK_POST_TARGET_COMMAND` 6621 Specifies a list of functions to call once the OpenEmbedded build 6622 system has created the target part of the SDK. You can specify 6623 functions separated by spaces:: 6624 6625 POPULATE_SDK_POST_TARGET_COMMAND += "function" 6626 6627 If you need to pass the SDK path to a command within a function, you 6628 can use ``${SDK_DIR}``, which points to the parent directory used by 6629 the OpenEmbedded build system when creating SDK output. See the 6630 :term:`SDK_DIR` variable for more information. 6631 6632 :term:`PR` 6633 The revision of the recipe. The default value for this variable is 6634 "r0". Subsequent revisions of the recipe conventionally have the 6635 values "r1", "r2", and so forth. When :term:`PV` increases, 6636 :term:`PR` is conventionally reset to "r0". 6637 6638 .. note:: 6639 6640 The OpenEmbedded build system does not need the aid of :term:`PR` 6641 to know when to rebuild a recipe. The build system uses the task 6642 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the 6643 :ref:`stamp <structure-build-tmp-stamps>` and 6644 :ref:`overview-manual/concepts:shared state cache` 6645 mechanisms. 6646 6647 The :term:`PR` variable primarily becomes significant when a package 6648 manager dynamically installs packages on an already built image. In 6649 this case, :term:`PR`, which is the default value of 6650 :term:`PKGR`, helps the package manager distinguish which 6651 package is the most recent one in cases where many packages have the 6652 same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with 6653 the same :term:`PV` usually means that the packages all install the same 6654 upstream version, but with later (:term:`PR`) version packages including 6655 packaging fixes. 6656 6657 .. note:: 6658 6659 :term:`PR` does not need to be increased for changes that do not change the 6660 package contents or metadata. 6661 6662 Because manually managing :term:`PR` can be cumbersome and error-prone, 6663 an automated solution exists. See the 6664 ":ref:`dev-manual/packages:working with a pr service`" section 6665 in the Yocto Project Development Tasks Manual for more information. 6666 6667 :term:`PREFERRED_PROVIDER` 6668 If multiple recipes provide the same item, this variable determines 6669 which recipe is preferred and thus provides the item (i.e. the 6670 preferred provider). You should always suffix this variable with the 6671 name of the provided item. And, you should define the variable using 6672 the preferred recipe's name (:term:`PN`). Here is a common 6673 example:: 6674 6675 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 6676 6677 In the previous example, multiple recipes are providing "virtual/kernel". 6678 The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of 6679 the recipe you prefer to provide "virtual/kernel". 6680 6681 Here are more examples:: 6682 6683 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" 6684 PREFERRED_PROVIDER_virtual/libgl ?= "mesa" 6685 6686 For more 6687 information, see the ":ref:`dev-manual/new-recipe:using virtual providers`" 6688 section in the Yocto Project Development Tasks Manual. 6689 6690 .. note:: 6691 6692 If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any 6693 recipe that :term:`PROVIDES` that item but is not selected (defined) 6694 by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually 6695 desirable since this mechanism is designed to select between mutually 6696 exclusive alternative providers. 6697 6698 :term:`PREFERRED_PROVIDERS` 6699 See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual. 6700 6701 :term:`PREFERRED_VERSION` 6702 If there are multiple versions of a recipe available, this variable 6703 determines which version should be given preference. You must always 6704 suffix the variable with the :term:`PN` you want to select (`python` in 6705 the first example below), and you should specify the :term:`PV` 6706 accordingly (`3.4.0` in the example). 6707 6708 The :term:`PREFERRED_VERSION` variable supports limited wildcard use 6709 through the "``%``" character. You can use the character to match any 6710 number of characters, which can be useful when specifying versions 6711 that contain long revision numbers that potentially change. Here are 6712 two examples:: 6713 6714 PREFERRED_VERSION_python = "3.4.0" 6715 PREFERRED_VERSION_linux-yocto = "5.0%" 6716 6717 .. note:: 6718 6719 The use of the "%" character is limited in that it only works at the end of the 6720 string. You cannot use the wildcard character in any other 6721 location of the string. 6722 6723 The specified version is matched against :term:`PV`, which 6724 does not necessarily match the version part of the recipe's filename. 6725 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` 6726 where ``foo_git.bb`` contains the following assignment:: 6727 6728 PV = "1.1+git${SRCPV}" 6729 6730 In this case, the correct way to select 6731 ``foo_git.bb`` is by using an assignment such as the following:: 6732 6733 PREFERRED_VERSION_foo = "1.1+git%" 6734 6735 Compare that previous example 6736 against the following incorrect example, which does not work:: 6737 6738 PREFERRED_VERSION_foo = "git" 6739 6740 Sometimes the :term:`PREFERRED_VERSION` variable can be set by 6741 configuration files in a way that is hard to change. You can use 6742 :term:`OVERRIDES` to set a machine-specific 6743 override. Here is an example:: 6744 6745 PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%" 6746 6747 Although not recommended, worst case, you can also use the 6748 "forcevariable" override, which is the strongest override possible. 6749 Here is an example:: 6750 6751 PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%" 6752 6753 .. note:: 6754 6755 The ``:forcevariable`` override is not handled specially. This override 6756 only works because the default value of :term:`OVERRIDES` includes "forcevariable". 6757 6758 If a recipe with the specified version is not available, a warning 6759 message will be shown. See :term:`REQUIRED_VERSION` if you want this 6760 to be an error instead. 6761 6762 :term:`PREMIRRORS` 6763 Specifies additional paths from which the OpenEmbedded build system 6764 gets source code. When the build system searches for source code, it 6765 first tries the local download directory. If that location fails, the 6766 build system tries locations defined by :term:`PREMIRRORS`, the upstream 6767 source, and then locations specified by 6768 :term:`MIRRORS` in that order. 6769 6770 The default value for :term:`PREMIRRORS` is defined in the 6771 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer. 6772 6773 Typically, you could add a specific server for the build system to 6774 attempt before any others by adding something like the following to 6775 the ``local.conf`` configuration file in the 6776 :term:`Build Directory`:: 6777 6778 PREMIRRORS:prepend = "\ 6779 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6780 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6781 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 6782 https://.*/.* &YOCTO_DL_URL;/mirror/sources/" 6783 6784 These changes cause the 6785 build system to intercept Git, FTP, HTTP, and HTTPS requests and 6786 direct them to the ``http://`` sources mirror. You can use 6787 ``file://`` URLs to point to local directories or network shares as 6788 well. 6789 6790 :term:`PRIORITY` 6791 Indicates the importance of a package. 6792 6793 :term:`PRIORITY` is considered to be part of the distribution policy 6794 because the importance of any given recipe depends on the purpose for 6795 which the distribution is being produced. Thus, :term:`PRIORITY` is not 6796 normally set within recipes. 6797 6798 You can set :term:`PRIORITY` to "required", "standard", "extra", and 6799 "optional", which is the default. 6800 6801 :term:`PRIVATE_LIBS` 6802 Specifies libraries installed within a recipe that should be ignored 6803 by the OpenEmbedded build system's shared library resolver. This 6804 variable is typically used when software being built by a recipe has 6805 its own private versions of a library normally provided by another 6806 recipe. In this case, you would not want the package containing the 6807 private libraries to be set as a dependency on other unrelated 6808 packages that should instead depend on the package providing the 6809 standard version of the library. 6810 6811 Libraries specified in this variable should be specified by their 6812 file name. For example, from the Firefox recipe in meta-browser:: 6813 6814 PRIVATE_LIBS = "libmozjs.so \ 6815 libxpcom.so \ 6816 libnspr4.so \ 6817 libxul.so \ 6818 libmozalloc.so \ 6819 libplc4.so \ 6820 libplds4.so" 6821 6822 For more information, see the 6823 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6824 section in the Yocto Project Overview and Concepts Manual. 6825 6826 :term:`PROVIDES` 6827 A list of aliases by which a particular recipe can be known. By 6828 default, a recipe's own :term:`PN` is implicitly already in its 6829 :term:`PROVIDES` list and therefore does not need to mention that it 6830 provides itself. If a recipe uses :term:`PROVIDES`, the additional 6831 aliases are synonyms for the recipe and can be useful for satisfying 6832 dependencies of other recipes during the build as specified by 6833 :term:`DEPENDS`. 6834 6835 Consider the following example :term:`PROVIDES` statement from the recipe 6836 file ``eudev_3.2.9.bb``:: 6837 6838 PROVIDES += "udev" 6839 6840 The :term:`PROVIDES` statement 6841 results in the "eudev" recipe also being available as simply "udev". 6842 6843 .. note:: 6844 6845 A recipe's own recipe name (:term:`PN`) is always implicitly prepended 6846 to :term:`PROVIDES`, so while using "+=" in the above example may not be 6847 strictly necessary it is recommended to avoid confusion. 6848 6849 In addition to providing recipes under alternate names, the 6850 :term:`PROVIDES` mechanism is also used to implement virtual targets. A 6851 virtual target is a name that corresponds to some particular 6852 functionality (e.g. a Linux kernel). Recipes that provide the 6853 functionality in question list the virtual target in :term:`PROVIDES`. 6854 Recipes that depend on the functionality in question can include the 6855 virtual target in :term:`DEPENDS` to leave the choice of provider open. 6856 6857 Conventionally, virtual targets have names on the form 6858 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part 6859 of the name and has no syntactical significance. 6860 6861 The :term:`PREFERRED_PROVIDER` variable is 6862 used to select which particular recipe provides a virtual target. 6863 6864 .. note:: 6865 6866 A corresponding mechanism for virtual runtime dependencies (packages) 6867 exists. However, the mechanism does not depend on any special 6868 functionality beyond ordinary variable assignments. For example, 6869 :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the 6870 package of the component that manages the ``/dev`` directory. 6871 6872 Setting the "preferred provider" for runtime dependencies is as 6873 simple as using the following assignment in a configuration file:: 6874 6875 VIRTUAL-RUNTIME_dev_manager = "udev" 6876 6877 6878 :term:`PRSERV_HOST` 6879 The network based :term:`PR` service host and port. 6880 6881 The ``conf/templates/default/local.conf.sample.extended`` configuration 6882 file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST` 6883 variable is set:: 6884 6885 PRSERV_HOST = "localhost:0" 6886 6887 You must 6888 set the variable if you want to automatically start a local :ref:`PR 6889 service <dev-manual/packages:working with a pr service>`. You can 6890 set :term:`PRSERV_HOST` to other values to use a remote PR service. 6891 6892 :term:`PRSERV_UPSTREAM` 6893 This variable can be used to specify an upstream PR server for the local 6894 PR server to connect to, in the form of ``host:port``. 6895 6896 This makes it possible to implement local fixes to an upstream package. 6897 6898 :term:`PSEUDO_IGNORE_PATHS` 6899 A comma-separated (without spaces) list of path prefixes that should be ignored 6900 by pseudo when monitoring and recording file operations, in order to avoid 6901 problems with files being written to outside of the pseudo context and 6902 reduce pseudo's overhead. A path is ignored if it matches any prefix in the list 6903 and can include partial directory (or file) names. 6904 6905 6906 :term:`PTEST_ENABLED` 6907 Specifies whether or not :ref:`Package 6908 Test <dev-manual/packages:testing packages with ptest>` (ptest) 6909 functionality is enabled when building a recipe. You should not set 6910 this variable directly. Enabling and disabling building Package Tests 6911 at build time should be done by adding "ptest" to (or removing it 6912 from) :term:`DISTRO_FEATURES`. 6913 6914 :term:`PV` 6915 The version of the recipe. The version is normally extracted from the 6916 recipe filename. For example, if the recipe is named 6917 ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1". 6918 :term:`PV` is generally not overridden within a recipe unless it is 6919 building an unstable (i.e. development) version from a source code 6920 repository (e.g. Git or Subversion). 6921 6922 :term:`PV` is the default value of the :term:`PKGV` variable. 6923 6924 :term:`PYPI_PACKAGE` 6925 When inheriting the :ref:`ref-classes-pypi` class, specifies the 6926 `PyPI <https://pypi.org/>`__ package name to be built. The default value 6927 is set based upon :term:`BPN` (stripping any "python-" or "python3-" 6928 prefix off if present), however for some packages it will need to be set 6929 explicitly if that will not match the package name (e.g. where the 6930 package name has a prefix, underscores, uppercase letters etc.) 6931 6932 :term:`PYPI_PACKAGE_EXT` 6933 When inheriting the :ref:`ref-classes-pypi` class, specifies the 6934 file extension to use when fetching a package from `PyPI 6935 <https://pypi.org/>`__. Default is ``tar.gz``. 6936 6937 :term:`PYPI_SRC_URI` 6938 When inheriting the :ref:`ref-classes-pypi` class, specifies the 6939 full `pythonhosted <https://files.pythonhosted.org/>`__ URI for 6940 fetching the package to be built. The default value is constructed 6941 based upon :term:`PYPI_PACKAGE`, :term:`PYPI_PACKAGE_EXT`, and 6942 :term:`PV`. Most recipes will not need to set this variable unless 6943 they are building an unstable (i.e. development) version. 6944 6945 :term:`PYTHON_ABI` 6946 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 6947 class, denotes the Application Binary Interface (ABI) currently in use 6948 for Python. By default, the ABI is "m". You do not have to set this 6949 variable as the OpenEmbedded build system sets it for you. 6950 6951 The OpenEmbedded build system uses the ABI to construct directory 6952 names used when installing the Python headers and libraries in 6953 sysroot (e.g. ``.../python3.3m/...``). 6954 6955 :term:`QA_EMPTY_DIRS` 6956 Specifies a list of directories that are expected to be empty when 6957 packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or 6958 :term:`WARN_QA` these will be checked and an error or warning 6959 (respectively) will be produced. 6960 6961 The default :term:`QA_EMPTY_DIRS` value is set in 6962 :ref:`insane.bbclass <ref-classes-insane>`. 6963 6964 :term:`QA_EMPTY_DIRS_RECOMMENDATION` 6965 Specifies a recommendation for why a directory must be empty, 6966 which will be included in the error message if a specific directory 6967 is found to contain files. Must be overridden with the directory 6968 path to match on. 6969 6970 If no recommendation is specified for a directory, then the default 6971 "but it is expected to be empty" will be used. 6972 6973 An example message shows if files were present in '/dev':: 6974 6975 QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime" 6976 6977 :term:`RANLIB` 6978 The minimal command and arguments to run ``ranlib``. 6979 6980 :term:`RCONFLICTS` 6981 The list of packages that conflict with packages. Note that packages 6982 will not be installed if conflicting packages are not first removed. 6983 6984 Like all package-controlling variables, you must always use them in 6985 conjunction with a package name override. Here is an example:: 6986 6987 RCONFLICTS:${PN} = "another_conflicting_package_name" 6988 6989 BitBake, which the OpenEmbedded build system uses, supports 6990 specifying versioned dependencies. Although the syntax varies 6991 depending on the packaging format, BitBake hides these differences 6992 from you. Here is the general syntax to specify versions with the 6993 :term:`RCONFLICTS` variable:: 6994 6995 RCONFLICTS:${PN} = "package (operator version)" 6996 6997 For ``operator``, you can specify the following: 6998 6999 - = 7000 - < 7001 - > 7002 - <= 7003 - >= 7004 7005 For example, the following sets up a dependency on version 1.2 or 7006 greater of the package ``foo``:: 7007 7008 RCONFLICTS:${PN} = "foo (>= 1.2)" 7009 7010 :term:`RDEPENDS` 7011 Lists runtime dependencies of a package. These dependencies are other 7012 packages that must be installed in order for the package to function 7013 correctly. As an example, the following assignment declares that the 7014 package ``foo`` needs the packages ``bar`` and ``baz`` to be 7015 installed:: 7016 7017 RDEPENDS:foo = "bar baz" 7018 7019 The most common types of package 7020 runtime dependencies are automatically detected and added. Therefore, 7021 most recipes do not need to set :term:`RDEPENDS`. For more information, 7022 see the 7023 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 7024 section in the Yocto Project Overview and Concepts Manual. 7025 7026 The practical effect of the above :term:`RDEPENDS` assignment is that 7027 ``bar`` and ``baz`` will be declared as dependencies inside the 7028 package ``foo`` when it is written out by one of the 7029 :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks. 7030 Exactly how this is done depends on which package format is used, 7031 which is determined by 7032 :term:`PACKAGE_CLASSES`. When the 7033 corresponding package manager installs the package, it will know to 7034 also install the packages on which it depends. 7035 7036 To ensure that the packages ``bar`` and ``baz`` get built, the 7037 previous :term:`RDEPENDS` assignment also causes a task dependency to be 7038 added. This dependency is from the recipe's 7039 :ref:`ref-tasks-build` (not to be confused with 7040 :ref:`ref-tasks-compile`) task to the 7041 :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and 7042 ``baz``. 7043 7044 The names of the packages you list within :term:`RDEPENDS` must be the 7045 names of other packages --- they cannot be recipe names. Although 7046 package names and recipe names usually match, the important point 7047 here is that you are providing package names within the :term:`RDEPENDS` 7048 variable. For an example of the default list of packages created from 7049 a recipe, see the :term:`PACKAGES` variable. 7050 7051 Because the :term:`RDEPENDS` variable applies to packages being built, 7052 you should always use the variable in a form with an attached package 7053 name (remember that a single recipe can build multiple packages). For 7054 example, suppose you are building a development package that depends 7055 on the ``perl`` package. In this case, you would use the following 7056 :term:`RDEPENDS` statement:: 7057 7058 RDEPENDS:${PN}-dev += "perl" 7059 7060 In the example, 7061 the development package depends on the ``perl`` package. Thus, the 7062 :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of 7063 the variable. 7064 7065 .. note:: 7066 7067 ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` 7068 by default. This default is set in the BitBake configuration file 7069 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove 7070 ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator 7071 rather than the "=" operator. 7072 7073 The package names you use with :term:`RDEPENDS` must appear as they would 7074 in the :term:`PACKAGES` variable. The :term:`PKG` variable 7075 allows a different name to be used for the final package (e.g. the 7076 :ref:`ref-classes-debian` class uses this to rename 7077 packages), but this final package name cannot be used with 7078 :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be 7079 independent of the package format used. 7080 7081 BitBake, which the OpenEmbedded build system uses, supports 7082 specifying versioned dependencies. Although the syntax varies 7083 depending on the packaging format, BitBake hides these differences 7084 from you. Here is the general syntax to specify versions with the 7085 :term:`RDEPENDS` variable:: 7086 7087 RDEPENDS:${PN} = "package (operator version)" 7088 7089 For ``operator``, you can specify the following: 7090 7091 - = 7092 - < 7093 - > 7094 - <= 7095 - >= 7096 7097 For version, provide the version number. 7098 7099 .. note:: 7100 7101 You can use :term:`EXTENDPKGV` to provide a full package version 7102 specification. 7103 7104 For example, the following sets up a dependency on version 1.2 or 7105 greater of the package ``foo``:: 7106 7107 RDEPENDS:${PN} = "foo (>= 1.2)" 7108 7109 For information on build-time dependencies, see the :term:`DEPENDS` 7110 variable. You can also see the 7111 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and 7112 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the 7113 BitBake User Manual for additional information on tasks and dependencies. 7114 7115 :term:`RECIPE_MAINTAINER` 7116 This variable defines the name and e-mail address of the maintainer of a 7117 recipe. Such information can be used by human users submitted changes, 7118 and by automated tools to send notifications, for example about 7119 vulnerabilities or source updates. 7120 7121 The variable can be defined in a global distribution :oe_git:`maintainers.inc 7122 </openembedded-core/tree/meta/conf/distro/include/maintainers.inc>` file:: 7123 7124 meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>" 7125 7126 It can also be directly defined in a recipe, 7127 for example in the ``libgpiod`` one:: 7128 7129 RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>" 7130 7131 :term:`RECIPE_NO_UPDATE_REASON` 7132 If a recipe should not be replaced by a more recent upstream version, 7133 putting the reason why in this variable in a recipe allows 7134 ``devtool check-upgrade-status`` command to display it, as explained 7135 in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`" 7136 section. 7137 7138 :term:`RECIPE_SYSROOT` 7139 This variable points to the directory that holds all files populated from 7140 recipes specified in :term:`DEPENDS`. As the name indicates, 7141 think of this variable as a custom root (``/``) for the recipe that will be 7142 used by the compiler in order to find headers and other files needed to complete 7143 its job. 7144 7145 This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET` 7146 according to the type of the recipe and the build target. 7147 7148 To better understand this variable, consider the following examples: 7149 7150 - For ``#include <header.h>``, ``header.h`` should be in ``"${RECIPE_SYSROOT}/usr/include"`` 7151 7152 - For ``-lexample``, ``libexample.so`` should be in ``"${RECIPE_SYSROOT}/lib"`` 7153 or other library sysroot directories. 7154 7155 The default value is ``"${WORKDIR}/recipe-sysroot"``. 7156 Do not modify it. 7157 7158 :term:`RECIPE_SYSROOT_NATIVE` 7159 This is similar to :term:`RECIPE_SYSROOT` but the populated files are from 7160 ``-native`` recipes. This allows a recipe built for the target machine to 7161 use ``native`` tools. 7162 7163 This variable is related to :term:`STAGING_DIR_NATIVE`. 7164 7165 The default value is ``"${WORKDIR}/recipe-sysroot-native"``. 7166 Do not modify it. 7167 7168 :term:`RECIPE_UPGRADE_EXTRA_TASKS` 7169 When upgrading a recipe with ``devtool upgrade``, the variable 7170 :term:`RECIPE_UPGRADE_EXTRA_TASKS` specifies a space-delimited list of 7171 tasks to run after the new sources have been unpacked. 7172 7173 For some recipes, after the new source has been unpacked, additional tasks 7174 may need to be run during an upgrade. A good example of this is recipes 7175 which inherit :ref:`ref-classes-cargo-update-recipe-crates`, where the 7176 `do_update_crates` task needs to be run whenever Cargo.toml/Cargo.lock have 7177 changed in the source. 7178 7179 :term:`REPODIR` 7180 See :term:`bitbake:REPODIR` in the BitBake manual. 7181 7182 :term:`REQUIRED_DISTRO_FEATURES` 7183 When inheriting the :ref:`ref-classes-features_check` 7184 class, this variable identifies distribution features that must exist 7185 in the current configuration in order for the OpenEmbedded build 7186 system to build the recipe. In other words, if the 7187 :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not 7188 appear in :term:`DISTRO_FEATURES` within the current configuration, then 7189 the recipe will be skipped, and if the build system attempts to build 7190 the recipe then an error will be triggered. 7191 7192 :term:`REQUIRED_VERSION` 7193 If there are multiple versions of a recipe available, this variable 7194 determines which version should be given preference. 7195 :term:`REQUIRED_VERSION` works in exactly the same manner as 7196 :term:`PREFERRED_VERSION`, except that if the specified version is not 7197 available then an error message is shown and the build fails 7198 immediately. 7199 7200 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set 7201 for the same recipe, the :term:`REQUIRED_VERSION` value applies. 7202 7203 :term:`RETAIN_DIRS_ALWAYS` 7204 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7205 space-separated recipe-specific directories to always save in a tarball 7206 whether the recipe build has failed or not. 7207 7208 :term:`RETAIN_DIRS_FAILURE` 7209 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7210 space-separated recipe-specific directories to save in a tarball on 7211 failure of the recipe's build. 7212 7213 :term:`RETAIN_DIRS_GLOBAL_ALWAYS` 7214 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7215 space-separated directories that are not specific to a recipe to save in a 7216 tarball whether the build has failed or not. 7217 7218 :term:`RETAIN_DIRS_GLOBAL_FAILURE` 7219 When inheriting the :ref:`ref-classes-retain` class, this variable holds 7220 space-separated directories that are not specific to a recipe to save in a 7221 tarball on build failure. 7222 7223 :term:`RETAIN_ENABLED` 7224 Disables the creation of a tarball of the work directory done by the 7225 :ref:`ref-classes-retain` class. Can be set to specific recipes to disable 7226 the class when the class was inherited globally with :term:`INHERIT`. 7227 7228 :term:`RETAIN_OUTDIR` 7229 When inheriting the :ref:`ref-classes-retain` class, this variable 7230 specifies the directory where to save the tarball of the work directory. 7231 The default directory is ``${TMPDIR}/retain``. 7232 7233 :term:`RETAIN_TARBALL_SUFFIX` 7234 When inheriting the :ref:`ref-classes-retain` class, this variable 7235 specifies the suffix of the tarball of the work directory. The default 7236 suffix is ``${DATETIME}.tar.gz``. 7237 7238 :term:`RM_WORK_EXCLUDE` 7239 With :ref:`ref-classes-rm-work` enabled, this variable 7240 specifies a list of recipes whose work directories should not be removed. 7241 See the ":ref:`ref-classes-rm-work`" section for more details. 7242 7243 :term:`ROOT_HOME` 7244 Defines the root home directory. By default, this directory is set as 7245 follows in the BitBake configuration file:: 7246 7247 ROOT_HOME ??= "/home/root" 7248 7249 .. note:: 7250 7251 This default value is likely used because some embedded solutions 7252 prefer to have a read-only root filesystem and prefer to keep 7253 writeable data in one place. 7254 7255 You can override the default by setting the variable in any layer or 7256 in the ``local.conf`` file. Because the default is set using a "weak" 7257 assignment (i.e. "??="), you can use either of the following forms to 7258 define your override:: 7259 7260 ROOT_HOME = "/root" 7261 ROOT_HOME ?= "/root" 7262 7263 These 7264 override examples use ``/root``, which is probably the most commonly 7265 used override. 7266 7267 :term:`ROOTFS` 7268 Indicates a filesystem image to include as the root filesystem. 7269 7270 The :term:`ROOTFS` variable is an optional variable used with the 7271 :ref:`ref-classes-image-live` class. 7272 7273 :term:`ROOTFS_POSTINSTALL_COMMAND` 7274 Specifies a list of functions to call after the OpenEmbedded build 7275 system has installed packages. You can specify functions separated by 7276 spaces:: 7277 7278 ROOTFS_POSTINSTALL_COMMAND += "function" 7279 7280 If you need to pass the root filesystem path to a command within a 7281 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7282 directory that becomes the root filesystem image. See the 7283 :term:`IMAGE_ROOTFS` variable for more 7284 information. 7285 7286 :term:`ROOTFS_POSTPROCESS_COMMAND` 7287 Specifies a list of functions to call once the OpenEmbedded build 7288 system has created the root filesystem. You can specify functions 7289 separated by spaces:: 7290 7291 ROOTFS_POSTPROCESS_COMMAND += "function" 7292 7293 If you need to pass the root filesystem path to a command within a 7294 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7295 directory that becomes the root filesystem image. See the 7296 :term:`IMAGE_ROOTFS` variable for more 7297 information. 7298 7299 :term:`ROOTFS_POSTUNINSTALL_COMMAND` 7300 Specifies a list of functions to call after the OpenEmbedded build 7301 system has removed unnecessary packages. When runtime package 7302 management is disabled in the image, several packages are removed 7303 including ``base-passwd``, ``shadow``, and ``update-alternatives``. 7304 You can specify functions separated by spaces:: 7305 7306 ROOTFS_POSTUNINSTALL_COMMAND += "function" 7307 7308 If you need to pass the root filesystem path to a command within a 7309 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7310 directory that becomes the root filesystem image. See the 7311 :term:`IMAGE_ROOTFS` variable for more 7312 information. 7313 7314 :term:`ROOTFS_PREPROCESS_COMMAND` 7315 Specifies a list of functions to call before the OpenEmbedded build 7316 system has created the root filesystem. You can specify functions 7317 separated by spaces:: 7318 7319 ROOTFS_PREPROCESS_COMMAND += "function" 7320 7321 If you need to pass the root filesystem path to a command within a 7322 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7323 directory that becomes the root filesystem image. See the 7324 :term:`IMAGE_ROOTFS` variable for more 7325 information. 7326 7327 :term:`RPMBUILD_EXTRA_PARAMS` 7328 Specifies extra user-defined parameters for the ``rpmbuild`` command. 7329 7330 :term:`RPROVIDES` 7331 A list of package name aliases that a package also provides. These 7332 aliases are useful for satisfying runtime dependencies of other 7333 packages both during the build and on the target (as specified by 7334 :term:`RDEPENDS`). 7335 7336 .. note:: 7337 7338 A package's own name is implicitly already in its :term:`RPROVIDES` list. 7339 7340 As with all package-controlling variables, you must always use the 7341 variable in conjunction with a package name override. Here is an 7342 example:: 7343 7344 RPROVIDES:${PN} = "widget-abi-2" 7345 7346 :term:`RRECOMMENDS` 7347 A list of packages that extends the usability of a package being 7348 built. The package being built does not depend on this list of 7349 packages in order to successfully build, but rather uses them for 7350 extended usability. To specify runtime dependencies for packages, see 7351 the :term:`RDEPENDS` variable. 7352 7353 The package manager will automatically install the :term:`RRECOMMENDS` 7354 list of packages when installing the built package. However, you can 7355 prevent listed packages from being installed by using the 7356 :term:`BAD_RECOMMENDATIONS`, 7357 :term:`NO_RECOMMENDATIONS`, and 7358 :term:`PACKAGE_EXCLUDE` variables. 7359 7360 Packages specified in :term:`RRECOMMENDS` need not actually be produced. 7361 However, there must be a recipe providing each package, either 7362 through the :term:`PACKAGES` or 7363 :term:`PACKAGES_DYNAMIC` variables or the 7364 :term:`RPROVIDES` variable, or an error will occur 7365 during the build. If such a recipe does exist and the package is not 7366 produced, the build continues without error. 7367 7368 Because the :term:`RRECOMMENDS` variable applies to packages being built, 7369 you should always attach an override to the variable to specify the 7370 particular package whose usability is being extended. For example, 7371 suppose you are building a development package that is extended to 7372 support wireless functionality. In this case, you would use the 7373 following:: 7374 7375 RRECOMMENDS:${PN}-dev += "wireless_package_name" 7376 7377 In the 7378 example, the package name (``${PN}-dev``) must appear as it would in 7379 the :term:`PACKAGES` namespace before any renaming of the output package 7380 by classes such as :ref:`ref-classes-debian`. 7381 7382 BitBake, which the OpenEmbedded build system uses, supports 7383 specifying versioned recommends. Although the syntax varies depending 7384 on the packaging format, BitBake hides these differences from you. 7385 Here is the general syntax to specify versions with the 7386 :term:`RRECOMMENDS` variable:: 7387 7388 RRECOMMENDS:${PN} = "package (operator version)" 7389 7390 For ``operator``, you can specify the following: 7391 7392 - = 7393 - < 7394 - > 7395 - <= 7396 - >= 7397 7398 For example, the following sets up a recommend on version 1.2 or 7399 greater of the package ``foo``:: 7400 7401 RRECOMMENDS:${PN} = "foo (>= 1.2)" 7402 7403 :term:`RREPLACES` 7404 A list of packages replaced by a package. The package manager uses 7405 this variable to determine which package should be installed to 7406 replace other package(s) during an upgrade. In order to also have the 7407 other package(s) removed at the same time, you must add the name of 7408 the other package to the :term:`RCONFLICTS` variable. 7409 7410 As with all package-controlling variables, you must use this variable 7411 in conjunction with a package name override. Here is an example:: 7412 7413 RREPLACES:${PN} = "other_package_being_replaced" 7414 7415 BitBake, which the OpenEmbedded build system uses, supports 7416 specifying versioned replacements. Although the syntax varies 7417 depending on the packaging format, BitBake hides these differences 7418 from you. Here is the general syntax to specify versions with the 7419 :term:`RREPLACES` variable:: 7420 7421 RREPLACES:${PN} = "package (operator version)" 7422 7423 For ``operator``, you can specify the following: 7424 7425 - = 7426 - < 7427 - > 7428 - <= 7429 - >= 7430 7431 For example, the following sets up a replacement using version 1.2 7432 or greater of the package ``foo``:: 7433 7434 RREPLACES:${PN} = "foo (>= 1.2)" 7435 7436 :term:`RSUGGESTS` 7437 A list of additional packages that you can suggest for installation 7438 by the package manager at the time a package is installed. Not all 7439 package managers support this functionality. 7440 7441 As with all package-controlling variables, you must always use this 7442 variable in conjunction with a package name override. Here is an 7443 example:: 7444 7445 RSUGGESTS:${PN} = "useful_package another_package" 7446 7447 :term:`RUST_CHANNEL` 7448 Specifies which version of Rust to build - "stable", "beta" or "nightly". 7449 The default value is "stable". Set this at your own risk, as values other 7450 than "stable" are not guaranteed to work at a given time. 7451 7452 :term:`S` 7453 The location in the :term:`Build Directory` where 7454 unpacked recipe source code resides. By default, this directory is 7455 ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, 7456 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe 7457 version. If the source tarball extracts the code to a directory named 7458 anything other than ``${BPN}-${PV}``, or if the source code is 7459 fetched from an SCM such as Git or Subversion, then you must set 7460 :term:`S` in the recipe so that the OpenEmbedded build system knows where 7461 to find the unpacked source. 7462 7463 As an example, assume a :term:`Source Directory` 7464 top-level folder named ``poky`` and a default :term:`Build Directory` at 7465 ``poky/build``. In this case, the work directory the build system 7466 uses to keep the unpacked recipe for ``db`` is the following:: 7467 7468 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 7469 7470 The unpacked source code resides in the ``db-5.1.19`` folder. 7471 7472 This next example assumes a Git repository. By default, Git 7473 repositories are cloned to ``${WORKDIR}/git`` during 7474 :ref:`ref-tasks-fetch`. Since this path is different 7475 from the default value of :term:`S`, you must set it specifically so the 7476 source can be located:: 7477 7478 SRC_URI = "git://path/to/repo.git;branch=main" 7479 S = "${WORKDIR}/git" 7480 7481 :term:`SANITY_REQUIRED_UTILITIES` 7482 Specifies a list of command-line utilities that should be checked for 7483 during the initial sanity checking process when running BitBake. If 7484 any of the utilities are not installed on the build host, then 7485 BitBake immediately exits with an error. 7486 7487 :term:`SANITY_TESTED_DISTROS` 7488 A list of the host distribution identifiers that the build system has 7489 been tested against. Identifiers consist of the host distributor ID 7490 followed by the release, as reported by the ``lsb_release`` tool or 7491 as read from ``/etc/lsb-release``. Separate the list items with 7492 explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is 7493 not empty and the current value of 7494 :term:`NATIVELSBSTRING` does not appear in the 7495 list, then the build system reports a warning that indicates the 7496 current host distribution has not been tested as a build host. 7497 7498 :term:`SDK_ARCH` 7499 The target architecture for the SDK. Typically, you do not directly 7500 set this variable. Instead, use :term:`SDKMACHINE`. 7501 7502 :term:`SDK_ARCHIVE_TYPE` 7503 Specifies the type of archive to create for the SDK. Valid values: 7504 7505 - ``tar.xz`` (default) 7506 - ``zip`` 7507 7508 Only one archive type can be specified. 7509 7510 :term:`SDK_BUILDINFO_FILE` 7511 When using the :ref:`ref-classes-image-buildinfo` class, 7512 specifies the file in the SDK to write the build information into. The 7513 default value is "``/buildinfo``". 7514 7515 :term:`SDK_CUSTOM_TEMPLATECONF` 7516 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to 7517 "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory` 7518 (:term:`TOPDIR`) then this will be copied into the SDK. 7519 7520 :term:`SDK_DEPLOY` 7521 The directory set up and used by the 7522 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the 7523 SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>` 7524 class defines :term:`SDK_DEPLOY` as follows:: 7525 7526 SDK_DEPLOY = "${TMPDIR}/deploy/sdk" 7527 7528 :term:`SDK_DIR` 7529 The parent directory used by the OpenEmbedded build system when 7530 creating SDK output. The 7531 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines 7532 the variable as follows:: 7533 7534 SDK_DIR = "${WORKDIR}/sdk" 7535 7536 .. note:: 7537 7538 The :term:`SDK_DIR` directory is a temporary directory as it is part of 7539 :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`. 7540 7541 :term:`SDK_EXT_TYPE` 7542 Controls whether or not shared state artifacts are copied into the 7543 extensible SDK. The default value of "full" copies all of the 7544 required shared state artifacts into the extensible SDK. The value 7545 "minimal" leaves these artifacts out of the SDK. 7546 7547 .. note:: 7548 7549 If you set the variable to "minimal", you need to ensure 7550 :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the 7551 artifacts to be fetched as needed. 7552 7553 :term:`SDK_HOST_MANIFEST` 7554 The manifest file for the host part of the SDK. This file lists all 7555 the installed packages that make up the host part of the SDK. The 7556 file contains package information on a line-per-package basis as 7557 follows:: 7558 7559 packagename packagearch version 7560 7561 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7562 defines the manifest file as follows:: 7563 7564 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" 7565 7566 The location is derived using the :term:`SDK_DEPLOY` and 7567 :term:`TOOLCHAIN_OUTPUTNAME` variables. 7568 7569 :term:`SDK_INCLUDE_PKGDATA` 7570 When set to "1", specifies to include the packagedata for all recipes 7571 in the "world" target in the extensible SDK. Including this data 7572 allows the ``devtool search`` command to find these recipes in search 7573 results, as well as allows the ``devtool add`` command to map 7574 dependencies more effectively. 7575 7576 .. note:: 7577 7578 Enabling the :term:`SDK_INCLUDE_PKGDATA` 7579 variable significantly increases build time because all of world 7580 needs to be built. Enabling the variable also slightly increases 7581 the size of the extensible SDK. 7582 7583 :term:`SDK_INCLUDE_TOOLCHAIN` 7584 When set to "1", specifies to include the toolchain in the extensible 7585 SDK. Including the toolchain is useful particularly when 7586 :term:`SDK_EXT_TYPE` is set to "minimal" to keep 7587 the SDK reasonably small but you still want to provide a usable 7588 toolchain. For example, suppose you want to use the toolchain from an 7589 IDE or from other tools and you do not want to perform additional 7590 steps to install the toolchain. 7591 7592 The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if 7593 :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if 7594 :term:`SDK_EXT_TYPE` is set to "full". 7595 7596 :term:`SDK_NAME` 7597 The base name for SDK output files. The default value (as set in 7598 ``meta-poky/conf/distro/poky.conf``) is derived from the 7599 :term:`DISTRO`, 7600 :term:`TCLIBC`, 7601 :term:`SDKMACHINE`, 7602 :term:`IMAGE_BASENAME`, 7603 :term:`TUNE_PKGARCH`, and 7604 :term:`MACHINE` variables:: 7605 7606 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}" 7607 7608 :term:`SDK_OS` 7609 Specifies the operating system for which the SDK will be built. The 7610 default value is the value of :term:`BUILD_OS`. 7611 7612 :term:`SDK_OUTPUT` 7613 The location used by the OpenEmbedded build system when creating SDK 7614 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 7615 class defines the variable as follows:: 7616 7617 SDK_DIR = "${WORKDIR}/sdk" 7618 SDK_OUTPUT = "${SDK_DIR}/image" 7619 SDK_DEPLOY = "${DEPLOY_DIR}/sdk" 7620 7621 .. note:: 7622 7623 The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of 7624 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is 7625 :term:`SDK_DEPLOY`. 7626 7627 :term:`SDK_PACKAGE_ARCHS` 7628 Specifies a list of architectures compatible with the SDK machine. 7629 This variable is set automatically and should not normally be 7630 hand-edited. Entries are separated using spaces and listed in order 7631 of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any 7632 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". 7633 7634 :term:`SDK_POSTPROCESS_COMMAND` 7635 Specifies a list of functions to call once the OpenEmbedded build 7636 system creates the SDK. You can specify functions separated by 7637 spaces: 7638 7639 SDK_POSTPROCESS_COMMAND += "function" 7640 7641 If you need to pass an SDK path to a command within a function, you 7642 can use ``${SDK_DIR}``, which points to the parent directory used by 7643 the OpenEmbedded build system when creating SDK output. See the 7644 :term:`SDK_DIR` variable for more information. 7645 7646 :term:`SDK_PREFIX` 7647 The toolchain binary prefix used for 7648 :ref:`ref-classes-nativesdk` recipes. The 7649 OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the 7650 :term:`TARGET_PREFIX` when building 7651 ``nativesdk`` recipes. The default value is "${SDK_SYS}-". 7652 7653 :term:`SDK_RECRDEP_TASKS` 7654 A list of shared state tasks added to the extensible SDK. By default, 7655 the following tasks are added: 7656 7657 - :ref:`ref-tasks-populate_lic` 7658 - :ref:`ref-tasks-package_qa` 7659 - :ref:`ref-tasks-populate_sysroot` 7660 - :ref:`ref-tasks-deploy` 7661 7662 Despite the default value of "" for the 7663 :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added 7664 to the SDK. To specify tasks beyond these four, you need to use the 7665 :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional 7666 tasks that are needed in order to build 7667 :term:`SDK_TARGETS`). 7668 7669 :term:`SDK_SYS` 7670 Specifies the system, including the architecture and the operating 7671 system, for which the SDK will be built. 7672 7673 The OpenEmbedded build system automatically sets this variable based 7674 on :term:`SDK_ARCH`, 7675 :term:`SDK_VENDOR`, and 7676 :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS` 7677 variable yourself. 7678 7679 :term:`SDK_TARGET_MANIFEST` 7680 The manifest file for the target part of the SDK. This file lists all 7681 the installed packages that make up the target part of the SDK. The 7682 file contains package information on a line-per-package basis as 7683 follows:: 7684 7685 packagename packagearch version 7686 7687 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7688 defines the manifest file as follows:: 7689 7690 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" 7691 7692 The location is derived using the :term:`SDK_DEPLOY` and 7693 :term:`TOOLCHAIN_OUTPUTNAME` variables. 7694 7695 :term:`SDK_TARGETS` 7696 A list of targets to install from shared state as part of the 7697 standard or extensible SDK installation. The default value is "${PN}" 7698 (i.e. the image from which the SDK is built). 7699 7700 The :term:`SDK_TARGETS` variable is an internal variable and typically 7701 would not be changed. 7702 7703 :term:`SDK_TITLE` 7704 The title to be printed when running the SDK installer. By default, 7705 this title is based on the :term:`DISTRO_NAME` or 7706 :term:`DISTRO` variable and is set in the 7707 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7708 follows:: 7709 7710 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" 7711 7712 For the default distribution "poky", 7713 :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)". 7714 7715 For information on how to change this default title, see the 7716 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" 7717 section in the Yocto Project Application Development and the 7718 Extensible Software Development Kit (eSDK) manual. 7719 7720 :term:`SDK_TOOLCHAIN_LANGS` 7721 Specifies programming languages to support in the SDK, as a 7722 space-separated list. Currently supported items are ``rust`` and ``go``. 7723 7724 :term:`SDK_UPDATE_URL` 7725 An optional URL for an update server for the extensible SDK. If set, 7726 the value is used as the default update server when running 7727 ``devtool sdk-update`` within the extensible SDK. 7728 7729 :term:`SDK_VENDOR` 7730 Specifies the name of the SDK vendor. 7731 7732 :term:`SDK_VERSION` 7733 Specifies the version of the SDK. The Poky distribution configuration file 7734 (``/meta-poky/conf/distro/poky.conf``) sets the default 7735 :term:`SDK_VERSION` as follows:: 7736 7737 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}" 7738 7739 For additional information, see the 7740 :term:`DISTRO_VERSION` and 7741 :term:`METADATA_REVISION` variables. 7742 7743 :term:`SDK_ZIP_OPTIONS` 7744 Specifies extra options to pass to the ``zip`` command when zipping the SDK 7745 (i.e. when :term:`SDK_ARCHIVE_TYPE` is set to "zip"). The default value is 7746 "-y". 7747 7748 :term:`SDKEXTPATH` 7749 The default installation directory for the Extensible SDK. By 7750 default, this directory is based on the :term:`DISTRO` 7751 variable and is set in the 7752 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7753 follows:: 7754 7755 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" 7756 7757 For the 7758 default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk". 7759 7760 For information on how to change this default directory, see the 7761 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" 7762 section in the Yocto Project Application Development and the 7763 Extensible Software Development Kit (eSDK) manual. 7764 7765 :term:`SDKIMAGE_FEATURES` 7766 Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to 7767 the SDK generated from an image using the following command:: 7768 7769 $ bitbake -c populate_sdk imagename 7770 7771 :term:`SDKMACHINE` 7772 The machine for which the SDK is built. In other words, the SDK is built 7773 such that it runs on the target you specify with the :term:`SDKMACHINE` 7774 value. The value points to a corresponding ``.conf`` file under 7775 ``conf/machine-sdk/`` in the enabled layers, for example ``aarch64``, 7776 ``i586``, ``i686``, ``ppc64``, ``ppc64le``, and ``x86_64`` are 7777 :oe_git:`available in OpenEmbedded-Core </openembedded-core/tree/meta/conf/machine-sdk>`. 7778 7779 The variable defaults to :term:`BUILD_ARCH` so that SDKs are built for the 7780 architecture of the build machine. 7781 7782 .. note:: 7783 7784 You cannot set the :term:`SDKMACHINE` 7785 variable in your distribution configuration file. If you do, the 7786 configuration will not take effect. 7787 7788 :term:`SDKPATH` 7789 Defines the path used to collect the SDK components and build the 7790 installer. 7791 7792 :term:`SDKPATHINSTALL` 7793 Defines the path offered to the user for installation of the SDK that 7794 is generated by the OpenEmbedded build system. The path appears as 7795 the default location for installing the SDK when you run the SDK's 7796 installation script. You can override the offered path when you run 7797 the script. 7798 7799 :term:`SDKTARGETSYSROOT` 7800 The full path to the sysroot used for cross-compilation within an SDK 7801 as it will be when installed into the default 7802 :term:`SDKPATHINSTALL`. 7803 7804 :term:`SECTION` 7805 The section in which packages should be categorized. Package 7806 management utilities can make use of this variable. 7807 7808 :term:`SELECTED_OPTIMIZATION` 7809 Specifies the optimization flags passed to the C compiler when 7810 building for the target. The flags are passed through the default 7811 value of the :term:`TARGET_CFLAGS` variable. 7812 7813 The :term:`SELECTED_OPTIMIZATION` variable takes the value of 7814 :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which 7815 case the value of :term:`DEBUG_OPTIMIZATION` is used. 7816 7817 :term:`SERIAL_CONSOLES` 7818 Defines a serial console (TTY) to enable using 7819 :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the 7820 baud rate followed by the TTY device name separated by a semicolon. 7821 Use spaces to separate multiple devices:: 7822 7823 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" 7824 7825 :term:`SETUPTOOLS_BUILD_ARGS` 7826 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7827 class, this variable can be used to specify additional arguments to be 7828 passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task. 7829 7830 :term:`SETUPTOOLS_INSTALL_ARGS` 7831 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7832 class, this variable can be used to specify additional arguments to be 7833 passed to ``setup.py install`` in the ``setuptools3_do_install()`` task. 7834 7835 :term:`SETUPTOOLS_SETUP_PATH` 7836 When used by recipes that inherit the :ref:`ref-classes-setuptools3` 7837 class, this variable should be used to specify the directory in which 7838 the ``setup.py`` file is located if it is not at the root of the source 7839 tree (as specified by :term:`S`). For example, in a recipe where the 7840 sources are fetched from a Git repository and ``setup.py`` is in a 7841 ``python/pythonmodule`` subdirectory, you would have this:: 7842 7843 S = "${WORKDIR}/git" 7844 SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule" 7845 7846 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` 7847 A list of recipe dependencies that should not be used to determine 7848 signatures of tasks from one recipe when they depend on tasks from 7849 another recipe. For example:: 7850 7851 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" 7852 7853 In the previous example, ``intone`` depends on ``mplayer2``. 7854 7855 You can use the special token ``"*"`` on the left-hand side of the 7856 dependency to match all recipes except the one on the right-hand 7857 side. Here is an example:: 7858 7859 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" 7860 7861 In the previous example, all recipes except ``quilt-native`` ignore 7862 task signatures from the ``quilt-native`` recipe when determining 7863 their task signatures. 7864 7865 Use of this variable is one mechanism to remove dependencies that 7866 affect task signatures and thus force rebuilds when a recipe changes. 7867 7868 .. note:: 7869 7870 If you add an inappropriate dependency for a recipe relationship, 7871 the software might break during runtime if the interface of the 7872 second recipe was changed after the first recipe had been built. 7873 7874 :term:`SIGGEN_EXCLUDERECIPES_ABISAFE` 7875 A list of recipes that are completely stable and will never change. 7876 The ABI for the recipes in the list are presented by output from the 7877 tasks run to build the recipe. Use of this variable is one way to 7878 remove dependencies from one recipe on another that affect task 7879 signatures and thus force rebuilds when the recipe changes. 7880 7881 .. note:: 7882 7883 If you add an inappropriate variable to this list, the software 7884 might break at runtime if the interface of the recipe was changed 7885 after the other had been built. 7886 7887 :term:`SIGGEN_LOCKEDSIGS` 7888 The list of locked tasks, with the form:: 7889 7890 SIGGEN_LOCKEDSIGS += "<package>:<task>:<signature>" 7891 7892 If ``<signature>`` exists for the specified ``<task>`` and ``<package>`` 7893 in the sstate cache, BitBake will use the cached output instead of 7894 rebuilding the ``<task>``. If it does not exist, BitBake will build the 7895 ``<task>`` and the sstate cache will be used next time. 7896 7897 Example:: 7898 7899 SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0" 7900 7901 You can obtain the signature of all the tasks for the recipe ``bc`` using:: 7902 7903 bitbake -S none bc 7904 7905 Then you can look at files in ``build/tmp/stamps/<arch>/bc`` and look for 7906 files like: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``. 7907 7908 Alternatively, you can also use :doc:`bblock </dev-manual/bblock>` to 7909 generate this line for you. 7910 7911 :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK` 7912 Specifies the debug level of task signature check. 3 levels are supported: 7913 7914 * ``info``: displays a "Note" message to remind the user that a task is locked 7915 and the current signature matches the locked one. 7916 * ``warn``: displays a "Warning" message if a task is locked and the current 7917 signature does not match the locked one. 7918 * ``error``: same as warn but displays an "Error" message and aborts. 7919 7920 :term:`SIGGEN_LOCKEDSIGS_TYPES` 7921 Allowed overrides for :term:`SIGGEN_LOCKEDSIGS`. This is mainly used 7922 for architecture specific locks. A common value for 7923 :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``:: 7924 7925 SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" 7926 7927 SIGGEN_LOCKEDSIGS_core2-64 += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0" 7928 SIGGEN_LOCKEDSIGS_cortexa57 += "bc:do_compile:12178eb6d55ef602a8fe638e49862fd247e07b228f0f08967697b655bfe4bb61" 7929 7930 Here, the ``do_compile`` task from ``bc`` will be locked only for 7931 ``core2-64`` and ``cortexa57`` but not for other architectures such as 7932 ``mips32r2``. 7933 7934 :term:`SITEINFO_BITS` 7935 Specifies the number of bits for the target system CPU. The value 7936 should be either "32" or "64". 7937 7938 :term:`SITEINFO_ENDIANNESS` 7939 Specifies the endian byte order of the target system. The value 7940 should be either "le" for little-endian or "be" for big-endian. 7941 7942 :term:`SKIP_FILEDEPS` 7943 Enables removal of all files from the "Provides" section of an RPM 7944 package. Removal of these files is required for packages containing 7945 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. 7946 7947 To enable file removal, set the variable to "1" in your 7948 ``conf/local.conf`` configuration file in your: 7949 :term:`Build Directory`:: 7950 7951 SKIP_FILEDEPS = "1" 7952 7953 :term:`SKIP_RECIPE` 7954 Used to prevent the OpenEmbedded build system from building a given 7955 recipe. Specify the :term:`PN` value as a variable flag (``varflag``) 7956 and provide a reason, which will be reported when attempting to 7957 build the recipe. 7958 7959 To prevent a recipe from being built, use the :term:`SKIP_RECIPE` 7960 variable in your ``local.conf`` file or distribution configuration. 7961 Here is an example which prevents ``myrecipe`` from being built:: 7962 7963 SKIP_RECIPE[myrecipe] = "Not supported by our organization." 7964 7965 :term:`SOC_FAMILY` 7966 A colon-separated list grouping together machines based upon the same 7967 family of SoC (System On Chip). You typically set this variable in a 7968 common ``.inc`` file that you include in the configuration files of all 7969 the machines. 7970 7971 .. note:: 7972 7973 You must include ``conf/machine/include/soc-family.inc`` for this 7974 variable to appear in :term:`MACHINEOVERRIDES`. 7975 7976 :term:`SOLIBS` 7977 Defines the suffix for shared libraries used on the target platform. 7978 By default, this suffix is ".so.*" for all Linux-based systems and is 7979 defined in the ``meta/conf/bitbake.conf`` configuration file. 7980 7981 You will see this variable referenced in the default values of 7982 ``FILES:${PN}``. 7983 7984 :term:`SOLIBSDEV` 7985 Defines the suffix for the development symbolic link (symlink) for 7986 shared libraries on the target platform. By default, this suffix is 7987 ".so" for Linux-based systems and is defined in the 7988 ``meta/conf/bitbake.conf`` configuration file. 7989 7990 You will see this variable referenced in the default values of 7991 ``FILES:${PN}-dev``. 7992 7993 :term:`SOURCE_DATE_EPOCH` 7994 This defines a date expressed in number of seconds since 7995 the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by 7996 multiple build systems to force a timestamp in built binaries. 7997 Many upstream projects already support this variable. 7998 7999 You will find more details in the `official specifications 8000 <https://reproducible-builds.org/specs/source-date-epoch/>`__. 8001 8002 A value for each recipe is computed from the sources by 8003 :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`. 8004 8005 If a recipe wishes to override the default behavior, it should set its 8006 own :term:`SOURCE_DATE_EPOCH` value:: 8007 8008 SOURCE_DATE_EPOCH = "1613559011" 8009 8010 :term:`SOURCE_MIRROR_FETCH` 8011 When you are fetching files to create a mirror of sources (i.e. 8012 creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in 8013 your ``local.conf`` configuration file ensures the source for all 8014 recipes are fetched regardless of whether or not a recipe is 8015 compatible with the configuration. A recipe is considered 8016 incompatible with the currently configured machine when either or 8017 both the :term:`COMPATIBLE_MACHINE` 8018 variable and :term:`COMPATIBLE_HOST` variables 8019 specify compatibility with a machine other than that of the current 8020 machine or host. 8021 8022 .. note:: 8023 8024 Do not set the :term:`SOURCE_MIRROR_FETCH` 8025 variable unless you are creating a source mirror. In other words, 8026 do not set the variable during a normal build. 8027 8028 :term:`SOURCE_MIRROR_URL` 8029 Defines your own :term:`PREMIRRORS` from which to 8030 first fetch source before attempting to fetch from the upstream 8031 specified in :term:`SRC_URI`. 8032 8033 To use this variable, you must globally inherit the 8034 :ref:`ref-classes-own-mirrors` class and then provide 8035 the URL to your mirrors. Here is the general syntax:: 8036 8037 INHERIT += "own-mirrors" 8038 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" 8039 8040 .. note:: 8041 8042 You can specify only a single URL in :term:`SOURCE_MIRROR_URL`. 8043 8044 :term:`SPDX_ARCHIVE_PACKAGED` 8045 This option allows to add to :term:`SPDX` output compressed archives 8046 of the files in the generated target packages. 8047 8048 Such archives are available in 8049 ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst`` 8050 under the :term:`Build Directory`. 8051 8052 Enable this option as follows:: 8053 8054 SPDX_ARCHIVE_PACKAGED = "1" 8055 8056 According to our tests on release 4.1 "langdale", building 8057 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this 8058 option multiplied the size of the ``tmp/deploy/spdx`` directory by a 8059 factor of 13 (+1.6 GiB for this image), compared to just using the 8060 :ref:`ref-classes-create-spdx` class with no option. 8061 8062 Note that this option doesn't increase the size of :term:`SPDX` 8063 files in ``tmp/deploy/images/MACHINE``. 8064 8065 :term:`SPDX_ARCHIVE_SOURCES` 8066 This option allows to add to :term:`SPDX` output compressed archives 8067 of the sources for packages installed on the target. It currently 8068 only works when :term:`SPDX_INCLUDE_SOURCES` is set. 8069 8070 This is one way of fulfilling "source code access" license 8071 requirements. 8072 8073 Such source archives are available in 8074 ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst`` 8075 under the :term:`Build Directory`. 8076 8077 Enable this option as follows:: 8078 8079 SPDX_INCLUDE_SOURCES = "1" 8080 SPDX_ARCHIVE_SOURCES = "1" 8081 8082 According to our tests on release 4.1 "langdale", building 8083 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling 8084 these options multiplied the size of the ``tmp/deploy/spdx`` 8085 directory by a factor of 11 (+1.4 GiB for this image), 8086 compared to just using the :ref:`ref-classes-create-spdx` 8087 class with no option. 8088 8089 Note that using this option only marginally increases the size 8090 of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/`` 8091 (+ 0.07\% with the tested image), compared to just enabling 8092 :term:`SPDX_INCLUDE_SOURCES`. 8093 8094 :term:`SPDX_CUSTOM_ANNOTATION_VARS` 8095 This option allows to associate `SPDX annotations 8096 <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe, 8097 using the values of variables in the recipe:: 8098 8099 ANNOTATION1 = "First annotation for recipe" 8100 ANNOTATION2 = "Second annotation for recipe" 8101 SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2" 8102 8103 This will add a new block to the recipe ``.sdpx.json`` output:: 8104 8105 "annotations": [ 8106 { 8107 "annotationDate": "2023-04-18T08:32:12Z", 8108 "annotationType": "OTHER", 8109 "annotator": "Tool: oe-spdx-creator - 1.0", 8110 "comment": "ANNOTATION1=First annotation for recipe" 8111 }, 8112 { 8113 "annotationDate": "2023-04-18T08:32:12Z", 8114 "annotationType": "OTHER", 8115 "annotator": "Tool: oe-spdx-creator - 1.0", 8116 "comment": "ANNOTATION2=Second annotation for recipe" 8117 } 8118 ], 8119 8120 :term:`SPDX_INCLUDE_SOURCES` 8121 This option allows to add a description of the source files used to build 8122 the host tools and the target packages, to the ``spdx.json`` files in 8123 ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`. 8124 As a consequence, the ``spdx.json`` files under the ``by-namespace`` and 8125 ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also 8126 modified to include references to such source file descriptions. 8127 8128 Enable this option as follows:: 8129 8130 SPDX_INCLUDE_SOURCES = "1" 8131 8132 According to our tests on release 4.1 "langdale", building 8133 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling 8134 this option multiplied the total size of the ``tmp/deploy/spdx`` 8135 directory by a factor of 3 (+291 MiB for this image), 8136 and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in 8137 ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this 8138 image), compared to just using the :ref:`ref-classes-create-spdx` class 8139 with no option. 8140 8141 :term:`SPDX_NAMESPACE_PREFIX` 8142 This option could be used in order to change the prefix of ``spdxDocument`` 8143 and the prefix of ``documentNamespace``. It is set by default to 8144 ``http://spdx.org/spdxdoc``. 8145 8146 :term:`SPDX_PRETTY` 8147 This option makes the SPDX output more human-readable, using 8148 identation and newlines, instead of the default output in a 8149 single line:: 8150 8151 SPDX_PRETTY = "1" 8152 8153 The generated SPDX files are approximately 20% bigger, but 8154 this option is recommended if you want to inspect the SPDX 8155 output files with a text editor. 8156 8157 :term:`SPDXLICENSEMAP` 8158 Maps commonly used license names to their SPDX counterparts found in 8159 ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` 8160 mappings, see the ``meta/conf/licenses.conf`` file. 8161 8162 For additional information, see the :term:`LICENSE` 8163 variable. 8164 8165 :term:`SPECIAL_PKGSUFFIX` 8166 A list of prefixes for :term:`PN` used by the OpenEmbedded 8167 build system to create variants of recipes or packages. The list 8168 specifies the prefixes to strip off during certain circumstances such 8169 as the generation of the :term:`BPN` variable. 8170 8171 :term:`SPL_BINARY` 8172 The file type for the Secondary Program Loader (SPL). Some devices 8173 use an SPL from which to boot (e.g. the BeagleBone development 8174 board). For such cases, you can declare the file type of the SPL 8175 binary in the ``u-boot.inc`` include file, which is used in the 8176 U-Boot recipe. 8177 8178 The SPL file type is set to "null" by default in the ``u-boot.inc`` 8179 file as follows:: 8180 8181 # Some versions of u-boot build an SPL (Second Program Loader) image that 8182 # should be packaged along with the u-boot binary as well as placed in the 8183 # deploy directory. For those versions they can set the following variables 8184 # to allow packaging the SPL. 8185 SPL_BINARY ?= "" 8186 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}" 8187 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" 8188 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" 8189 8190 The :term:`SPL_BINARY` variable helps form 8191 various ``SPL_*`` variables used by the OpenEmbedded build system. 8192 8193 See the BeagleBone machine configuration example in the 8194 ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" 8195 section in the Yocto Project Board Support Package Developer's Guide 8196 for additional information. 8197 8198 :term:`SPL_MKIMAGE_DTCOPTS` 8199 Options for the device tree compiler passed to ``mkimage -D`` feature 8200 while creating a FIT image with the :ref:`ref-classes-uboot-sign` 8201 class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the 8202 :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option 8203 to ``mkimage``. 8204 8205 The default value is set to "" by the :ref:`ref-classes-uboot-config` 8206 class. 8207 8208 :term:`SPL_SIGN_ENABLE` 8209 Enable signing of the U-Boot FIT image. The default value is "0". 8210 This variable is used by the :ref:`ref-classes-uboot-sign` class. 8211 8212 :term:`SPL_SIGN_KEYDIR` 8213 Location of the directory containing the RSA key and certificate used for 8214 signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign` 8215 class. 8216 8217 :term:`SPL_SIGN_KEYNAME` 8218 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class 8219 for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR` 8220 directory. If we have for example a ``dev.key`` key and a ``dev.crt`` 8221 certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will 8222 have to set :term:`SPL_SIGN_KEYNAME` to ``dev``. 8223 8224 :term:`SPLASH` 8225 This variable, used by the :ref:`ref-classes-image` class, allows 8226 to choose splashscreen applications. Set it to the names of packages 8227 for such applications to use. This variable is set by default to 8228 ``psplash``. 8229 8230 :term:`SPLASH_IMAGES` 8231 This variable, used by the ``psplash`` recipe, allows to customize 8232 the default splashscreen image. 8233 8234 Specified images in PNG format are converted to ``.h`` files by the recipe, 8235 and are included in the ``psplash`` binary, so you won't find them in 8236 the root filesystem. 8237 8238 To make such a change, it is recommended to customize the 8239 ``psplash`` recipe in a custom layer. Here is an example structure for 8240 an ``ACME`` board:: 8241 8242 meta-acme/recipes-core/psplash 8243 ├── files 8244 │ └── logo-acme.png 8245 └── psplash_%.bbappend 8246 8247 And here are the contents of the ``psplash_%.bbappend`` file in 8248 this example:: 8249 8250 SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default" 8251 FILESEXTRAPATHS:prepend := "${THISDIR}/files:" 8252 8253 You could even add specific configuration options for ``psplash``, 8254 for example:: 8255 8256 EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen" 8257 8258 For information on append files, see the 8259 ":ref:`dev-manual/layers:appending other layers metadata with your layer`" 8260 section. 8261 8262 :term:`SRCREV_FORMAT` 8263 See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual. 8264 8265 :term:`SRC_URI` 8266 8267 See the BitBake manual for the initial description for this variable: 8268 :term:`bitbake:SRC_URI`. 8269 8270 The following features are added by OpenEmbedded and the Yocto Project. 8271 8272 There are standard and recipe-specific options. Here are standard ones: 8273 8274 - ``apply`` --- whether to apply the patch or not. The default 8275 action is to apply the patch. 8276 8277 - ``striplevel`` --- which striplevel to use when applying the 8278 patch. The default level is 1. 8279 8280 - ``patchdir`` --- specifies the directory in which the patch should 8281 be applied. The default is ``${``\ :term:`S`\ ``}``. 8282 8283 Here are options specific to recipes building code from a revision 8284 control system: 8285 8286 - ``mindate`` --- apply the patch only if 8287 :term:`SRCDATE` is equal to or greater than 8288 ``mindate``. 8289 8290 - ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later 8291 than ``maxdate``. 8292 8293 - ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or 8294 greater than ``minrev``. 8295 8296 - ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later 8297 than ``maxrev``. 8298 8299 - ``rev`` --- apply the patch only if :term:`SRCREV` is equal to 8300 ``rev``. 8301 8302 - ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to 8303 ``rev``. 8304 8305 .. note:: 8306 8307 If you want the build system to pick up files specified through 8308 a :term:`SRC_URI` statement from your append file, you need to be 8309 sure to extend the :term:`FILESPATH` variable by also using the 8310 :term:`FILESEXTRAPATHS` variable from within your append file. 8311 8312 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` 8313 By default, the OpenEmbedded build system automatically detects 8314 whether :term:`SRC_URI` contains files that are machine-specific. If so, 8315 the build system automatically changes :term:`PACKAGE_ARCH`. Setting this 8316 variable to "0" disables this behavior. 8317 8318 :term:`SRCDATE` 8319 The date of the source code used to build the package. This variable 8320 applies only if the source was fetched from a Source Code Manager 8321 (SCM). 8322 8323 :term:`SRCPV` 8324 Returns the version string of the current package. This string is 8325 used to help define the value of :term:`PV`. 8326 8327 The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf`` 8328 configuration file in the :term:`Source Directory` as 8329 follows:: 8330 8331 SRCPV = "${@bb.fetch2.get_srcrev(d)}" 8332 8333 Recipes that need to define :term:`PV` do so with the help of the 8334 :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``) 8335 located in ``meta/recipes-connectivity`` in the Source Directory 8336 defines :term:`PV` as follows:: 8337 8338 PV = "0.12-git${SRCPV}" 8339 8340 :term:`SRCREV` 8341 The revision of the source code used to build the package. This 8342 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note 8343 that if you want to build a fixed revision and you want to avoid 8344 performing a query on the remote repository every time BitBake parses 8345 your recipe, you should specify a :term:`SRCREV` that is a full revision 8346 identifier (e.g. the full SHA hash in git) and not just a tag. 8347 8348 .. note:: 8349 8350 For information on limitations when inheriting the latest revision 8351 of software using :term:`SRCREV`, see the :term:`AUTOREV` variable 8352 description and the 8353 ":ref:`dev-manual/packages:automatically incrementing a package version number`" 8354 section, which is in the Yocto Project Development Tasks Manual. 8355 8356 :term:`SRCTREECOVEREDTASKS` 8357 A list of tasks that are typically not relevant (and therefore skipped) 8358 when building using the :ref:`ref-classes-externalsrc` 8359 class. The default value as set in that class file is the set of tasks 8360 that are rarely needed when using external source:: 8361 8362 SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch" 8363 8364 The notable exception is when processing external kernel source as 8365 defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for 8366 aesthetics):: 8367 8368 SRCTREECOVEREDTASKS += "\ 8369 do_validate_branches \ 8370 do_kernel_configcheck \ 8371 do_kernel_checkout \ 8372 do_fetch \ 8373 do_unpack \ 8374 do_patch \ 8375 " 8376 8377 See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` 8378 variables for more information. 8379 8380 :term:`SSTATE_DIR` 8381 The directory for the shared state cache. 8382 8383 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` 8384 This variable allows to specify indirect dependencies to exclude 8385 from sysroots, for example to avoid the situations when a dependency on 8386 any ``-native`` recipe will pull in all dependencies of that recipe 8387 in the recipe sysroot. This behaviour might not always be wanted, 8388 for example when that ``-native`` recipe depends on build tools 8389 that are not relevant for the current recipe. 8390 8391 This way, irrelevant dependencies are ignored, which could have 8392 prevented the reuse of prebuilt artifacts stored in the Shared 8393 State Cache. 8394 8395 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` is evaluated as two regular 8396 expressions of recipe and dependency to ignore. An example 8397 is the rule in :oe_git:`meta/conf/layer.conf </openembedded-core/tree/meta/conf/layer.conf>`:: 8398 8399 # Nothing needs to depend on libc-initial 8400 # base-passwd/shadow-sysroot don't need their dependencies 8401 SSTATE_EXCLUDEDEPS_SYSROOT += "\ 8402 .*->.*-initial.* \ 8403 .*(base-passwd|shadow-sysroot)->.* \ 8404 " 8405 8406 The ``->`` substring represents the dependency between 8407 the two regular expressions. 8408 8409 :term:`SSTATE_MIRROR_ALLOW_NETWORK` 8410 If set to "1", allows fetches from mirrors that are specified in 8411 :term:`SSTATE_MIRRORS` to work even when 8412 fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to 8413 "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if 8414 you have set :term:`SSTATE_MIRRORS` to point to an internal server for 8415 your shared state cache, but you want to disable any other fetching 8416 from the network. 8417 8418 :term:`SSTATE_MIRRORS` 8419 Configures the OpenEmbedded build system to search other mirror 8420 locations for prebuilt cache data objects before building out the 8421 data. This variable works like fetcher :term:`MIRRORS` 8422 and :term:`PREMIRRORS` and points to the cache 8423 locations to check for the shared state (sstate) objects. 8424 8425 You can specify a filesystem directory or a remote URL such as HTTP 8426 or FTP. The locations you specify need to contain the shared state 8427 cache (sstate-cache) results from previous builds. The sstate-cache 8428 you point to can also be from builds on other machines. 8429 8430 When pointing to sstate build artifacts on another machine that uses 8431 a different GCC version for native builds, you must configure 8432 :term:`SSTATE_MIRRORS` with a regular expression that maps local search 8433 paths to server paths. The paths need to take into account 8434 :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class. 8435 For example, the following maps the local search path ``universal-4.9`` 8436 to the server-provided path server_url_sstate_path:: 8437 8438 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) https://server_url_sstate_path/universal-4.8/\1" 8439 8440 If a mirror uses the same structure as 8441 :term:`SSTATE_DIR`, you need to add "PATH" at the 8442 end as shown in the examples below. The build system substitutes the 8443 correct path within the directory structure:: 8444 8445 SSTATE_MIRRORS ?= "\ 8446 file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \ 8447 file://.* file:///some-local-dir/sstate/PATH" 8448 8449 The Yocto Project actually shares the cache data objects built by its 8450 autobuilder:: 8451 8452 SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH" 8453 8454 As such binary artifacts are built for the generic QEMU machines 8455 supported by the various Poky releases, they are less likely to be 8456 reusable in real projects building binaries optimized for a specific 8457 CPU family. 8458 8459 :term:`SSTATE_SCAN_FILES` 8460 Controls the list of files the OpenEmbedded build system scans for 8461 hardcoded installation paths. The variable uses a space-separated 8462 list of filenames (not paths) with standard wildcard characters 8463 allowed. 8464 8465 During a build, the OpenEmbedded build system creates a shared state 8466 (sstate) object during the first stage of preparing the sysroots. 8467 That object is scanned for hardcoded paths for original installation 8468 locations. The list of files that are scanned for paths is controlled 8469 by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files 8470 they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather 8471 than the variable being comprehensively set. The 8472 :ref:`ref-classes-sstate` class specifies the default list of files. 8473 8474 For details on the process, see the :ref:`ref-classes-staging` class. 8475 8476 :term:`STAGING_BASE_LIBDIR_NATIVE` 8477 Specifies the path to the ``/lib`` subdirectory of the sysroot 8478 directory for the build host. 8479 8480 :term:`STAGING_BASELIBDIR` 8481 Specifies the path to the ``/lib`` subdirectory of the sysroot 8482 directory for the target for which the current recipe is being built 8483 (:term:`STAGING_DIR_HOST`). 8484 8485 :term:`STAGING_BINDIR` 8486 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 8487 directory for the target for which the current recipe is being built 8488 (:term:`STAGING_DIR_HOST`). 8489 8490 :term:`STAGING_BINDIR_CROSS` 8491 Specifies the path to the directory containing binary configuration 8492 scripts. These scripts provide configuration information for other 8493 software that wants to make use of libraries or include files 8494 provided by the software associated with the script. 8495 8496 .. note:: 8497 8498 This style of build configuration has been largely replaced by 8499 ``pkg-config``. Consequently, if ``pkg-config`` is supported by the 8500 library to which you are linking, it is recommended you use 8501 ``pkg-config`` instead of a provided configuration script. 8502 8503 :term:`STAGING_BINDIR_NATIVE` 8504 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 8505 directory for the build host. 8506 8507 :term:`STAGING_DATADIR` 8508 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 8509 directory for the target for which the current recipe is being built 8510 (:term:`STAGING_DIR_HOST`). 8511 8512 :term:`STAGING_DATADIR_NATIVE` 8513 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 8514 directory for the build host. 8515 8516 :term:`STAGING_DIR` 8517 Helps construct the ``recipe-sysroots`` directory, which is used 8518 during packaging. 8519 8520 For information on how staging for recipe-specific sysroots occurs, 8521 see the :ref:`ref-tasks-populate_sysroot` 8522 task, the ":ref:`sdk-manual/extensible:sharing files between recipes`" 8523 section in the Yocto Project Development Tasks Manual, the 8524 ":ref:`overview-manual/concepts:configuration, compilation, and staging`" 8525 section in the Yocto Project Overview and Concepts Manual, and the 8526 :term:`SYSROOT_DIRS` variable. 8527 8528 .. note:: 8529 8530 Recipes should never write files directly under the :term:`STAGING_DIR` 8531 directory because the OpenEmbedded build system manages the 8532 directory automatically. Instead, files should be installed to 8533 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` 8534 task and then the OpenEmbedded build system will stage a subset of 8535 those files into the sysroot. 8536 8537 :term:`STAGING_DIR_HOST` 8538 Specifies the path to the sysroot directory for the system on which 8539 the component is built to run (the system that hosts the component). 8540 For most recipes, this sysroot is the one in which that recipe's 8541 :ref:`ref-tasks-populate_sysroot` task copies 8542 files. Exceptions include ``-native`` recipes, where the 8543 :ref:`ref-tasks-populate_sysroot` task instead uses 8544 :term:`STAGING_DIR_NATIVE`. Depending on 8545 the type of recipe and the build target, :term:`STAGING_DIR_HOST` can 8546 have the following values: 8547 8548 - For recipes building for the target machine, the value is 8549 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}". 8550 8551 - For native recipes building for the build host, the value is empty 8552 given the assumption that when building for the build host, the 8553 build host's own directories should be used. 8554 8555 .. note:: 8556 8557 ``-native`` recipes are not installed into host paths like such 8558 as ``/usr``. Rather, these recipes are installed into 8559 :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes, 8560 standard build environment variables such as 8561 :term:`CPPFLAGS` and 8562 :term:`CFLAGS` are set up so that both host paths 8563 and :term:`STAGING_DIR_NATIVE` are searched for libraries and 8564 headers using, for example, GCC's ``-isystem`` option. 8565 8566 Thus, the emphasis is that the ``STAGING_DIR*`` variables 8567 should be viewed as input variables by tasks such as 8568 :ref:`ref-tasks-configure`, 8569 :ref:`ref-tasks-compile`, and 8570 :ref:`ref-tasks-install`. Having the real system 8571 root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense 8572 for ``-native`` recipes, as they make use of host headers and 8573 libraries. 8574 8575 Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`. 8576 8577 :term:`STAGING_DIR_NATIVE` 8578 Specifies the path to the sysroot directory used when building 8579 components that run on the build host itself. 8580 8581 The default value is ``"${RECIPE_SYSROOT_NATIVE}"``, 8582 check :term:`RECIPE_SYSROOT_NATIVE`. 8583 8584 :term:`STAGING_DIR_TARGET` 8585 Specifies the path to the sysroot used for the system for which the 8586 component generates code. For components that do not generate code, 8587 which is the majority, :term:`STAGING_DIR_TARGET` is set to match 8588 :term:`STAGING_DIR_HOST`. 8589 8590 Some recipes build binaries that can run on the target system but those 8591 binaries in turn generate code for another different system (e.g. 8592 :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU, 8593 the primary system is referred to as the "HOST" and the secondary, or 8594 different, system is referred to as the "TARGET". Thus, the binaries 8595 run on the "HOST" system and generate binaries for the "TARGET" 8596 system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used 8597 for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the 8598 sysroot used for the "TARGET" system. 8599 8600 :term:`STAGING_ETCDIR_NATIVE` 8601 Specifies the path to the ``/etc`` subdirectory of the sysroot 8602 directory for the build host. 8603 8604 :term:`STAGING_EXECPREFIXDIR` 8605 Specifies the path to the ``/usr`` subdirectory of the sysroot 8606 directory for the target for which the current recipe is being built 8607 (:term:`STAGING_DIR_HOST`). 8608 8609 :term:`STAGING_INCDIR` 8610 Specifies the path to the ``/usr/include`` subdirectory of the 8611 sysroot directory for the target for which the current recipe being 8612 built (:term:`STAGING_DIR_HOST`). 8613 8614 :term:`STAGING_INCDIR_NATIVE` 8615 Specifies the path to the ``/usr/include`` subdirectory of the 8616 sysroot directory for the build host. 8617 8618 :term:`STAGING_KERNEL_BUILDDIR` 8619 Points to the directory containing the kernel build artifacts. 8620 Recipes building software that needs to access kernel build artifacts 8621 (e.g. ``systemtap-uprobes``) can look in the directory specified with 8622 the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts 8623 after the kernel has been built. 8624 8625 :term:`STAGING_KERNEL_DIR` 8626 The directory with kernel headers that are required to build 8627 out-of-tree modules. 8628 8629 :term:`STAGING_LIBDIR` 8630 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 8631 directory for the target for which the current recipe is being built 8632 (:term:`STAGING_DIR_HOST`). 8633 8634 :term:`STAGING_LIBDIR_NATIVE` 8635 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 8636 directory for the build host. 8637 8638 :term:`STAMP` 8639 Specifies the base path used to create recipe stamp files. The path 8640 to an actual stamp file is constructed by evaluating this string and 8641 then appending additional information. Currently, the default 8642 assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf`` 8643 file is:: 8644 8645 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" 8646 8647 For information on how BitBake uses stamp files to determine if a 8648 task should be rerun, see the 8649 ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`" 8650 section in the Yocto Project Overview and Concepts Manual. 8651 8652 See :term:`STAMPS_DIR`, 8653 :term:`MULTIMACH_TARGET_SYS`, 8654 :term:`PN`, :term:`EXTENDPE`, 8655 :term:`PV`, and :term:`PR` for related variable 8656 information. 8657 8658 :term:`STAMPCLEAN` 8659 See :term:`bitbake:STAMPCLEAN` in the BitBake manual. 8660 8661 :term:`STAMPS_DIR` 8662 Specifies the base directory in which the OpenEmbedded build system 8663 places stamps. The default directory is ``${TMPDIR}/stamps``. 8664 8665 :term:`STRIP` 8666 The minimal command and arguments to run ``strip``, which is used to 8667 strip symbols. 8668 8669 :term:`SUMMARY` 8670 The short (72 characters or less) summary of the binary package for 8671 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, 8672 :term:`SUMMARY` is used to define the 8673 :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is 8674 not set in the recipe. 8675 8676 :term:`SVNDIR` 8677 The directory in which files checked out of a Subversion system are 8678 stored. 8679 8680 :term:`SYSLINUX_DEFAULT_CONSOLE` 8681 Specifies the kernel boot default console. If you want to use a 8682 console other than the default, set this variable in your recipe as 8683 follows where "X" is the console number you want to use:: 8684 8685 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" 8686 8687 The :ref:`ref-classes-syslinux` class initially sets 8688 this variable to null but then checks for a value later. 8689 8690 :term:`SYSLINUX_OPTS` 8691 Lists additional options to add to the syslinux file. You need to set 8692 this variable in your recipe. If you want to list multiple options, 8693 separate the options with a semicolon character (``;``). 8694 8695 The :ref:`ref-classes-syslinux` class uses this variable 8696 to create a set of options. 8697 8698 :term:`SYSLINUX_SERIAL` 8699 Specifies the alternate serial port or turns it off. To turn off 8700 serial, set this variable to an empty string in your recipe. The 8701 variable's default value is set in the 8702 :ref:`ref-classes-syslinux` class as follows:: 8703 8704 SYSLINUX_SERIAL ?= "0 115200" 8705 8706 The class checks for and uses the variable as needed. 8707 8708 :term:`SYSLINUX_SERIAL_TTY` 8709 Specifies the alternate console=tty... kernel boot argument. The 8710 variable's default value is set in the :ref:`ref-classes-syslinux` 8711 class as follows:: 8712 8713 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" 8714 8715 The class checks for and uses the variable as needed. 8716 8717 :term:`SYSLINUX_SPLASH` 8718 An ``.LSS`` file used as the background for the VGA boot menu when 8719 you use the boot menu. You need to set this variable in your recipe. 8720 8721 The :ref:`ref-classes-syslinux` class checks for this 8722 variable and if found, the OpenEmbedded build system installs the 8723 splash screen. 8724 8725 :term:`SYSROOT_DESTDIR` 8726 Points to the temporary directory under the work directory (default 8727 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``") 8728 where the files populated into the sysroot are assembled during the 8729 :ref:`ref-tasks-populate_sysroot` task. 8730 8731 :term:`SYSROOT_DIRS` 8732 Directories that are staged into the sysroot by the 8733 :ref:`ref-tasks-populate_sysroot` task. By 8734 default, the following directories are staged:: 8735 8736 SYSROOT_DIRS = " \ 8737 ${includedir} \ 8738 ${libdir} \ 8739 ${base_libdir} \ 8740 ${nonarch_base_libdir} \ 8741 ${datadir} \ 8742 /sysroot-only \ 8743 " 8744 8745 Consider the following example in which you need to manipulate this variable. 8746 Assume you have a recipe ``A`` that provides a shared library ``.so.*`` that is 8747 installed into a custom folder other than "``${libdir}``" 8748 or "``${base_libdir}``", let's say "``/opt/lib``". 8749 8750 .. note:: 8751 8752 This is not a recommended way to deal with shared libraries, but this 8753 is just to show the usefulness of setting :term:`SYSROOT_DIRS`. 8754 8755 When a recipe ``B`` :term:`DEPENDS` on ``A``, it means what is in 8756 :term:`SYSROOT_DIRS` will be copied from :term:`D` of the recipe ``A`` 8757 into ``B``'s :term:`SYSROOT_DESTDIR` that is "``${WORKDIR}/sysroot-destdir``". 8758 8759 Now, since ``/opt/lib`` is not in :term:`SYSROOT_DIRS`, it will never be copied to 8760 ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So, 8761 the linking process will fail. 8762 8763 To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`:: 8764 8765 SYSROOT_DIRS:append = " /opt/lib" 8766 8767 .. note:: 8768 Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail 8769 because the linker does not know that location, since :term:`TARGET_LDFLAGS` 8770 doesn't contain it (if your recipe is for the target). Therefore, so you should add:: 8771 8772 TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib" 8773 8774 :term:`SYSROOT_DIRS_IGNORE` 8775 Directories that are not staged into the sysroot by the 8776 :ref:`ref-tasks-populate_sysroot` task. You 8777 can use this variable to exclude certain subdirectories of 8778 directories listed in :term:`SYSROOT_DIRS` from 8779 staging. By default, the following directories are not staged:: 8780 8781 SYSROOT_DIRS_IGNORE = " \ 8782 ${mandir} \ 8783 ${docdir} \ 8784 ${infodir} \ 8785 ${datadir}/X11/locale \ 8786 ${datadir}/applications \ 8787 ${datadir}/bash-completion \ 8788 ${datadir}/fonts \ 8789 ${datadir}/gtk-doc/html \ 8790 ${datadir}/installed-tests \ 8791 ${datadir}/locale \ 8792 ${datadir}/pixmaps \ 8793 ${datadir}/terminfo \ 8794 ${libdir}/${BPN}/ptest \ 8795 " 8796 8797 :term:`SYSROOT_DIRS_NATIVE` 8798 Extra directories staged into the sysroot by the 8799 :ref:`ref-tasks-populate_sysroot` task for 8800 ``-native`` recipes, in addition to those specified in 8801 :term:`SYSROOT_DIRS`. By default, the following 8802 extra directories are staged:: 8803 8804 SYSROOT_DIRS_NATIVE = " \ 8805 ${bindir} \ 8806 ${sbindir} \ 8807 ${base_bindir} \ 8808 ${base_sbindir} \ 8809 ${libexecdir} \ 8810 ${sysconfdir} \ 8811 ${localstatedir} \ 8812 " 8813 8814 .. note:: 8815 8816 Programs built by ``-native`` recipes run directly from the sysroot 8817 (:term:`STAGING_DIR_NATIVE`), which is why additional directories 8818 containing program executables and supporting files need to be staged. 8819 8820 :term:`SYSROOT_PREPROCESS_FUNCS` 8821 A list of functions to execute after files are staged into the 8822 sysroot. These functions are usually used to apply additional 8823 processing on the staged files, or to stage additional files. 8824 8825 :term:`SYSTEMD_AUTO_ENABLE` 8826 When inheriting the :ref:`ref-classes-systemd` class, 8827 this variable specifies whether the specified service in 8828 :term:`SYSTEMD_SERVICE` should start 8829 automatically or not. By default, the service is enabled to 8830 automatically start at boot time. The default setting is in the 8831 :ref:`ref-classes-systemd` class as follows:: 8832 8833 SYSTEMD_AUTO_ENABLE ??= "enable" 8834 8835 You can disable the service by setting the variable to "disable". 8836 8837 :term:`SYSTEMD_BOOT_CFG` 8838 When :term:`EFI_PROVIDER` is set to 8839 "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the 8840 configuration file that should be used. By default, the 8841 :ref:`ref-classes-systemd-boot` class sets the 8842 :term:`SYSTEMD_BOOT_CFG` as follows:: 8843 8844 SYSTEMD_BOOT_CFG ?= "${S}/loader.conf" 8845 8846 For information on Systemd-boot, see the `Systemd-boot 8847 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8848 8849 :term:`SYSTEMD_BOOT_ENTRIES` 8850 When :term:`EFI_PROVIDER` is set to 8851 "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a 8852 list of entry files (``*.conf``) to install that contain one boot 8853 entry per file. By default, the :ref:`ref-classes-systemd-boot` class 8854 sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows:: 8855 8856 SYSTEMD_BOOT_ENTRIES ?= "" 8857 8858 For information on Systemd-boot, see the `Systemd-boot 8859 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8860 8861 :term:`SYSTEMD_BOOT_TIMEOUT` 8862 When :term:`EFI_PROVIDER` is set to 8863 "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the 8864 boot menu timeout in seconds. By default, the 8865 :ref:`ref-classes-systemd-boot` class sets the 8866 :term:`SYSTEMD_BOOT_TIMEOUT` as follows:: 8867 8868 SYSTEMD_BOOT_TIMEOUT ?= "10" 8869 8870 For information on Systemd-boot, see the `Systemd-boot 8871 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8872 8873 :term:`SYSTEMD_DEFAULT_TARGET` 8874 8875 This variable allows to set the default unit that systemd starts at bootup. 8876 Usually, this is either ``multi-user.target`` or ``graphical.target``. 8877 This works by creating a ``default.target`` symbolic link to the chosen systemd 8878 target file. 8879 8880 See `systemd's documentation 8881 <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__ 8882 for details. 8883 8884 For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb 8885 </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>` 8886 recipe:: 8887 8888 SYSTEMD_DEFAULT_TARGET = "graphical.target" 8889 8890 :term:`SYSTEMD_PACKAGES` 8891 When inheriting the :ref:`ref-classes-systemd` class, 8892 this variable locates the systemd unit files when they are not found 8893 in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES` 8894 variable is set such that the systemd unit files are assumed to 8895 reside in the recipes main package:: 8896 8897 SYSTEMD_PACKAGES ?= "${PN}" 8898 8899 If these unit files are not in this recipe's main package, you need 8900 to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which 8901 the build system can find the systemd unit files. 8902 8903 :term:`SYSTEMD_SERVICE` 8904 When inheriting the :ref:`ref-classes-systemd` class, 8905 this variable specifies the systemd service name for a package. 8906 8907 Multiple services can be specified, each one separated by a space. 8908 8909 When you specify this file in your recipe, use a package name 8910 override to indicate the package to which the value applies. Here is 8911 an example from the connman recipe:: 8912 8913 SYSTEMD_SERVICE:${PN} = "connman.service" 8914 8915 The package overrides that can be specified are directly related to the value of 8916 :term:`SYSTEMD_PACKAGES`. Overrides not included in :term:`SYSTEMD_PACKAGES` 8917 will be silently ignored. 8918 8919 :term:`SYSVINIT_ENABLED_GETTYS` 8920 When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, 8921 specifies a space-separated list of the virtual terminals that should 8922 run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming 8923 :term:`USE_VT` is not set to "0". 8924 8925 The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only 8926 run a getty on the first virtual terminal). 8927 8928 :term:`T` 8929 This variable points to a directory were BitBake places temporary 8930 files, which consist mostly of task logs and scripts, when building a 8931 particular recipe. The variable is typically set as follows:: 8932 8933 T = "${WORKDIR}/temp" 8934 8935 The :term:`WORKDIR` is the directory into which 8936 BitBake unpacks and builds the recipe. The default ``bitbake.conf`` 8937 file sets this variable. 8938 8939 The :term:`T` variable is not to be confused with the 8940 :term:`TMPDIR` variable, which points to the root of 8941 the directory tree where BitBake places the output of an entire 8942 build. 8943 8944 :term:`TARGET_ARCH` 8945 The target machine's architecture. The OpenEmbedded build system 8946 supports many architectures. Here is an example list of architectures 8947 supported. This list is by no means complete as the architecture is 8948 configurable: 8949 8950 - arm 8951 - i586 8952 - x86_64 8953 - powerpc 8954 - powerpc64 8955 - mips 8956 - mipsel 8957 8958 For additional information on machine architectures, see the 8959 :term:`TUNE_ARCH` variable. 8960 8961 :term:`TARGET_AS_ARCH` 8962 Specifies architecture-specific assembler flags for the target 8963 system. :term:`TARGET_AS_ARCH` is initialized from 8964 :term:`TUNE_ASARGS` by default in the BitBake 8965 configuration file (``meta/conf/bitbake.conf``):: 8966 8967 TARGET_AS_ARCH = "${TUNE_ASARGS}" 8968 8969 :term:`TARGET_CC_ARCH` 8970 Specifies architecture-specific C compiler flags for the target 8971 system. :term:`TARGET_CC_ARCH` is initialized from 8972 :term:`TUNE_CCARGS` by default. 8973 8974 .. note:: 8975 8976 It is a common workaround to append :term:`LDFLAGS` to 8977 :term:`TARGET_CC_ARCH` in recipes that build software for the target that 8978 would not otherwise respect the exported :term:`LDFLAGS` variable. 8979 8980 :term:`TARGET_CC_KERNEL_ARCH` 8981 This is a specific kernel compiler flag for a CPU or Application 8982 Binary Interface (ABI) tune. The flag is used rarely and only for 8983 cases where a userspace :term:`TUNE_CCARGS` is not 8984 compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH` 8985 variable allows the kernel (and associated modules) to use a 8986 different configuration. See the 8987 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the 8988 :term:`Source Directory` for an example. 8989 8990 :term:`TARGET_CFLAGS` 8991 Specifies the flags to pass to the C compiler when building for the 8992 target. When building in the target context, 8993 :term:`CFLAGS` is set to the value of this variable by 8994 default. 8995 8996 Additionally, the SDK's environment setup script sets the :term:`CFLAGS` 8997 variable in the environment to the :term:`TARGET_CFLAGS` value so that 8998 executables built using the SDK also have the flags applied. 8999 9000 :term:`TARGET_CPPFLAGS` 9001 Specifies the flags to pass to the C pre-processor (i.e. to both the 9002 C and the C++ compilers) when building for the target. When building 9003 in the target context, :term:`CPPFLAGS` is set to the 9004 value of this variable by default. 9005 9006 Additionally, the SDK's environment setup script sets the 9007 :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS` 9008 value so that executables built using the SDK also have the flags 9009 applied. 9010 9011 :term:`TARGET_CXXFLAGS` 9012 Specifies the flags to pass to the C++ compiler when building for the 9013 target. When building in the target context, 9014 :term:`CXXFLAGS` is set to the value of this variable 9015 by default. 9016 9017 Additionally, the SDK's environment setup script sets the 9018 :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS` 9019 value so that executables built using the SDK also have the flags 9020 applied. 9021 9022 :term:`TARGET_DBGSRC_DIR` 9023 Specifies the target path to debug source files. The default is 9024 ``/usr/src/debug/${PN}/${PV}``. 9025 9026 :term:`TARGET_FPU` 9027 Specifies the method for handling FPU code. For FPU-less targets, 9028 which include most ARM CPUs, the variable must be set to "soft". If 9029 not, the kernel emulation gets used, which results in a performance 9030 penalty. 9031 9032 :term:`TARGET_LD_ARCH` 9033 Specifies architecture-specific linker flags for the target system. 9034 :term:`TARGET_LD_ARCH` is initialized from 9035 :term:`TUNE_LDARGS` by default in the BitBake 9036 configuration file (``meta/conf/bitbake.conf``):: 9037 9038 TARGET_LD_ARCH = "${TUNE_LDARGS}" 9039 9040 :term:`TARGET_LDFLAGS` 9041 Specifies the flags to pass to the linker when building for the 9042 target. When building in the target context, 9043 :term:`LDFLAGS` is set to the value of this variable 9044 by default. 9045 9046 Additionally, the SDK's environment setup script sets the 9047 :term:`LDFLAGS` variable in the environment to the 9048 :term:`TARGET_LDFLAGS` value so that executables built using the SDK also 9049 have the flags applied. 9050 9051 :term:`TARGET_OS` 9052 Specifies the target's operating system. The variable can be set to 9053 "linux" for glibc-based systems (GNU C Library) and to "linux-musl" 9054 for musl libc. For ARM/EABI targets, the possible values are 9055 "linux-gnueabi" and "linux-musleabi". 9056 9057 :term:`TARGET_PREFIX` 9058 Specifies the prefix used for the toolchain binary target tools. 9059 9060 Depending on the type of recipe and the build target, 9061 :term:`TARGET_PREFIX` is set as follows: 9062 9063 - For recipes building for the target machine, the value is 9064 "${:term:`TARGET_SYS`}-". 9065 9066 - For native recipes, the build system sets the variable to the 9067 value of :term:`BUILD_PREFIX`. 9068 9069 - For native SDK recipes (:ref:`ref-classes-nativesdk`), 9070 the build system sets the variable to the value of :term:`SDK_PREFIX`. 9071 9072 :term:`TARGET_SYS` 9073 Specifies the system, including the architecture and the operating 9074 system, for which the build is occurring in the context of the 9075 current recipe. 9076 9077 The OpenEmbedded build system automatically sets this variable based 9078 on :term:`TARGET_ARCH`, 9079 :term:`TARGET_VENDOR`, and 9080 :term:`TARGET_OS` variables. 9081 9082 .. note:: 9083 9084 You do not need to set the :term:`TARGET_SYS` variable yourself. 9085 9086 Consider these two examples: 9087 9088 - Given a native recipe on a 32-bit, x86 machine running Linux, the 9089 value is "i686-linux". 9090 9091 - Given a recipe being built for a little-endian, MIPS target 9092 running Linux, the value might be "mipsel-linux". 9093 9094 :term:`TARGET_VENDOR` 9095 Specifies the name of the target vendor. 9096 9097 :term:`TCLIBC` 9098 Specifies the GNU standard C library (``libc``) variant to use during 9099 the build process. 9100 9101 You can select "glibc", "musl", "newlib", or "baremetal". 9102 9103 :term:`TCMODE` 9104 Specifies the toolchain selector. :term:`TCMODE` controls the 9105 characteristics of the generated packages and images by telling the 9106 OpenEmbedded build system which toolchain profile to use. By default, 9107 the OpenEmbedded build system builds its own internal toolchain. The 9108 variable's default value is "default", which uses that internal 9109 toolchain. 9110 9111 .. note:: 9112 9113 If :term:`TCMODE` is set to a value other than "default", then it is your 9114 responsibility to ensure that the toolchain is compatible with the 9115 default toolchain. Using older or newer versions of these 9116 components might cause build problems. See 9117 :doc:`Release Information </migration-guides/index>` for your 9118 version of the Yocto Project, to find the specific components with 9119 which the toolchain must be compatible. 9120 9121 The :term:`TCMODE` variable is similar to :term:`TCLIBC`, 9122 which controls the variant of the GNU standard C library (``libc``) 9123 used during the build process: ``glibc`` or ``musl``. 9124 9125 With additional layers, it is possible to use a pre-compiled external 9126 toolchain. One example is the Sourcery G++ Toolchain. The support for 9127 this toolchain resides in the separate Mentor Graphics 9128 ``meta-sourcery`` layer at 9129 https://github.com/MentorEmbedded/meta-sourcery/. 9130 9131 The layer's ``README`` file contains information on how to use the 9132 Sourcery G++ Toolchain as an external toolchain. You will have to 9133 add the layer to your ``bblayers.conf`` file and then set the 9134 :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to 9135 the location of the toolchain. 9136 9137 The fundamentals used for this example apply to any external 9138 toolchain. You can use ``meta-sourcery`` as a template for adding 9139 support for other external toolchains. 9140 9141 In addition to toolchain configuration, you will also need a 9142 corresponding toolchain recipe file. This recipe file needs to package 9143 up any pre-built objects in the toolchain such as ``libgcc``, 9144 ``libstdcc++``, any locales, and ``libc``. 9145 9146 :term:`TC_CXX_RUNTIME` 9147 Specifies the C/C++ STL and runtime variant to use during 9148 the build process. Default value is 'gnu' 9149 9150 You can select "gnu", "llvm", or "android". 9151 9152 :term:`TEMPLATECONF` 9153 Specifies the directory used by the build system to find templates 9154 from which to build the ``bblayers.conf`` and ``local.conf`` files. 9155 Use this variable if you wish to customize such files, and the default 9156 BitBake targets shown when sourcing the ``oe-init-build-env`` script. 9157 9158 For details, see the 9159 :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory` 9160 section in the Yocto Project Development Tasks manual. 9161 9162 .. note:: 9163 9164 You must set this variable in the external environment in order 9165 for it to work. 9166 9167 :term:`TEST_EXPORT_DIR` 9168 The location the OpenEmbedded build system uses to export tests when 9169 the :term:`TEST_EXPORT_ONLY` variable is set 9170 to "1". 9171 9172 The :term:`TEST_EXPORT_DIR` variable defaults to 9173 ``"${TMPDIR}/testimage/${PN}"``. 9174 9175 :term:`TEST_EXPORT_ONLY` 9176 Specifies to export the tests only. Set this variable to "1" if you 9177 do not want to run the tests but you want them to be exported in a 9178 manner that you to run them outside of the build system. 9179 9180 :term:`TEST_LOG_DIR` 9181 Holds the SSH log and the boot log for QEMU machines. The 9182 :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``. 9183 9184 .. note:: 9185 9186 Actual test results reside in the task log (``log.do_testimage``), 9187 which is in the ``${WORKDIR}/temp/`` directory. 9188 9189 :term:`TEST_POWERCONTROL_CMD` 9190 For automated hardware testing, specifies the command to use to 9191 control the power of the target machine under test. Typically, this 9192 command would point to a script that performs the appropriate action 9193 (e.g. interacting with a web-enabled power strip). The specified 9194 command should expect to receive as the last argument "off", "on" or 9195 "cycle" specifying to power off, on, or cycle (power off and then 9196 power on) the device, respectively. 9197 9198 :term:`TEST_POWERCONTROL_EXTRA_ARGS` 9199 For automated hardware testing, specifies additional arguments to 9200 pass through to the command specified in 9201 :term:`TEST_POWERCONTROL_CMD`. Setting 9202 :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you 9203 wish, for example, to separate the machine-specific and 9204 non-machine-specific parts of the arguments. 9205 9206 :term:`TEST_QEMUBOOT_TIMEOUT` 9207 The time in seconds allowed for an image to boot before automated 9208 runtime tests begin to run against an image. The default timeout 9209 period to allow the boot process to reach the login prompt is 500 9210 seconds. You can specify a different value in the ``local.conf`` 9211 file. 9212 9213 For more information on testing images, see the 9214 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" 9215 section in the Yocto Project Development Tasks Manual. 9216 9217 :term:`TEST_SERIALCONTROL_CMD` 9218 For automated hardware testing, specifies the command to use to 9219 connect to the serial console of the target machine under test. This 9220 command simply needs to connect to the serial console and forward 9221 that connection to standard input and output as any normal terminal 9222 program does. 9223 9224 For example, to use the Picocom terminal program on serial device 9225 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: 9226 9227 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" 9228 9229 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` 9230 For automated hardware testing, specifies additional arguments to 9231 pass through to the command specified in 9232 :term:`TEST_SERIALCONTROL_CMD`. Setting 9233 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you 9234 wish, for example, to separate the machine-specific and 9235 non-machine-specific parts of the command. 9236 9237 :term:`TEST_SERVER_IP` 9238 The IP address of the build machine (host machine). This IP address 9239 is usually automatically detected. However, if detection fails, this 9240 variable needs to be set to the IP address of the build machine (i.e. 9241 where the build is taking place). 9242 9243 .. note:: 9244 9245 The :term:`TEST_SERVER_IP` variable is only used for a small number of 9246 tests such as the "dnf" test suite, which needs to download packages 9247 from ``WORKDIR/oe-rootfs-repo``. 9248 9249 :term:`TEST_SUITES` 9250 An ordered list of tests (modules) to run against an image when 9251 performing automated runtime testing. 9252 9253 The OpenEmbedded build system provides a core set of tests that can 9254 be used against images. 9255 9256 .. note:: 9257 9258 Currently, there is only support for running these tests under 9259 QEMU. 9260 9261 Tests include ``ping``, ``ssh``, ``df`` among others. You can add 9262 your own tests to the list of tests by appending :term:`TEST_SUITES` as 9263 follows:: 9264 9265 TEST_SUITES:append = " mytest" 9266 9267 Alternatively, you can 9268 provide the "auto" option to have all applicable tests run against 9269 the image:: 9270 9271 TEST_SUITES:append = " auto" 9272 9273 Using this option causes the 9274 build system to automatically run tests that are applicable to the 9275 image. Tests that are not applicable are skipped. 9276 9277 The order in which tests are run is important. Tests that depend on 9278 another test must appear later in the list than the test on which 9279 they depend. For example, if you append the list of tests with two 9280 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on 9281 ``test_A``, then you must order the tests as follows:: 9282 9283 TEST_SUITES = "test_A test_B" 9284 9285 For more information on testing images, see the 9286 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" 9287 section in the Yocto Project Development Tasks Manual. 9288 9289 :term:`TEST_TARGET` 9290 Specifies the target controller to use when running tests against a 9291 test image. The default controller to use is "qemu":: 9292 9293 TEST_TARGET = "qemu" 9294 9295 A target controller is a class that defines how an image gets 9296 deployed on a target and how a target is started. A layer can extend 9297 the controllers by adding a module in the layer's 9298 ``/lib/oeqa/controllers`` directory and by inheriting the 9299 ``BaseTarget`` class, which is an abstract class that cannot be used 9300 as a value of :term:`TEST_TARGET`. 9301 9302 You can provide the following arguments with :term:`TEST_TARGET`: 9303 9304 - *"qemu":* Boots a QEMU image and runs the tests. See the 9305 ":ref:`dev-manual/runtime-testing:enabling runtime tests on qemu`" section 9306 in the Yocto Project Development Tasks Manual for more 9307 information. 9308 9309 - *"simpleremote":* Runs the tests on target hardware that is 9310 already up and running. The hardware can be on the network or it 9311 can be a device running an image on QEMU. You must also set 9312 :term:`TEST_TARGET_IP` when you use 9313 "simpleremote". 9314 9315 .. note:: 9316 9317 This argument is defined in 9318 ``meta/lib/oeqa/controllers/simpleremote.py``. 9319 9320 For information on running tests on hardware, see the 9321 ":ref:`dev-manual/runtime-testing:enabling runtime tests on hardware`" 9322 section in the Yocto Project Development Tasks Manual. 9323 9324 :term:`TEST_TARGET_IP` 9325 The IP address of your hardware under test. The :term:`TEST_TARGET_IP` 9326 variable has no effect when :term:`TEST_TARGET` is 9327 set to "qemu". 9328 9329 When you specify the IP address, you can also include a port. Here is 9330 an example:: 9331 9332 TEST_TARGET_IP = "192.168.1.4:2201" 9333 9334 Specifying a port is 9335 useful when SSH is started on a non-standard port or in cases when 9336 your hardware under test is behind a firewall or network that is not 9337 directly accessible from your host and you need to do port address 9338 translation. 9339 9340 :term:`TESTIMAGE_AUTO` 9341 Automatically runs the series of automated tests for images when an 9342 image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes 9343 any image that successfully builds to automatically boot under QEMU. 9344 Using the variable also adds in dependencies so that any SDK for 9345 which testing is requested is automatically built first. 9346 9347 These tests are written in Python making use of the ``unittest`` 9348 module, and the majority of them run commands on the target system 9349 over ``ssh``. You can set this variable to "1" in your ``local.conf`` 9350 file in the :term:`Build Directory` to have the 9351 OpenEmbedded build system automatically run these tests after an 9352 image successfully builds: 9353 9354 TESTIMAGE_AUTO = "1" 9355 9356 For more information 9357 on enabling, running, and writing these tests, see the 9358 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" 9359 section in the Yocto Project Development Tasks Manual and the 9360 ":ref:`ref-classes-testimage`" section. 9361 9362 :term:`TESTIMAGE_FAILED_QA_ARTIFACTS` 9363 When using the :ref:`ref-classes-testimage` class, the variable 9364 :term:`TESTIMAGE_FAILED_QA_ARTIFACTS` lists space-separated paths on the 9365 target to retrieve onto the host. 9366 9367 :term:`THISDIR` 9368 The directory in which the file BitBake is currently parsing is 9369 located. Do not manually set this variable. 9370 9371 :term:`TIME` 9372 The time the build was started. Times appear using the hour, minute, 9373 and second (HMS) format (e.g. "140159" for one minute and fifty-nine 9374 seconds past 1400 hours). 9375 9376 :term:`TMPDIR` 9377 This variable is the base directory the OpenEmbedded build system 9378 uses for all build output and intermediate files (other than the 9379 shared state cache). By default, the :term:`TMPDIR` variable points to 9380 ``tmp`` within the :term:`Build Directory`. 9381 9382 If you want to establish this directory in a location other than the 9383 default, you can uncomment and edit the following statement in the 9384 ``conf/local.conf`` file in the :term:`Source Directory`:: 9385 9386 #TMPDIR = "${TOPDIR}/tmp" 9387 9388 An example use for this scenario is to set :term:`TMPDIR` to a local disk, 9389 which does not use NFS, while having the :term:`Build Directory` use NFS. 9390 9391 The filesystem used by :term:`TMPDIR` must have standard filesystem 9392 semantics (i.e. mixed-case files are unique, POSIX file locking, and 9393 persistent inodes). Due to various issues with NFS and bugs in some 9394 implementations, NFS does not meet this minimum requirement. 9395 Consequently, :term:`TMPDIR` cannot be on NFS. 9396 9397 :term:`TOOLCHAIN_HOST_TASK` 9398 This variable lists packages the OpenEmbedded build system uses when 9399 building an SDK, which contains a cross-development environment. The 9400 packages specified by this variable are part of the toolchain set 9401 that runs on the :term:`SDKMACHINE`, and each 9402 package should usually have the prefix ``nativesdk-``. For example, 9403 consider the following command when building an SDK:: 9404 9405 $ bitbake -c populate_sdk imagename 9406 9407 In this case, a default list of packages is 9408 set in this variable, but you can add additional packages to the 9409 list. See the 9410 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section 9411 in the Yocto Project Application Development and the Extensible 9412 Software Development Kit (eSDK) manual for more information. 9413 9414 For background information on cross-development toolchains in the 9415 Yocto Project development environment, see the 9416 ":ref:`sdk-manual/intro:the cross-development toolchain`" 9417 section in the Yocto Project Overview and Concepts Manual. For 9418 information on setting up a cross-development environment, see the 9419 :doc:`/sdk-manual/index` manual. 9420 9421 Note that this variable applies to building an SDK, not an eSDK, 9422 in which case the :term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be 9423 used instead. 9424 9425 :term:`TOOLCHAIN_HOST_TASK_ESDK` 9426 This variable allows to extend what is installed in the host 9427 portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK` 9428 applying to SDKs. 9429 9430 :term:`TOOLCHAIN_OPTIONS` 9431 This variable holds extra options passed to the compiler and the linker 9432 for non ``-native`` recipes as they have to point to their custom 9433 ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`:: 9434 9435 TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}" 9436 9437 Native recipes don't need this variable to be set, as they are 9438 built for the host machine with the native compiler. 9439 9440 :term:`TOOLCHAIN_OUTPUTNAME` 9441 This variable defines the name used for the toolchain output. The 9442 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets 9443 the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:: 9444 9445 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" 9446 9447 See 9448 the :term:`SDK_NAME` and 9449 :term:`SDK_VERSION` variables for additional 9450 information. 9451 9452 :term:`TOOLCHAIN_TARGET_TASK` 9453 This variable lists packages the OpenEmbedded build system uses when 9454 it creates the target part of an SDK (i.e. the part built for the 9455 target hardware), which includes libraries and headers. Use this 9456 variable to add individual packages to the part of the SDK that runs 9457 on the target. See the 9458 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section 9459 in the Yocto Project Application Development and the Extensible 9460 Software Development Kit (eSDK) manual for more information. 9461 9462 For background information on cross-development toolchains in the 9463 Yocto Project development environment, see the 9464 ":ref:`sdk-manual/intro:the cross-development toolchain`" 9465 section in the Yocto Project Overview and Concepts Manual. For 9466 information on setting up a cross-development environment, see the 9467 :doc:`/sdk-manual/index` manual. 9468 9469 :term:`TOPDIR` 9470 See :term:`bitbake:TOPDIR` in the BitBake manual. 9471 9472 :term:`TRANSLATED_TARGET_ARCH` 9473 A sanitized version of :term:`TARGET_ARCH`. This 9474 variable is used where the architecture is needed in a value where 9475 underscores are not allowed, for example within package filenames. In 9476 this case, dash characters replace any underscore characters used in 9477 :term:`TARGET_ARCH`. 9478 9479 Do not edit this variable. 9480 9481 :term:`TUNE_ARCH` 9482 The GNU canonical architecture for a specific architecture (i.e. 9483 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses 9484 this value to setup configuration. 9485 9486 :term:`TUNE_ARCH` definitions are specific to a given architecture. The 9487 definitions can be a single static definition, or can be dynamically 9488 adjusted. You can see details for a given CPU family by looking at 9489 the architecture's ``README`` file. For example, the 9490 ``meta/conf/machine/include/mips/README`` file in the 9491 :term:`Source Directory` provides information for 9492 :term:`TUNE_ARCH` specific to the ``mips`` architecture. 9493 9494 :term:`TUNE_ARCH` is tied closely to 9495 :term:`TARGET_ARCH`, which defines the target 9496 machine's architecture. The BitBake configuration file 9497 (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:: 9498 9499 TARGET_ARCH = "${TUNE_ARCH}" 9500 9501 The following list, which is by no means complete since architectures 9502 are configurable, shows supported machine architectures: 9503 9504 - arm 9505 - i586 9506 - x86_64 9507 - powerpc 9508 - powerpc64 9509 - mips 9510 - mipsel 9511 9512 :term:`TUNE_ASARGS` 9513 Specifies architecture-specific assembler flags for the target 9514 system. The set of flags is based on the selected tune features. 9515 :term:`TUNE_ASARGS` is set using the tune include files, which are 9516 typically under ``meta/conf/machine/include/`` and are influenced 9517 through :term:`TUNE_FEATURES`. For example, the 9518 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9519 for the x86 architecture as follows:: 9520 9521 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" 9522 9523 .. note:: 9524 9525 Board Support Packages (BSPs) select the tune. The selected tune, 9526 in turn, affects the tune variables themselves (i.e. the tune can 9527 supply its own set of flags). 9528 9529 :term:`TUNE_CCARGS` 9530 Specifies architecture-specific C compiler flags for the target 9531 system. The set of flags is based on the selected tune features. 9532 :term:`TUNE_CCARGS` is set using the tune include files, which are 9533 typically under ``meta/conf/machine/include/`` and are influenced 9534 through :term:`TUNE_FEATURES`. 9535 9536 .. note:: 9537 9538 Board Support Packages (BSPs) select the tune. The selected tune, 9539 in turn, affects the tune variables themselves (i.e. the tune can 9540 supply its own set of flags). 9541 9542 :term:`TUNE_FEATURES` 9543 Features used to "tune" a compiler for optimal use given a specific 9544 processor. The features are defined within the tune files and allow 9545 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on 9546 the features. 9547 9548 The OpenEmbedded build system verifies the features to be sure they 9549 are not conflicting and that they are supported. 9550 9551 The BitBake configuration file (``meta/conf/bitbake.conf``) defines 9552 :term:`TUNE_FEATURES` as follows:: 9553 9554 TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}" 9555 9556 See the :term:`DEFAULTTUNE` variable for more information. 9557 9558 :term:`TUNE_LDARGS` 9559 Specifies architecture-specific linker flags for the target system. 9560 The set of flags is based on the selected tune features. 9561 :term:`TUNE_LDARGS` is set using the tune include files, which are 9562 typically under ``meta/conf/machine/include/`` and are influenced 9563 through :term:`TUNE_FEATURES`. For example, the 9564 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9565 for the x86 architecture as follows:: 9566 9567 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" 9568 9569 .. note:: 9570 9571 Board Support Packages (BSPs) select the tune. The selected tune, 9572 in turn, affects the tune variables themselves (i.e. the tune can 9573 supply its own set of flags). 9574 9575 :term:`TUNE_PKGARCH` 9576 The package architecture understood by the packaging system to define 9577 the architecture, ABI, and tuning of output packages. The specific 9578 tune is defined using the "_tune" override as follows:: 9579 9580 TUNE_PKGARCH:tune-tune = "tune" 9581 9582 These tune-specific package architectures are defined in the machine 9583 include files. Here is an example of the "core2-32" tuning as used in 9584 the ``meta/conf/machine/include/x86/tune-core2.inc`` file:: 9585 9586 TUNE_PKGARCH:tune-core2-32 = "core2-32" 9587 9588 :term:`TUNECONFLICTS[feature]` 9589 Specifies CPU or Application Binary Interface (ABI) tuning features 9590 that conflict with feature. 9591 9592 Known tuning conflicts are specified in the machine include files in 9593 the :term:`Source Directory`. Here is an example from 9594 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file 9595 that lists the "o32" and "n64" features as conflicting with the "n32" 9596 feature:: 9597 9598 TUNECONFLICTS[n32] = "o32 n64" 9599 9600 :term:`TUNEVALID[feature]` 9601 Specifies a valid CPU or Application Binary Interface (ABI) tuning 9602 feature. The specified feature is stored as a flag. Valid features 9603 are specified in the machine include files (e.g. 9604 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example 9605 from that file:: 9606 9607 TUNEVALID[bigendian] = "Enable big-endian mode." 9608 9609 See the machine include files in the :term:`Source Directory` 9610 for these features. 9611 9612 :term:`UBOOT_BINARY` 9613 Specifies the name of the binary build by U-Boot. 9614 9615 :term:`UBOOT_CONFIG` 9616 Configures one or more U-Boot configurations to build. Each 9617 configuration can define the :term:`UBOOT_MACHINE` and optionally the 9618 :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`. 9619 9620 Here is an example from the ``meta-freescale`` layer. :: 9621 9622 UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor" 9623 UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig" 9624 UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig,,u-boot-with-spl-pbl.bin" 9625 UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin" 9626 UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig" 9627 UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig" 9628 UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig" 9629 UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig,,u-boot-with-spl-pbl.bin" 9630 9631 In this example, all possible seven configurations are selected. Each 9632 configuration specifies "..._defconfig" as :term:`UBOOT_MACHINE`, and 9633 the "sd..." configurations define an individual name for 9634 :term:`UBOOT_BINARY`. No configuration defines a second parameter for 9635 :term:`IMAGE_FSTYPES` to use for the U-Boot image. 9636 9637 For more information on how the :term:`UBOOT_CONFIG` is handled, see the 9638 :ref:`ref-classes-uboot-config` class. 9639 9640 :term:`UBOOT_DTB_LOADADDRESS` 9641 Specifies the load address for the dtb image used by U-Boot. During FIT 9642 image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in 9643 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be 9644 used in creating the dtb sections of Image Tree Source for the FIT image. 9645 9646 :term:`UBOOT_DTBO_LOADADDRESS` 9647 Specifies the load address for the dtbo image used by U-Boot. During FIT 9648 image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in 9649 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be 9650 used in creating the dtbo sections of Image Tree Source for the FIT image. 9651 9652 :term:`UBOOT_ENTRYPOINT` 9653 Specifies the entry point for the U-Boot image. During U-Boot image 9654 creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a 9655 command-line parameter to the ``uboot-mkimage`` utility. 9656 9657 To pass a 64 bit address for FIT image creation, you will need to set: 9658 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. 9659 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. 9660 9661 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9662 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, 9663 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9664 classes. 9665 9666 :term:`UBOOT_FIT_ADDRESS_CELLS` 9667 Specifies the value of the ``#address-cells`` value for the 9668 description of the U-Boot FIT image. 9669 9670 The default value is set to "1" by the :ref:`ref-classes-uboot-sign` 9671 class, which corresponds to 32 bit addresses. 9672 9673 For platforms that need to set 64 bit addresses in 9674 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to 9675 set this value to "2", as two 32 bit values (cells) will be needed 9676 to represent such addresses. 9677 9678 Here is an example setting "0x400000000" as a load address:: 9679 9680 UBOOT_FIT_ADDRESS_CELLS = "2" 9681 UBOOT_LOADADDRESS= "0x04 0x00000000" 9682 9683 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. 9684 9685 :term:`UBOOT_FIT_DESC` 9686 Specifies the description string encoded into a U-Boot fitImage. The default 9687 value is set by the :ref:`ref-classes-uboot-sign` class as follows:: 9688 9689 UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" 9690 9691 :term:`UBOOT_FIT_GENERATE_KEYS` 9692 Decides whether to generate the keys for signing the U-Boot fitImage if 9693 they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`. 9694 The default value is "0". 9695 9696 Enable this as follows:: 9697 9698 UBOOT_FIT_GENERATE_KEYS = "1" 9699 9700 This variable is used in the :ref:`ref-classes-uboot-sign` class. 9701 9702 :term:`UBOOT_FIT_HASH_ALG` 9703 Specifies the hash algorithm used in creating the U-Boot FIT Image. 9704 It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign` 9705 class. 9706 9707 :term:`UBOOT_FIT_KEY_GENRSA_ARGS` 9708 Arguments to ``openssl genrsa`` for generating a RSA private key for 9709 signing the U-Boot FIT image. The default value of this variable 9710 is set to "-F4" by the :ref:`ref-classes-uboot-sign` class. 9711 9712 :term:`UBOOT_FIT_KEY_REQ_ARGS` 9713 Arguments to ``openssl req`` for generating a certificate for signing 9714 the U-Boot FIT image. The default value is "-batch -new" by the 9715 :ref:`ref-classes-uboot-sign` class, "batch" for 9716 non interactive mode and "new" for generating new keys. 9717 9718 :term:`UBOOT_FIT_KEY_SIGN_PKCS` 9719 Format for the public key certificate used for signing the U-Boot FIT 9720 image. The default value is set to "x509" by the 9721 :ref:`ref-classes-uboot-sign` class. 9722 9723 :term:`UBOOT_FIT_SIGN_ALG` 9724 Specifies the signature algorithm used in creating the U-Boot FIT Image. 9725 This variable is set by default to "rsa2048" by the 9726 :ref:`ref-classes-uboot-sign` class. 9727 9728 :term:`UBOOT_FIT_SIGN_NUMBITS` 9729 Size of the private key used in signing the U-Boot FIT image, in number 9730 of bits. The default value for this variable is set to "2048" 9731 by the :ref:`ref-classes-uboot-sign` class. 9732 9733 :term:`UBOOT_FITIMAGE_ENABLE` 9734 This variable allows to generate a FIT image for U-Boot, which is one 9735 of the ways to implement a verified boot process. 9736 9737 Its default value is "0", so set it to "1" to enable this functionality:: 9738 9739 UBOOT_FITIMAGE_ENABLE = "1" 9740 9741 See the :ref:`ref-classes-uboot-sign` class for details. 9742 9743 :term:`UBOOT_LOADADDRESS` 9744 Specifies the load address for the U-Boot image. During U-Boot image 9745 creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a 9746 command-line parameter to the ``uboot-mkimage`` utility. 9747 9748 To pass a 64 bit address, you will also need to set: 9749 9750 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. 9751 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. 9752 9753 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9754 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, 9755 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9756 classes. 9757 9758 :term:`UBOOT_LOCALVERSION` 9759 Appends a string to the name of the local version of the U-Boot 9760 image. For example, assuming the version of the U-Boot image built 9761 was "2013.10", the full version string reported by U-Boot would be 9762 "2013.10-yocto" given the following statement:: 9763 9764 UBOOT_LOCALVERSION = "-yocto" 9765 9766 :term:`UBOOT_MACHINE` 9767 Specifies the value passed on the ``make`` command line when building 9768 a U-Boot image. The value indicates the target platform 9769 configuration. You typically set this variable from the machine 9770 configuration file (i.e. ``conf/machine/machine_name.conf``). 9771 9772 Please see the "Selection of Processor Architecture and Board Type" 9773 section in the U-Boot README for valid values for this variable. 9774 9775 :term:`UBOOT_MAKE_TARGET` 9776 Specifies the target called in the ``Makefile``. The default target 9777 is "all". 9778 9779 :term:`UBOOT_MKIMAGE` 9780 Specifies the name of the mkimage command as used by the 9781 :ref:`ref-classes-kernel-fitimage` class to assemble 9782 the FIT image. This can be used to substitute an alternative command, wrapper 9783 script or function if desired. The default is "uboot-mkimage". 9784 9785 :term:`UBOOT_MKIMAGE_DTCOPTS` 9786 Options for the device tree compiler passed to ``mkimage -D`` feature 9787 while creating a FIT image with the :ref:`ref-classes-kernel-fitimage` 9788 class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the 9789 :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option 9790 to ``mkimage``. 9791 9792 This variable is also used by the :ref:`ref-classes-uboot-sign` class. 9793 9794 :term:`UBOOT_MKIMAGE_KERNEL_TYPE` 9795 Specifies the type argument for the kernel as passed to ``uboot-mkimage``. 9796 The default value is "kernel". 9797 9798 :term:`UBOOT_MKIMAGE_SIGN` 9799 Specifies the name of the mkimage command as used by the 9800 :ref:`ref-classes-kernel-fitimage` class to sign 9801 the FIT image after it has been assembled (if enabled). This can be used 9802 to substitute an alternative command, wrapper script or function if 9803 desired. The default is "${:term:`UBOOT_MKIMAGE`}". 9804 9805 :term:`UBOOT_MKIMAGE_SIGN_ARGS` 9806 Optionally specifies additional arguments for the 9807 :ref:`ref-classes-kernel-fitimage` class to pass to the 9808 mkimage command when signing the FIT image. 9809 9810 :term:`UBOOT_RD_ENTRYPOINT` 9811 Specifies the entrypoint for the RAM disk image. During FIT image 9812 creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in 9813 :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be 9814 used in creating the Image Tree Source for the FIT image. 9815 9816 :term:`UBOOT_RD_LOADADDRESS` 9817 Specifies the load address for the RAM disk image. During FIT image 9818 creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in 9819 :ref:`ref-classes-kernel-fitimage` class to specify the load address to 9820 be used in creating the Image Tree Source for the FIT image. 9821 9822 :term:`UBOOT_SIGN_ENABLE` 9823 Enable signing of FIT image. The default value is "0". 9824 9825 This variable is used by the :ref:`ref-classes-kernel-fitimage`, 9826 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` 9827 classes. 9828 9829 :term:`UBOOT_SIGN_KEYDIR` 9830 Location of the directory containing the RSA key and certificate used for 9831 signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and 9832 :ref:`ref-classes-uboot-sign` classes. 9833 9834 :term:`UBOOT_SIGN_KEYNAME` 9835 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class 9836 for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR` 9837 directory. If we have for example a ``dev.key`` key and a ``dev.crt`` 9838 certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will 9839 have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``. 9840 9841 :term:`UBOOT_SUFFIX` 9842 Points to the generated U-Boot extension. For example, ``u-boot.sb`` 9843 has a ``.sb`` extension. 9844 9845 The default U-Boot extension is ``.bin`` 9846 9847 :term:`UBOOT_TARGET` 9848 Specifies the target used for building U-Boot. The target is passed 9849 directly as part of the "make" command (e.g. SPL and AIS). If you do 9850 not specifically set this variable, the OpenEmbedded build process 9851 passes and uses "all" for the target during the U-Boot building 9852 process. 9853 9854 :term:`UKIFY_CMD` 9855 When inheriting the :ref:`ref-classes-uki` class, 9856 `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build 9857 `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 9858 Defaults to ``ukify build``. 9859 9860 :term:`UKI_CMDLINE` 9861 When inheriting the :ref:`ref-classes-uki` class, the kernel command line 9862 to use when booting the `Unified Kernel Image (UKI) 9863 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 9864 Defaults to ``rootwait root=LABEL=root console=${KERNEL_CONSOLE}``. 9865 9866 :term:`UKI_CONFIG_FILE` 9867 When inheriting the :ref:`ref-classes-uki` class, an optional config 9868 file for the `ukify 9869 <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ 9870 command. 9871 9872 :term:`UKI_FILENAME` 9873 When inheriting the :ref:`ref-classes-uki` class, the output file name 9874 for the generated `Unified Kernel Image (UKI) 9875 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 9876 Defaults to ``uki.efi``. 9877 9878 :term:`UKI_KERNEL_FILENAME` 9879 When inheriting the :ref:`ref-classes-uki` class, the kernel image file 9880 name to use as input. Defaults to :term:`KERNEL_IMAGETYPE`. 9881 9882 :term:`UKI_SB_CERT` 9883 When inheriting the :ref:`ref-classes-uki` class, optional UEFI 9884 secureboot certificate matching the private key in :term:`UKI_SB_KEY`. 9885 9886 :term:`UKI_SB_KEY` 9887 When inheriting the :ref:`ref-classes-uki` class, optional UEFI 9888 secureboot private key to sign the `Unified Kernel Image (UKI) 9889 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__. 9890 9891 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` 9892 Specifies a list of options that, if reported by the configure script 9893 as being invalid, should not generate a warning during the 9894 :ref:`ref-tasks-configure` task. Normally, invalid 9895 configure options are simply not passed to the configure script (e.g. 9896 should be removed from :term:`EXTRA_OECONF` or 9897 :term:`PACKAGECONFIG_CONFARGS`). 9898 However, there are common options that are passed to all 9899 configure scripts at a class level, but might not be valid for some 9900 configure scripts. Therefore warnings about these options are useless. 9901 For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`. 9902 9903 The configure arguments check that uses 9904 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the 9905 :ref:`ref-classes-insane` class and is only enabled if the 9906 recipe inherits the :ref:`ref-classes-autotools` class. 9907 9908 :term:`UNPACKDIR` 9909 This variable, used by the :ref:`ref-classes-base` class, 9910 specifies where fetches sources should be unpacked by the 9911 :ref:`ref-tasks-unpack` task. 9912 9913 :term:`UPDATERCPN` 9914 For recipes inheriting the 9915 :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN` 9916 specifies the package that contains the initscript that is enabled. 9917 9918 The default value is "${PN}". Given that almost all recipes that 9919 install initscripts package them in the main package for the recipe, 9920 you rarely need to set this variable in individual recipes. 9921 9922 :term:`UPSTREAM_CHECK_COMMITS` 9923 You can perform a per-recipe check for what the latest upstream 9924 source code version is by calling ``devtool latest-version recipe``. If 9925 the recipe source code is provided from Git repositories, but 9926 releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS` 9927 to ``1`` in the recipe, and the OpenEmbedded build system 9928 will compare the latest commit with the one currently specified 9929 by the recipe (:term:`SRCREV`):: 9930 9931 UPSTREAM_CHECK_COMMITS = "1" 9932 9933 :term:`UPSTREAM_CHECK_GITTAGREGEX` 9934 You can perform a per-recipe check for what the latest upstream 9935 source code version is by calling ``devtool latest-version recipe``. If 9936 the recipe source code is provided from Git repositories, the 9937 OpenEmbedded build system determines the latest upstream version by 9938 picking the latest tag from the list of all repository tags. 9939 9940 You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a 9941 regular expression to filter only the relevant tags should the 9942 default filter not work correctly:: 9943 9944 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" 9945 9946 :term:`UPSTREAM_CHECK_REGEX` 9947 Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different 9948 regular expression instead of the default one when the package 9949 checking system is parsing the page found using 9950 :term:`UPSTREAM_CHECK_URI`:: 9951 9952 UPSTREAM_CHECK_REGEX = "package_regex" 9953 9954 :term:`UPSTREAM_CHECK_URI` 9955 You can perform a per-recipe check for what the latest upstream 9956 source code version is by calling ``devtool latest-version recipe``. If 9957 the source code is provided from tarballs, the latest version is 9958 determined by fetching the directory listing where the tarball is and 9959 attempting to find a later tarball. When this approach does not work, 9960 you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that 9961 contains the link to the latest tarball:: 9962 9963 UPSTREAM_CHECK_URI = "recipe_url" 9964 9965 :term:`UPSTREAM_VERSION_UNKNOWN` 9966 You can perform a per-recipe check for what the latest upstream 9967 source code version is by calling ``devtool latest-version recipe``. 9968 If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`, 9969 :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in 9970 the recipe allows to determine what the latest upstream version is, 9971 you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe 9972 to acknowledge that the check cannot be performed:: 9973 9974 UPSTREAM_VERSION_UNKNOWN = "1" 9975 9976 :term:`USE_DEVFS` 9977 Determines if ``devtmpfs`` is used for ``/dev`` population. The 9978 default value used for :term:`USE_DEVFS` is "1" when no value is 9979 specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a 9980 statically populated ``/dev`` directory. 9981 9982 See the ":ref:`dev-manual/device-manager:selecting a device manager`" section in 9983 the Yocto Project Development Tasks Manual for information on how to 9984 use this variable. 9985 9986 :term:`USE_VT` 9987 When using 9988 :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, 9989 determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>` 9990 on any virtual terminals in order to enable logging in through those 9991 terminals. 9992 9993 The default value used for :term:`USE_VT` is "1" when no default value is 9994 specifically set. Typically, you would set :term:`USE_VT` to "0" in the 9995 machine configuration file for machines that do not have a graphical 9996 display attached and therefore do not need virtual terminal 9997 functionality. 9998 9999 :term:`USER_CLASSES` 10000 A list of classes to globally inherit. These classes are used by the 10001 OpenEmbedded build system to enable extra features. 10002 10003 Classes inherited using :term:`USER_CLASSES` must be located in the 10004 ``classes-global/`` or ``classes/`` subdirectories. 10005 10006 The default list is set in your ``local.conf`` file:: 10007 10008 USER_CLASSES ?= "buildstats" 10009 10010 For more information, see 10011 ``meta-poky/conf/templates/default/local.conf.sample`` in the 10012 :term:`Source Directory`. 10013 10014 :term:`USERADD_DEPENDS` 10015 Specifies a list of recipes that create users / groups (via 10016 :term:`USERADD_PARAM` / :term:`GROUPADD_PARAM`) which a recipe 10017 depends upon. This ensures that those users / groups are available 10018 when building a recipe. 10019 10020 :term:`USERADD_ERROR_DYNAMIC` 10021 If set to ``error``, forces the OpenEmbedded build system to produce 10022 an error if the user identification (``uid``) and group 10023 identification (``gid``) values are not defined in any of the files 10024 listed in :term:`USERADD_UID_TABLES` and 10025 :term:`USERADD_GID_TABLES`. If set to 10026 ``warn``, a warning will be issued instead. 10027 10028 The default behavior for the build system is to dynamically apply 10029 ``uid`` and ``gid`` values. Consequently, the 10030 :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan 10031 on using statically assigned ``gid`` and ``uid`` values, you should 10032 set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` 10033 file as follows:: 10034 10035 USERADD_ERROR_DYNAMIC = "error" 10036 10037 Overriding the 10038 default behavior implies you are going to also take steps to set 10039 static ``uid`` and ``gid`` values through use of the 10040 :term:`USERADDEXTENSION`, 10041 :term:`USERADD_UID_TABLES`, and 10042 :term:`USERADD_GID_TABLES` variables. 10043 10044 .. note:: 10045 10046 There is a difference in behavior between setting 10047 :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``. 10048 When it is set to ``warn``, the build system will report a warning for 10049 every undefined ``uid`` and ``gid`` in any recipe. But when it is set 10050 to ``error``, it will only report errors for recipes that are actually 10051 built. 10052 This saves you from having to add static IDs for recipes that you 10053 know will never be built. 10054 10055 :term:`USERADD_GID_TABLES` 10056 Specifies a password file to use for obtaining static group 10057 identification (``gid``) values when the OpenEmbedded build system 10058 adds a group to the system during package installation. 10059 10060 When applying static group identification (``gid``) values, the 10061 OpenEmbedded build system looks in :term:`BBPATH` for a 10062 ``files/group`` file and then applies those ``uid`` values. Set the 10063 variable as follows in your ``local.conf`` file:: 10064 10065 10066 USERADD_GID_TABLES = "files/group" 10067 10068 .. note:: 10069 10070 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" 10071 causes the build system to use static ``gid`` values. 10072 10073 :term:`USERADD_PACKAGES` 10074 When inheriting the :ref:`ref-classes-useradd` class, 10075 this variable specifies the individual packages within the recipe 10076 that require users and/or groups to be added. 10077 10078 You must set this variable if the recipe inherits the class. For 10079 example, the following enables adding a user for the main package in 10080 a recipe:: 10081 10082 USERADD_PACKAGES = "${PN}" 10083 10084 .. note:: 10085 10086 It follows that if you are going to use the :term:`USERADD_PACKAGES` 10087 variable, you need to set one or more of the :term:`USERADD_PARAM`, 10088 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. 10089 10090 :term:`USERADD_PARAM` 10091 When inheriting the :ref:`ref-classes-useradd` class, 10092 this variable specifies for a package what parameters should pass to 10093 the ``useradd`` command if you add a user to the system when the 10094 package is installed. 10095 10096 Here is an example from the ``dbus`` recipe:: 10097 10098 USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \ 10099 --no-create-home --shell /bin/false \ 10100 --user-group messagebus" 10101 10102 For information on the 10103 standard Linux shell command ``useradd``, see 10104 https://linux.die.net/man/8/useradd. 10105 10106 :term:`USERADD_UID_TABLES` 10107 Specifies a password file to use for obtaining static user 10108 identification (``uid``) values when the OpenEmbedded build system 10109 adds a user to the system during package installation. 10110 10111 When applying static user identification (``uid``) values, the 10112 OpenEmbedded build system looks in :term:`BBPATH` for a 10113 ``files/passwd`` file and then applies those ``uid`` values. Set the 10114 variable as follows in your ``local.conf`` file:: 10115 10116 USERADD_UID_TABLES = "files/passwd" 10117 10118 .. note:: 10119 10120 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" 10121 causes the build system to use static ``uid`` values. 10122 10123 :term:`USERADDEXTENSION` 10124 When set to "useradd-staticids", causes the OpenEmbedded build system 10125 to base all user and group additions on a static ``passwd`` and 10126 ``group`` files found in :term:`BBPATH`. 10127 10128 To use static user identification (``uid``) and group identification 10129 (``gid``) values, set the variable as follows in your ``local.conf`` 10130 file: USERADDEXTENSION = "useradd-staticids" 10131 10132 .. note:: 10133 10134 Setting this variable to use static ``uid`` and ``gid`` 10135 values causes the OpenEmbedded build system to employ the 10136 :ref:`ref-classes-useradd` class. 10137 10138 If you use static ``uid`` and ``gid`` information, you must also 10139 specify the ``files/passwd`` and ``files/group`` files by setting the 10140 :term:`USERADD_UID_TABLES` and 10141 :term:`USERADD_GID_TABLES` variables. 10142 Additionally, you should also set the 10143 :term:`USERADD_ERROR_DYNAMIC` variable. 10144 10145 :term:`VIRTUAL-RUNTIME` 10146 :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual 10147 packages for runtime usage, typically for use in :term:`RDEPENDS` 10148 or in image definitions. 10149 10150 An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible 10151 to either use BusyBox based utilities:: 10152 10153 VIRTUAL-RUNTIME_base-utils = "busybox" 10154 10155 or their full featured implementations from GNU Coreutils 10156 and other projects:: 10157 10158 VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils" 10159 10160 Here are two examples using this virtual runtime package. The 10161 first one is in :yocto_git:`initramfs-framework_1.0.bb 10162 </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`:: 10163 10164 RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}" 10165 10166 The second example is in the :yocto_git:`core-image-initramfs-boot 10167 </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>` 10168 image definition:: 10169 10170 PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd" 10171 10172 :term:`WARN_QA` 10173 Specifies the quality assurance checks whose failures are reported as 10174 warnings by the OpenEmbedded build system. You set this variable in 10175 your distribution configuration file. For a list of the checks you 10176 can control with this variable, see the 10177 ":ref:`ref-classes-insane`" section. 10178 10179 :term:`WATCHDOG_TIMEOUT` 10180 Specifies the timeout in seconds used by the ``watchdog`` recipe and 10181 also by ``systemd`` during reboot. The default is 60 seconds. 10182 10183 :term:`WIRELESS_DAEMON` 10184 For ``connman`` and ``packagegroup-base``, specifies the wireless 10185 daemon to use. The default is "wpa-supplicant" (note that the value 10186 uses a dash and not an underscore). 10187 10188 :term:`WKS_FILE` 10189 Specifies the location of the Wic kickstart file that is used by the 10190 OpenEmbedded build system to create a partitioned image 10191 (``image.wic``). For information on how to create a partitioned 10192 image, see the 10193 ":ref:`dev-manual/wic:creating partitioned images using wic`" 10194 section in the Yocto Project Development Tasks Manual. For details on 10195 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. 10196 10197 :term:`WKS_FILE_DEPENDS` 10198 When placed in the recipe that builds your image, this variable lists 10199 build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only 10200 applicable when Wic images are active (i.e. when 10201 :term:`IMAGE_FSTYPES` contains entries related 10202 to Wic). If your recipe does not create Wic images, the variable has 10203 no effect. 10204 10205 The :term:`WKS_FILE_DEPENDS` variable is similar to the 10206 :term:`DEPENDS` variable. When you use the variable in 10207 your recipe that builds the Wic image, dependencies you list in the 10208 :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable. 10209 10210 With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to 10211 specify a list of additional dependencies (e.g. native tools, 10212 bootloaders, and so forth), that are required to build Wic images. 10213 Here is an example:: 10214 10215 WKS_FILE_DEPENDS = "some-native-tool" 10216 10217 In the 10218 previous example, some-native-tool would be replaced with an actual 10219 native tool on which the build would depend. 10220 10221 :term:`WKS_FILES` 10222 Specifies a list of candidate Wic kickstart files to be used by the 10223 OpenEmbedded build system to create a partitioned image. Only the 10224 first one that is found, from left to right, will be used. 10225 10226 This is only useful when there are multiple ``.wks`` files that can be 10227 used to produce an image. A typical case is when multiple layers are 10228 used for different hardware platforms, each supplying a different 10229 ``.wks`` file. In this case, you specify all possible ones through 10230 :term:`WKS_FILES`. 10231 10232 If only one ``.wks`` file is used, set :term:`WKS_FILE` instead. 10233 10234 :term:`WORKDIR` 10235 The pathname of the work directory in which the OpenEmbedded build 10236 system builds a recipe. This directory is located within the 10237 :term:`TMPDIR` directory structure and is specific to 10238 the recipe being built and the system for which it is being built. 10239 10240 The :term:`WORKDIR` directory is defined as follows:: 10241 10242 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} 10243 10244 The actual directory depends on several things: 10245 10246 - :term:`TMPDIR`: The top-level build output directory 10247 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier 10248 - :term:`PN`: The recipe name 10249 - :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which 10250 is usually the case for most recipes, then :term:`EXTENDPE` is blank. 10251 - :term:`PV`: The recipe version 10252 - :term:`PR`: The recipe revision 10253 10254 As an example, assume a Source Directory top-level folder name 10255 ``poky``, a default :term:`Build Directory` at ``poky/build``, and a 10256 ``qemux86-poky-linux`` machine target system. Furthermore, suppose 10257 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work 10258 directory the build system uses to build the package would be as 10259 follows:: 10260 10261 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 10262 10263 :term:`XSERVER` 10264 Specifies the packages that should be installed to provide an X 10265 server and drivers for the current machine, assuming your image 10266 directly includes ``packagegroup-core-x11-xserver`` or, perhaps 10267 indirectly, includes "x11-base" in 10268 :term:`IMAGE_FEATURES`. 10269 10270 The default value of :term:`XSERVER`, if not specified in the machine 10271 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". 10272 10273 :term:`XZ_THREADS` 10274 Specifies the number of parallel threads that should be used when 10275 using xz compression. 10276 10277 By default this scales with core count, but is never set less than 2 10278 to ensure that multi-threaded mode is always used so that the output 10279 file contents are deterministic. Builds will work with a value of 1 10280 but the output will differ compared to the output from the compression 10281 generated when more than one thread is used. 10282 10283 On systems where many tasks run in parallel, setting a limit to this 10284 can be helpful in controlling system resource usage. 10285 10286 :term:`XZ_MEMLIMIT` 10287 Specifies the maximum memory the xz compression should use as a percentage 10288 of system memory. If unconstrained the xz compressor can use large amounts of 10289 memory and become problematic with parallelism elsewhere in the build. 10290 "50%" has been found to be a good value. 10291 10292 :term:`ZSTD_COMPRESSION_LEVEL` 10293 Specifies the compression level to be used with ZStandard compression 10294 (from ``1`` to ``19``, set to ``3`` by default, following upstream choice). 10295 Higher levels produce smaller files, but take longer to complete. 10296 10297 :term:`ZSTD_THREADS` 10298 Specifies the number of parallel threads that should be used when 10299 using ZStandard compression. 10300 10301 By default this scales with core count, but is never set less than 2 10302 to ensure that multi-threaded mode is always used so that the output 10303 file contents are deterministic. Builds will work with a value of 1 10304 but the output will differ compared to the output from the compression 10305 generated when more than one thread is used. 10306 10307 On systems where many tasks run in parallel, setting a limit to this 10308 can be helpful in controlling system resource usage. 10309
