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