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