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