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