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